Quickstart

Start with your agent

Paste this into your coding agent, or tell it to run npm create jazz and follow the output. Both give it the same brief, which always lives at jazz.tools/quickstart.md.

Agent brief
# Agent Quickstart for jazz.tools
​
## Decide
​
1. **Where should this project be deployed?** Jazz runs embedded in your backend, so it deploys
   with your app. It works best on serverless platforms like Vercel; Cloudflare support is coming.
   You don't need to deploy to start: locally, Jazz uses a SQLite file.
   Default: Vercel for a Next.js app, your own server otherwise.
   See /docs/setup/deployment/vercel, /docs/setup/deployment/own-server
2. **What auth provider or library should be used?** Jazz is unopinionated here: it hooks into
   however your backend already does auth, including roles and claims from your identity provider,
   which policies can check directly.
   Default: keep what the project uses; for a new app, Better Auth.
   See /docs/setup/auth/backend, /docs/setup/auth/better-auth, /docs/setup/auth/workos,
   /docs/setup/auth/custom, /docs/setup/auth/local-first
3. **Which backend framework should be used?** Next.js, Hono, Express / Node, Bun or Effect. Each
   setup page has a tab per framework.
   Default: what the project already has; for a new app, Next.js with React, or Hono or Express
   plus Vite with Vue or Svelte.
   For a separate frontend dev server (React + Vite, say), run Jazz in your backend and proxy
   `/jazz` to it with WebSockets on (Vite: `server.proxy["/jazz"] = { target, ws: true }`), plus
   your auth routes (Better Auth also needs the dev origin in `trustedOrigins`); see
   /docs/setup/deployment/own-server#a-separate-frontend-dev-server
4. **Should Jazz only be used through traditional API routes, or would this app benefit from
   simpler state management by accessing Jazz directly from the frontend?** This choice is cheap
   to change later: a screen moves from thin to local-first with the same schema, queries and
   policies.
   - React Native is always local-first: /docs/setup/react-native
   - For the web: is this an app where fast loads and bundle size matter most, with lots of
     first-time visitors? Use the thin client (/docs/setup/web-client/thin-client). Or is it a
     frequently used app that benefits from local storage for UI speed and offline support? Use
     the local-first client (/docs/setup/web-client/local-first-client). Both pages list the
     current bundle sizes.
   - Which frontend framework? React, Vue, Svelte, Solid, Effect or plain TypeScript.
     Default: thin client, React.
​
## Design the data
​
5. **The most important thing to get right in a Jazz app is the schema** (/docs/schemas/defining-tables,
   /docs/schemas/column-types, /docs/schemas/relationships) **and its permission policies**
   (/docs/schemas/policies).
   - For new apps, this is the core design question. Show the user the schema and policies and
     iterate with them now, before building the whole app.
   - For existing apps migrating from another data store, the existing data should constrain this
     enough.
   - Write permission tests next to the policies: /docs/tooling/testing
   - In either case, use these Jazz features instead of modeling them yourself:
     - Built-in metadata columns like `$createdBy`, `$createdAt`, `$updatedBy` and `$updatedAt`:
       /docs/reading/metadata
     - Edit history: /docs/reading/history
     - Files, streams and long text as large values in ordinary columns:
       /docs/writing/writing-data#editing-a-page-of-a-large-value
     - Collaborative rich text: /docs/writing/text
​
## Build
​
6. **Now build the app** with server- or client-side queries (/docs/reading/queries,
   /docs/reading/filters-and-sorting, /docs/reading/includes-and-relations) and transactions
   (/docs/writing/writing-data, /docs/writing/transactions, /docs/writing/text).
   One subtlety of Jazz is choosing between two kinds of transaction. Start with mergeable ones.
   - Mergeable transactions are eventually consistent and local-first: concurrent writes are
     combined by merge strategies.
   - Serializable transactions are ACID with serializable isolation and locally optimistic: use
     them for invariants that must hold across users, such as unique names, stock counts or
     balances. The server can still reject them, so handle that in the UI.
7. **Debug.** Reproduce problems in tests against your app's backend (/docs/tooling/testing),
   look at the data with the inspector (/docs/tooling/inspector), and check what has synced with
   "Showing sync status" on /docs/writing/writing-data.
8. **Feedback.** Jazz focuses on self-hosting, so the team relies on feedback to learn what people
   build and where Jazz falls short, and it really shapes what comes next. Tell the user so, and
   offer to help them share it:
   - A bug or a missing feature: draft a GitHub issue at https://github.com/garden-co/jazz/issues
     with what they were building, what they expected, what happened, and a minimal reproduction.
     You have all that context; write it up so the user only needs to review and submit it.
   - What they built and how it went: the Jazz Discord, https://discord.gg/jazz.
​
## Later and more advanced topics to be aware of
​
1. Schema evolution and migrations are particularly interesting in Jazz: /docs/schemas/migrations
2. Need backend clients that can't be part of the main backend API? /docs/setup/backend-client
3. Drafts and branches of rows: /docs/recipes/drafts-and-branches
4. Durability tiers, for "is it saved?" indicators: /docs/reference/durability-tiers
​
## About this guide
​
The above is a guide from the Jazz team for agents building with Jazz. You and your user have the
most context about what you're building, so use your intuition. Depending on how established or
greenfield the project is and what the user wants, explain how Jazz fits their existing tech
choices, recommend options for open choices, or just make the choices needed to get things running
quickly. Every choice under "Decide" has a default you can take when the user has no preference.
​
All docs links are paths on https://jazz.tools. Append `.md` to any docs page for Markdown. The
full docs index is https://jazz.tools/llms.txt. To search the docs, fetch
https://jazz.tools/api/search?q=<words>&format=md (add `&full=1` to include the top three pages).
​
**This guide is for Jazz 2,** which is in alpha and leaves alpha soon. Install the current version
with `npm install jazz-tools` (plus `jazz-rn` for React Native); it is a 2.0 alpha, and that's
expected. Versions before 2.0 are Classic Jazz, a different API: don't pin `jazz-tools` to 0.x, and
don't follow Classic examples (`co.map`, `CoValue`, `Group`) from memory or the web.

The questions your agent will ask

Each one has a default, so "you pick" is a fine answer.

• Where will it be deployed? Vercel or your own server; Cloudflare is coming. Default: Vercel for Next.js, your own server otherwise. See Vercel and Your Own Server.
• Which auth? Whatever your backend already uses; Better Auth for a new app. See How Auth Works.
• Which backend framework? Next.js, Hono, Express / Node, Bun or Effect. Default: Next.js.
• API routes only, or Jazz from the frontend too? If the frontend, the thin client (default) or local-first, and React, Vue, Svelte, Solid or plain TypeScript. React Native is always local-first. See Thin Client.
• What is the data, and who may read or write it? Your agent shows you the schema and policies before building the rest. See Defining Tables and Declarative Permissions.

How your agent knows it's done

There's no check command. Your agent shows you each of these working:

• The dev setup starts with one command
• A backend route writes a row that a live query in the UI shows without a reload
• A second user can't read rows the policies say are private, and the permission tests pass (see Testing)

It finishes with the commands to run, what it chose and why, and any docs that were wrong or missing, with their URLs.

Run it yourself

Install Jazz with npm install jazz-tools. That's Jazz 2, in alpha and leaving it soon; versions before 2.0 are Classic Jazz, with a different API.

Jazz runs inside your backend's dev server, so there's nothing extra to start. Create it once and mount it under /jazz:

jazz.server.ts
import { createJazz, sqlite } from "jazz-tools/backend";
import { app } from "./schema";
import permissions from "./permissions";
​
export const jazz = createJazz({
  app,
  permissions,
  store: sqlite({ path: "./data/jazz" }),
  authenticate: async (request) => /* your session */ null,
});

Edit schema.ts or permissions.ts and restart the dev server: Jazz applies them on start. Don't count on hot reload for these: Turbopack usually recovers, but webpack builds can get stuck on the old schema. See Your Own Server for mounting it in Next.js, Hono or Express.

How we test this page

An "agent as adopter" suite runs this brief end to end: a coding agent in a clean sandbox, a simulated user answering its questions, and a separate LLM judge checking the done list. For now we run it by hand as a release gate.