blade
Version:
React at the edge.
99 lines (65 loc) • 4.26 kB
Markdown
# Blade
[](https://github.com/ronin-co/blade/actions/workflows/validate.yml)
A [React](https://react.dev) 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](https://tailwindcss.com) with zero config)
- **Native Markdown** (Support for [MDX](https://mdxjs.com) 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** (powered by Rust, using [Rolldown](https://rolldown.rs))
- **Zero Config** (only `pages/index.tsx` and `package.json` are [needed](https://github.com/ronin-co/blade/tree/main/packages/create-blade/templates/basic) 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, Cloudflare, containers, and more)
## 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](https://blade.im/hooks#usemutation-client))
- **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)
## Setup
To get started with Blade, create a new app with this command:
```bash
npm create blade
```
Afterward, enter the newly created directory and install the dependencies:
```bash
cd blade-example
npm install
```
Lastly, start the development server:
```bash
npm 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](https://vercel.com) and run this command in the directory of your Blade app to deploy it:
```bash
vercel -y
```
That's all. The command will create the Vercel project and deploy the app for you.
## API
Check out [the documentation](https://blade.im) for more details.
## Contributing
To start contributing code, [clone the repo](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) and install its dependencies:
```bash
bun install
```
Once that's done, link the package to make it available to all of your local projects, by running the following command in the `packages/blade` directory:
```bash
bun link
```
Inside your project, you can then run the following command, which is similar to `bun add blade` or `npm install blade`, except that it doesn't install `blade` from npm, but instead uses your local clone of the package:
```bash
bun link blade
```
If your project is not yet compatible with [Bun](https://bun.sh), 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#creating-the-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:
```bash
# Run all tests
bun run test
# Alternatively, run a single test
bun run test -- -t 'your test name'
```