Introduction

Blade is a React framework for building highly dynamic web applications.

Applications built with Blade are fast across all vectors: The first load is instant, while interactions are instant too.

By following the principles of edge compute, Blade meets your users where they are, instead of making them come to you. Your application and the data of your users are pushed as close as possible to them, instead of requiring them retrieve it.

In practice, this means that loading animations of any form (spinners, skeletons, etc) are avoided, ensuring the snappiest and thereby most joyful experience for end users, similar to how a native app feels.

Data Model

The core of Blade is its query syntax, which allows for instantly reading and writing data.

It combines common data querying patterns of web apps into a syntax that is more powerful than SQL, by making it possible to express complex operations with less code, resulting in a more effective tool for web apps.

In its simplest form, reading a list of records would look like this:

const records = use.accounts();

While writing a record looks like this:

const { add } = useMutation();

add.account.with.handle('test');

This lets you focus on the user experience of your application instead of adding REST APIs, data state management libraries, React server functions, or similar.

Blade manages the state of your data for you. Any mutation you apply is instantly reflected across all read queries, and propagated to other clients in the background.

Hooks

In general, just like with the data model described above, the majority of programmatic API of Blade revolves around the concept of Hooks:

use: Read data
useMutation: Write data
useLocation: Mimics window.location
useNavigator: Mimics window.navigator
useRedirect: Change the page
useCookie: Read and write cookies
useParams: Read dynamic path segments
usePopulatePathname: Populate dynamic path segments
usePagination: Get the next/previous page of records
usePaginationBuffer: Concatenate paginated lists
useMetadata: Set the contents of <head>
useCountOf: Like use, but counts records
useBatch: Run multiple use queries at once
useLinkEvents: Applies the event handlers of the <Link> component
useQueryState: Like useState, but for URL query params

Get Started

Start building your first application with Blade by running the following command to create a new example application:

npm create blade

A new directory named blade-example will be created as a result, which contains your newly created application.

To start developing it, you can now run this command:

npm run dev

That's it! 🎉 You can now start working on your application.

Data Storage

By default, when you run Blade the first time, it will generate an SQLite database for you and place it in the .blade directory of your project. All of your data will then be persisted in that directory.

Now that your database exists, you can start defining its schema. As an example, we could add the following model (which is similar to a table in SQL):

export const Account = model({
  slug: 'account',

  fields: {
    name: string(),
  }
});

Next, you can run apply the model to your database by running this command:

blade diff --apply

Once your database schema has been updated, your can begin inserting data. For example, you could execute write queries with the useMutation hook like this:

import { useMutation } from 'blade/client/hooks';

const MyComponent = () => {
  const { add } = useMutation();

  const buttonClicked = () => {
    await add.account.with({ name: 'Elaine' });
  }

  return (
    <button onClick={buttonClicked}>Insert data</button>
  );
};

That's it! 🚀

You've successfully inserted data. As you can see when running this code (you can just run it multiple times), the add.account query returns the new record you just created.

To read the data across different pages, you could then write read queries with the use hook. In other words, useMutation handles write queries, while read queries are handled by use.

If you need any help, just let us know on our Discord server and the team will be with you immediately.

Production

While this works well during the development of your application and also for small single-region applications in production, larger applications require much more sophisticated database features.

For that purpose, you may choose to use a full data infrastructure offered by RONIN, the team behind Blade. At the moment, this infrastructure is available in its alpha release phase, which means that access tokens are currently only handed out via our Discord server. If you are interested, please feel free to join our Discord server and a RONIN team member will send you a free token with no additional obligations immediately. A interface for generating tokens will follow soon.

You will then be able to use the following two environment variables to access your production database, which is replicated to 18 regions across the globe and offers a strong consistency model.

RONIN_TOKEN=xxxxxx
RONIN_ID=xxxxxx

Once you've placed this file in the root directory of your project, Blade will automatically read it and use it to access your origin SQLite database, from which it will then automatically retrieve data as needed.

On This Page