React Quickstart

Learn how to create a React app, built with Vite, with a Bijection backend, starting from the react-vite template of bijection init.

Install the Bijection CLI

curl -fsSL https://bijection.com/install.sh | sh

If bijection is not on your PATH afterwards, add it as the installer explains. See Install Bijection.

Create the app

bijection init my-app --template react-vite

This writes a React app and its Bijection backend into my-app/, then installs the app’s dependencies, including the Bijection SDK, with your JavaScript package manager: the one of an enclosing workspace, otherwise the first of pnpm, bun, yarn and npm on your PATH. The app needs Node.js and one of them; the backend does not. Last, it generates bijection/_generated/, the typed API of your functions, so the project typechecks before it has a deployment.

my-app/
├── bijection/
│   ├── _generated/     the typed API of your functions
│   ├── messages.ts     a query and a mutation
│   ├── schema.ts       the messages table
│   └── tsconfig.json
├── src/
│   ├── App.tsx         the page that calls them
│   └── main.tsx        creates the Bijection client
├── bijection.json
├── index.html
├── package.json
└── vite.config.ts

Log this machine in to Bijection. You only do this once per machine.

cd my-app
bijection login

Bijection’s hosted service is not yet open for public sign-up, and the CLI has no default management service. Before running bijection login, set BIJECTION_MANAGEMENT_URL to the management service URL you were given, in your shell’s startup file so that every later bijection command sees it too:

export BIJECTION_MANAGEMENT_URL=https://<your management service>

Start the backend

bijection dev

The first run creates your dev deployment and writes its URL to .env.local, where the app reads it as VITE_BIJECTION_URL. bijection dev then keeps running: on every change it pushes bijection/ to your dev deployment and regenerates bijection/_generated/. Keep it running.

Start the app

In another terminal, start the app with the command bijection init printed for your package manager, for example:

npm run dev

Open http://localhost:5173/ and send a message. Open a second window: messages appear in both as soon as they are sent.

Read the backend

bijection/schema.ts declares the messages table, and bijection/messages.ts exports a query and a mutation. Each export is an API function named after the file and the export: api.messages.list and api.messages.send.

bijection/messages.ts

import { v } from "bijection/values";
import { mutation, query } from "./_generated/server";

// The 50 most recent messages, newest first.
export const list = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("messages").order("desc").take(50);
  },
});

export const send = mutation({
  args: { author: v.string(), body: v.string() },
  handler: async (ctx, args) => {
    await ctx.db.insert("messages", args);
  },
});

Read the app

src/main.tsx creates a BijectionReactClient for the deployment URL and provides it to the app with BijectionProvider:

src/main.tsx

import { BijectionProvider, BijectionReactClient } from "bijection/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

const client = new BijectionReactClient(import.meta.env.VITE_BIJECTION_URL);

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <BijectionProvider client={client}>
      <App />
    </BijectionProvider>
  </StrictMode>,
);

src/App.tsx subscribes to the query with useQuery and calls the mutation with useMutation. The query result updates by itself whenever the messages change:

src/App.tsx

const messages = useQuery(api.messages.list);
const send = useMutation(api.messages.send);

Call a function from the CLI

With the app open, send a message from another terminal. It appears in the app at once:

bijection run messages:send '{"author": "me", "body": "Hello"}'

See the complete React documentation.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference