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:

Install dependencies
Write your schema
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 & PermissionsAccount, 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 definitionco } from "jazz-tools";

export class class MyAppAccountMyAppAccount extends class Account@categoryIdentity & PermissionsAccount {
  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 definitionco.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 & HooksJazzProvider } from "jazz-react";
import { class MyAppAccountMyAppAccount } from "./schema";

function createRoot(container: Container, options?: RootOptions): RootcreateRoot 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 | nullReturns 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 & HooksJazzProvider
    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 & HooksJazzProvider>
);

// 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 & HooksJazzProvider } from "jazz-react";
import { class MyAppAccountMyAppAccount } from "./schema";

export function function JazzWrapper({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementJazzWrapper({ 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 | undefinedRepresents 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 & HooksJazzProvider
      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 & HooksJazzProvider>
  );
}

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:

Create a shared rendering component.

Create a client hydration component.

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.

Installation and Setup

#Install dependencies

#Write your schema

#Standard React Setup

#Next.js Integration

#Client-side Only (Easiest)

#SSR Support (Experimental)

#Pure SSR

#Hybrid SSR + Client Hydration

#Further Reading