Bijection React

Bijection React is the client library enabling your React application to interact with your Bijection backend. It allows your frontend code to:

Call your queries, mutations and actions
Upload and display files from File Storage
Authenticate users using Authentication
Implement full text Search over your data

The Bijection React client is open source and available on GitHub. Follow the React Quickstart to get started with React using Vite.

Installation

Bijection React is part of the bijection SDK package, as bijection/react. bijection init --template react-vite creates a React app with it installed. The Bijection SDK (bijection/react, bijection/browser, …) is not published to the npm registry. Your app declares it as a tarball from bijection.com, for the version of your CLI (bijection --version prints it). Add this line to the dependencies in your app’s package.json:

package.json

"bijection": "https://bijection.com/sdk/bijection-0.1.1.tgz"

Then install your app’s dependencies with its package manager as usual (for example npm install). The react-vite and nextjs templates of bijection init write this line and run the install for you.

Connecting to a backend

The BijectionReactClient maintains a connection to your Bijection backend, and is used by the React hooks described below to call your functions. First you need to create an instance of the client by giving it your backend deployment URL. See Configuring Deployment URL on how to pass in the right value:

import { BijectionProvider, BijectionReactClient } from "bijection/react";

const bijection = new BijectionReactClient("https://<your domain here>.bijection.cloud");

And then you make the client available to your app by passing it in to a BijectionProvider wrapping your component tree:

reactDOMRoot.render(
  <React.StrictMode>
    <BijectionProvider client={bijection}>
      <App />
    </BijectionProvider>
  </React.StrictMode>,
);

Fetching data

Your React app fetches data using the useQuery React hook by calling your queries via an api object. The bijection dev command generates this api object for you in the bijection/_generated/api.js module to provide better autocompletion in JavaScript and end-to-end type safety in TypeScript:

src/App.tsx

import { useQuery } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const data = useQuery(api.functions.myQuery);
  return data ?? "Loading...";
}

The useQuery hook returns undefined while the data is first loading and afterwards the return value of your query.

Query arguments

Arguments to your query follow the query name:

src/App.tsx

export function App() {
  const a = "Hello world";
  const b = 4;
  const data = useQuery(api.functions.myQuery, { a, b });
  //...
}

Reactivity

The useQuery hook makes your app automatically reactive: when the underlying data changes in your database, your component rerenders with the new query result. The first time the hook is used it creates a subscription to your backend for a given query and any arguments you pass in. When your component unmounts, the subscription is canceled.

Consistency

Bijection React ensures that your application always renders a consistent view of the query results based on a single state of the underlying database. Imagine a mutation changes some data in the database, and that 2 different useQuery call sites rely on this data. Your app will never render in an inconsistent state where only one of the useQuery call sites reflects the new data.

Experimental: query result object

If you want a richer result object to handle when querying, try useQuery_experimental. It always returns an object with a status field, and does not throw errors by default. The status of the result object will be one of "pending" | "success" | "error". To help ensure correct handling of query results, the return type requires that you check the status before accessing other fields (data or error).

src/App.tsx

import { useQuery_experimental as useQuery } from "bijection/react";
import { api } from "../bijection/_generated/api";

function TaskList() {
  const result = useQuery({
    query: api.tasks.list,
    args: { completed: false },
  });

  if (result.status === "pending") return <div>Loading...</div>;
  if (result.status === "error")
    return <div>Error: {result.error.message}</div>;
  // `status` guaranteed to be `"success"` at this point; `data` available.
  return result.data.map((task) => <div key={task._id}>{task.text}</div>);
}

If you’re migrating existing code that leverages error boundaries, you can use the throwOnError: true option to maintain that behavior.

Paginating queries

See Paginating within React Components.

Skipping queries

Advanced: Loading a query conditionally

With React it can be tricky to dynamically invoke a hook, because hooks cannot be placed inside conditionals or after early returns:

import { useQuery } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  // the URL `param` might be null
  const param = new URLSearchParams(window.location.search).get("param");
  // ERROR! React Hook "useQuery" is called conditionally. React Hooks must
  // be called in the exact same order in every component render.
  const data = param !== null ? useQuery(api.functions.read, { param }) : null;
  //...
}

For this reason useQuery can be “disabled” by passing in "skip" instead of its arguments:

import { useQuery } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const param = new URLSearchParams(window.location.search).get("param");
  const data = useQuery(
    api.functions.read,
    param !== null ? { param } : "skip",
  );
  //...
}

When "skip" is used the useQuery doesn’t talk to your backend at all and returns undefined.

One-off queries

Advanced: Fetching a query from a callback

Sometimes you might want to read state from the database in response to a user action, for example to validate given input, without making any changes to the database. In this case you can use a one-off query call, similarly to calling mutations and actions.The async method query is exposed on the BijectionReactClient, which you can reference in your components via the useBijection() hook.

import { useBijection } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const bijection = useBijection();
  return (
    <button
      onClick={async () => {
        console.log(await bijection.query(api.functions.myQuery));
      }}
    >
      Check
    </button>
  );
}

Editing data

Your React app edits data using the useMutation React hook by calling your mutations. The bijection dev command generates this api object for you in the bijection/_generated/api.js module to provide better autocompletion in JavaScript and end-to-end type safety in TypeScript:

src/App.tsx

import { useMutation } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const doSomething = useMutation(api.functions.doSomething);
  return <button onClick={() => doSomething()}>Click me</button>;
}

The hook returns an async function which performs the call to the mutation.

Mutation arguments

Arguments to your mutation are passed to the async function returned from useMutation:

src/App.tsx

export function App() {
  const a = "Hello world";
  const b = 4;
  const doSomething = useMutation(api.functions.doSomething);
  return <button onClick={() => doSomething({ a, b })}>Click me</button>;
}

Mutation response and error handling

The mutation can optionally return a value or throw errors, which you can await:

src/App.tsx

export function App() {
  const doSomething = useMutation(api.functions.doSomething);
  const onClick = () => {
    async function callBackend() {
      try {
        const result = await doSomething();
      } catch (error) {
        console.error(error);
      }
      console.log(result);
    }
    void callBackend();
  };
  return <button onClick={onClick}>Click me</button>;
}

Or handle as a Promise:

src/App.tsx

export function App() {
  const doSomething = useMutation(api.functions.doSomething);
  const onClick = () => {
    doSomething()
      .catch((error) => {
        console.error(error);
      })
      .then((result) => {
        console.log(result);
      });
  };
  return <button onClick={onClick}>Click me</button>;
}

Learn more about Error Handling in functions.

Retries

Bijection React automatically retries mutations until they are confirmed to have been written to the database. The Bijection backend ensures that despite multiple retries, every mutation call only executes once. Additionally, Bijection React will warn users if they try to close their browser tab while there are outstanding mutations. This means that when you call a Bijection mutation, you can be sure that the user’s edits won’t be lost.

Optimistic updates

Bijection queries are fully reactive, so all query results will be automatically updated after a mutation. Sometimes you may want to update the UI before the mutation changes propagate back to the client. To accomplish this, you can configure an optimistic update to execute as part of your mutation. Optimistic updates are temporary, local changes to your query results which are used to make your app more responsive. See Optimistic Updates on how to configure them.

Calling third-party APIs

Your React app can read data, call third-party services, and write data with a single backend call using the useAction React hook by calling your actions. Like useQuery and useMutation, this hook is used with the api object generated for you in the bijection/_generated/api.js module to provide better autocompletion in JavaScript and end-to-end type safety in TypeScript:

src/App.tsx

import { useAction } from "bijection/react";
import { api } from "../bijection/_generated/api";

export function App() {
  const doSomeAction = useAction(api.functions.doSomeAction);
  return <button onClick={() => doSomeAction()}>Click me</button>;
}

The hook returns an async function which performs the call to the action.

Action arguments

Action arguments work exactly the same as mutation arguments.

Action response and error handling

Action response and error handling work exactly the same as mutation response and error handling. Actions do not support automatic retries or optimistic updates.

Under the hood

The BijectionReactClient connects to your Bijection deployment by creating a WebSocket. The WebSocket provides a 2-way communication channel over TCP. This allows Bijection to push new query results reactively to the client without the client needing to poll for updates. If the internet connection drops, the client will handle reconnecting and re-establishing the Bijection session automatically.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Installation

Connecting to a backend

Fetching data

Query arguments

Reactivity

Consistency

Experimental: query result object

Paginating queries

Skipping queries

One-off queries

Editing data

Mutation arguments

Mutation response and error handling

Retries

Optimistic updates

Calling third-party APIs

Action arguments

Action response and error handling

Under the hood

​Installation

​Connecting to a backend

​Fetching data

​Query arguments

​Reactivity

​Consistency

​Experimental: query result object

​Paginating queries

​Skipping queries

​One-off queries

​Editing data

​Mutation arguments

​Mutation response and error handling

​Retries

​Optimistic updates

​Calling third-party APIs

​Action arguments

​Action response and error handling

​Under the hood

Installation

Connecting to a backend

Fetching data

Query arguments

Reactivity

Consistency

Experimental: query result object

Paginating queries

Skipping queries

One-off queries

Editing data

Mutation arguments

Mutation response and error handling

Retries

Optimistic updates

Calling third-party APIs

Action arguments

Action response and error handling

Under the hood