@ronin/blade

Blade

A React framework for building instant web apps.

Features

• Native Data State Management (built-in React hooks for reads and mutations)
• Native Pagination (built-in React hooks for paginating lists of records)
• Native Styling (Support for Tailwind CSS with zero config)
• Native Markdown (Support for MDX with zero config)
• Client & Server Components (code is not shipped to the client by default, unless you opt in)
• Web Standard Compliant (outputs a req/res worker + static files that run anywhere — also runs in containers)
• No Data Waterfalls (queries are collected across layouts and pages to ensure a single DB transaction)
• Instant Prod Builds (no compiler, only relies on Bun and loaders)
• Zero Config (only pages/index.tsx and package.json are needed to get Blade to run)
• Automatic REST API (Blade auto-generates a REST API at /api for you, for models that you want to expose)
• Zero Config Deployments (Vercel [ready], containers [ready], Cloudflare [ready], and more soon)

Blade works most efficiently when using RONIN — a globally replicable database powered by SQLite. Blade is and will always be usable with any other data source as well, however you will see performance drawbacks if that datasource isn't equally fast.

The first and currently largest known implementation of Blade is the RONIN dashboard (its code is currently closed, but will be opened up very soon), which has been implemented with Blade since its inception.

Considerations

Blade purposefully does not (and likely won't ever) comply with the official specification for React Server Components, because it provides different solutions to the problems that RSC aims to solve.

• No Server Functions (instead of executing arbitrary code, the only way to invoke the server in Blade is through a mutation)
• No Async Components (I/O leads to slow code, so reads in Blade are always synchronous, but async behind the scenes)
• No Suspense (Blade does not support reads on the client — server components can only read and client components can only write)

Temporary Limitation

The experimental React version defined in the examples is currently required. Support for the "stable" release channel of React will follow very soon.

Setup

To get started with Blade, first make sure you have Bun installed, which is a JavaScript runtime.

Next, create a new app with this command:

bunx @ronin/blade init

Afterward, enter the newly created directory and install the dependencies:

cd blade-example
bun install

Lastly, start the development server:

bun run dev

Deploying

In order to deploy your Blade app to production, use your deployment provider of choice. For example, you can sign up to Vercel and run this command in the directory of your Blade app to deploy it:

vercel -y

That's all. The command will create the Vercel project and deploy the app for you.

API

Check out the documentation for more details.

Contributing

To start contributing code, first make sure you have Bun installed, which is a JavaScript runtime.

Next, clone the repo and install its dependencies:

bun install

Once that's done, link the package to make it available to all of your local projects:

bun link

Inside your project, you can then run the following command, which is similar to bun add @ronin/blade or npm install @ronin/blade, except that it doesn't install @ronin/blade from npm, but instead uses your local clone of the package:

bun link @ronin/blade

If your project is not yet compatible with Bun, feel free to replace all of the occurrences of the word bun in the commands above with npm instead.

You will just need to make sure that, once you create a pull request on the current repo, it will not contain a package-lock.json file, which is usually generated by npm. Instead, we're using the bun.lockb file for this purpose (locking sub dependencies to a certain version).

Running Tests

Before you create a pull request on the blade repo, it is advised to run its tests in order to ensure everything works as expected:

# Run all tests
bun run test

# Alternatively, run a single test
bun run test -- -t 'your test name'