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:
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
Account,co } from "jazz-tools"; export class
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>; }; }
class MyAppAccount
MyAppAccount extendsclass Account
Account {MyAppAccount.name: co<string>
name =co.
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>; }; }
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
JazzProvider } from "jazz-react"; import {class MyAppAccount
MyAppAccount } from "./schema";function createRoot(container: Container, options?: RootOptions): Root
createRoot lets you create a root to display React components inside a browser DOM node.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.getElementById("root")!).Root.render(children: React.ReactNode): void
render( <function JazzProvider<Acc extends Account = MyAppAccount>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
JazzProvidersync: SyncConfig
sync={{peer: "wss://cloud.jazz.tools/?key=you@example.com"
peer: "wss://cloud.jazz.tools/?key=you@example.com" }}AccountSchema?: AccountClass<MyAppAccount> | undefined
AccountSchema={class MyAppAccount
MyAppAccount} > <function App(): React.JSX.Element
App /> </function JazzProvider<Acc extends Account = MyAppAccount>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
JazzProvider> ); // Register your Account schema to enhance TypeScript support declare module "jazz-react" { interface Register {Register.Account: MyAppAccount
Account:class MyAppAccount
MyAppAccount; } }
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
JazzProvider } from "jazz-react"; import {class MyAppAccount
MyAppAccount } from "./schema"; export functionJazzWrapper({
function JazzWrapper({ children }: { children: React.ReactNode; }): React.JSX.Element
children: React.ReactNode
children }: {children: React.ReactNode
children: 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.ReactNode }) { return ( <function JazzProvider<Acc extends Account = Account>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
JazzProvidersync: SyncConfig
sync={{peer: "wss://cloud.jazz.tools/?key=you@example.com"
peer: "wss://cloud.jazz.tools/?key=you@example.com" }}AccountSchema?: AccountClass<MyAppAccount> | undefined
AccountSchema={class MyAppAccount
MyAppAccount} > {children: React.ReactNode
children} </function JazzProvider<Acc extends Account = Account>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, }: JazzProviderProps<Acc>): JSX.Element
JazzProvider> ); }
Remember to mark any component that uses Jazz hooks with "use client"
:
// Profile.tsx "use client"; import {
useAccount } from "jazz-react"; export function
function useAccount<A extends RegisteredAccount>(): { me: A; logOut: () => void; } (+1 overload)
function Profile(): React.JSX.Element
Profile() { const {const me: MyAppAccount
me } =useAccount(); return <
useAccount<MyAppAccount>(): { me: MyAppAccount; logOut: () => void; } (+1 overload)
JSX.IntrinsicElements.div: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>
div>Hello, {const me: MyAppAccount
me?.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.
Further Reading
- Schemas - Learn about defining your data model
- Provider Configuration - Learn about other configuration options for Providers
- Authentication - Set up user authentication
- Sync and Storage - Learn about data persistence