TanStack Start Quickstart

TanStack Start is in Release CandidateTanStack Start is a new React framework currently in the Release Candidate stage. You can use it today but there may be bugs or breaking changes before a stable release.

To use an auth provider with Bijection and TanStack Start, see the TanStack Start + Clerk guide or the TanStack Start + WorkOS AuthKit guide.

Learn how to query data from Bijection in a TanStack Start site.

Install the Bijection CLI

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

See Install Bijection for PATH setup and supported platforms.

Create a TanStack Start site

Create a TanStack Start app using the create-start-app command:

npx create-start-app@latest

Add a Bijection backend

In the site’s directory, run bijection init. It adds a bijection/ folder, where you write your backend functions, with a sample schema, query and mutation, and bijection.json.

bijection init

Add the Bijection SDK and React Query packages

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.Also add the Bijection React Query integration and TanStack’s React Query packages with your package manager:

npm install @bijection/react-query @tanstack/react-router-ssr-query @tanstack/react-query

Update src/routes/__root.tsx

Add a QueryClient to the router context to make React Query usable anywhere in the TanStack Start site.

import { QueryClient } from "@tanstack/react-query";
import { createRootRouteWithContext } from "@tanstack/react-router";
import { Outlet, Scripts, HeadContent } from "@tanstack/react-router";
import * as React from "react";

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient;
}>()({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
  }),
  component: RootComponent,
});

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  );
}

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  );
}

Update src/router.tsx

Replace the file src/router.tsx with these contents.This creates a BijectionClient and a BijectionQueryClient and wires in a BijectionProvider.

import { createRouter } from "@tanstack/react-router";
import { QueryClient } from "@tanstack/react-query";
import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
import { BijectionQueryClient } from "@bijection/react-query";
import { BijectionProvider } from "bijection/react";
import { routeTree } from "./routeTree.gen";

export function getRouter() {
  const BIJECTION_URL = (import.meta as any).env.VITE_BIJECTION_URL!;
  if (!BIJECTION_URL) {
    console.error("missing envar VITE_BIJECTION_URL");
  }
  const bijectionQueryClient = new BijectionQueryClient(BIJECTION_URL);

  const queryClient: QueryClient = new QueryClient({
    defaultOptions: {
      queries: {
        queryKeyHashFn: bijectionQueryClient.hashFn(),
        queryFn: bijectionQueryClient.queryFn(),
      },
    },
  });
  bijectionQueryClient.connect(queryClient);

  const router = createRouter({
    routeTree,
    defaultPreload: "intent",
    context: { queryClient },
    scrollRestoration: true,
    Wrap: ({ children }) => (
      <BijectionProvider client={bijectionQueryClient.bijectionClient}>
        {children}
      </BijectionProvider>
    ),
  });
  setupRouterSsrQueryIntegration({ router, queryClient });

  return router;
}

Set up a Bijection dev deployment

Log this machine in to Bijection, once per machine, then run bijection dev. The first run creates your dev deployment and saves its URL in .env.local as VITE_BIJECTION_URL. The dev command then keeps running to push your functions in bijection/ to your dev deployment on every change.

bijection login
bijection dev

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>

Create sample data for your database

In a new terminal window, create a sampleData.jsonl file with some sample data.

{"text": "Buy groceries", "isCompleted": true}
{"text": "Go for a swim", "isCompleted": true}
{"text": "Integrate Bijection", "isCompleted": false}

Add the sample data to your database

Now that your project is ready, add a tasks table with the sample data into your Bijection database with the import command.

bijection import --table tasks sampleData.jsonl

Declare the tasks table

bijection init created bijection/schema.ts, which declares the tables of your database, starting with a sample messages table. Add a tasks table beside it. The schema gives your functions TypeScript types, and Bijection enforces it at runtime.

bijection/schema.ts

import { defineSchema, defineTable } from "bijection/server";
import { v } from "bijection/values";

export default defineSchema({
  messages: defineTable({
    author: v.string(),
    body: v.string(),
  }),
  tasks: defineTable({
    text: v.string(),
    isCompleted: v.boolean(),
  }),
});

Expose a database query

Add a new file tasks.ts in the bijection/ folder with a query function that loads the data.Exporting a query function from this file declares an API function named after the file and the export name, api.tasks.get.

import { query } from "./_generated/server";

export const get = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("tasks").collect();
  },
});

Display the data in your app

Replace the file src/routes/index.tsx with these contents.The useSuspenseQuery hook renders the API function api.tasks.get query result on the server initially, then it updates live in the browser.

import { bijectionQuery } from "@bijection/react-query";
import { useSuspenseQuery } from "@tanstack/react-query";
import { createFileRoute } from "@tanstack/react-router";
import { api } from "../../bijection/_generated/api";

export const Route = createFileRoute("/")({
  component: Home,
});

function Home() {
  const { data } = useSuspenseQuery(bijectionQuery(api.tasks.get, {}));

  return (
    <div>
      {data.map(({ _id, text }) => (
        <div key={_id}>{text}</div>
      ))}
    </div>
  );
}

Start the app

Start the app, open http://localhost:3000 in a browser, and see the list of tasks.

npm run dev

For more see the TanStack Start with Bijection client documentation page.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

TanStack Start Quickstart