Installation and Setup

Add Jazz to your React application in minutes. This setup covers standard React apps, Next.js, and gives an overview of experimental SSR approaches.

Integrating Jazz with React is straightforward. You'll define data schemas that describe your application's structure, then wrap your app with a provider that handles sync and storage. The whole process takes just three steps:

  1. Install dependencies
  2. Write your schema
  3. Wrap your app in <JazzProvider />

Looking for complete examples? Check out our example applications for chat apps, collaborative editors, and more.

Install dependencies

First, install the required packages:

pnpm install jazz-react jazz-tools

Write your schema

Define your data schema using CoValues from jazz-tools.

// schema.ts
import { class Account
@categoryIdentity & Permissions
Account
,
type co<T> = T | (T & CoMarker)
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}
@categorySchema definition@categorySchema definition
co
} from "jazz-tools";
export class class MyAppAccountMyAppAccount extends class Account
@categoryIdentity & Permissions
Account
{
MyAppAccount.name: co<string>name =
const co: {
    string: co<string>;
    number: co<number>;
    boolean: co<boolean>;
    null: co<null>;
    Date: co<Date>;
    literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number]>;
    json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T>;
    encoded<T>(arg: Encoder<T>): co<T>;
    ref: {
        ...;
    };
    items: ItemsSym;
    optional: {
        ref: <C extends CoValueClass>(arg: C | ((_raw: InstanceType<C>["_raw"]) => C)) => co<InstanceType<C> | null | undefined>;
        json<T extends CojsonInternalTypes.CoJsonValue<T>>(): co<T | undefined>;
        encoded<T>(arg: OptionalEncoder<T>): co<T | undefined>;
        string: co<string | undefined>;
        number: co<number | undefined>;
        boolean: co<boolean | undefined>;
        null: co<null | undefined>;
        Date: co<Date | undefined>;
        literal<T extends (string | number | boolean)[]>(..._lit: T): co<T[number] | undefined>;
    };
}
@categorySchema definition@categorySchema definition
co
.string: co<string>string;
}

See CoValues for more information on how to define your schema.

Standard React Setup

Wrap your application with <JazzProvider /> to connect to the Jazz network and define your data schema:

// app.tsx
import { function JazzProvider<Acc extends Account = MyAppAccount>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
@categoryContext & Hooks
JazzProvider
} from "jazz-react";
import { class MyAppAccountMyAppAccount } from "./schema"; function createRoot(container: Container, options?: RootOptions): Root
createRoot lets you create a root to display React components inside a browser DOM node.
@see{@link https://react.dev/reference/react-dom/client/createRoot API Reference for `createRoot`}
createRoot
(var document: Document
[MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/document)
document
.Document.getElementById(elementId: string): HTMLElement | null
Returns a reference to the first object with the specified value of the ID attribute.
@paramelementId String that specifies the ID value.
getElementById
("root")!).Root.render(children: React.ReactNode): voidrender(
<function JazzProvider<Acc extends Account = MyAppAccount>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
@categoryContext & Hooks
JazzProvider
sync: SyncConfigsync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com"peer: "wss://cloud.jazz.tools/?key=you@example.com" }} AccountSchema?: AccountClass<MyAppAccount> | undefinedAccountSchema={class MyAppAccountMyAppAccount} > <function App(): React.JSX.ElementApp /> </function JazzProvider<Acc extends Account = MyAppAccount>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
@categoryContext & Hooks
JazzProvider
>
); // Register your Account schema to enhance TypeScript support declare module "jazz-react" { interface Register { Register.Account: MyAppAccountAccount: class MyAppAccountMyAppAccount; } }

This setup handles:

  • Connection to the Jazz sync server
  • Schema registration for type-safe data handling
  • Local storage configuration

With this in place, you're ready to start using Jazz hooks in your components. Learn how to access and update your data.

Next.js Integration

Client-side Only (Easiest)

The simplest approach for Next.js is client-side only integration:

// app.tsx
"use client" // Mark as client component

import { function JazzProvider<Acc extends Account = Account>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
@categoryContext & Hooks
JazzProvider
} from "jazz-react";
import { class MyAppAccountMyAppAccount } from "./schema"; export function
function JazzWrapper({ children }: {
    children: React.ReactNode;
}): React.JSX.Element
JazzWrapper
({ children: React.ReactNodechildren }: { children: React.ReactNodechildren: React.type React.ReactNode = string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | null | undefined
Represents all of the things React can render. Where {@link ReactElement } only represents JSX, `ReactNode` represents everything that can be rendered.
@see{@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/reactnode/ React TypeScript Cheatsheet}@example```tsx // Typing children type Props = { children: ReactNode } const Component = ({ children }: Props) => <div>{children}</div> <Component>hello</Component> ```@example```tsx // Typing a custom element type Props = { customElement: ReactNode } const Component = ({ customElement }: Props) => <div>{customElement}</div> <Component customElement={<div>hello</div>} /> ```
ReactNode
}) {
return ( <function JazzProvider<Acc extends Account = Account>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
@categoryContext & Hooks
JazzProvider
sync: SyncConfigsync={{ peer: "wss://cloud.jazz.tools/?key=you@example.com"peer: "wss://cloud.jazz.tools/?key=you@example.com" }} AccountSchema?: AccountClass<MyAppAccount> | undefinedAccountSchema={class MyAppAccountMyAppAccount} > {children: React.ReactNodechildren} </function JazzProvider<Acc extends Account = Account>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
@categoryContext & Hooks
JazzProvider
>
); }

Remember to mark any component that uses Jazz hooks with "use client":

// Profile.tsx
"use client"; 

import { 
function useAccount<A extends RegisteredAccount>(): {
    me: A;
    logOut: () => void;
} (+1 overload)
useAccount
} from "jazz-react";
export function function Profile(): React.JSX.ElementProfile() { const { const me: MyAppAccountme } =
useAccount<MyAppAccount>(): {
    me: MyAppAccount;
    logOut: () => void;
} (+1 overload)
useAccount
();
return <JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>Hello, {const me: MyAppAccountme?.MyAppAccount.name: co<string>name}</JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>div>; }

SSR Support (Experimental)

For server-side rendering, Jazz offers experimental approaches:

  • Pure SSR
  • Hybrid SSR + Client Hydration

Pure SSR

Use Jazz in server components by directly loading data with CoValue.load().

This works well for public data accessible to the server account.

Hybrid SSR + Client Hydration

For more complex cases, you can pre-render on the server and hydrate on the client:

  1. Create a shared rendering component.
  1. Create a client hydration component.
  1. Create a server component that pre-loads data.

This approach gives you the best of both worlds: fast initial loading with server rendering, plus real-time updates on the client.

Further Reading