Providers

<JazzReactProvider /> is the core component that connects your React application to Jazz. It handles:

Data Synchronization: Manages connections to peers and the Jazz cloud
Local Storage: Persists data locally between app sessions
Schema Types: Provides APIs for the AccountSchema
Authentication: Connects your authentication system to Jazz

Our Chat example app provides a complete implementation of JazzReactProvider with authentication and real-time data sync.

Setting up the Provider

The <JazzReactProvider /> accepts several configuration options:

// App.tsx
import { function JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider } from "jazz-tools/react";
import { const MyAppAccount: AccountSchema<{
    root: CoMapSchema<{
        todos: CoListSchema<CoMapSchema<{
            title: ZodString;
            completed: ZodBoolean;
        }, unknown, Account | Group>>;
    }, unknown, Account | Group>;
    profile: CoProfileSchema<...>;
}>MyAppAccount } from "./schema";

export function function MyApp({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementMyApp({ children: React.ReactNodechildren }: { children: React.ReactNodechildren: React.type React.ReactNode = string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<...> | 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 JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider
      sync: SyncConfigsync={{
        peer: `wss://${string}` | `ws://${string}`peer: `wss://cloud.jazz.tools/?key=${const apiKey: "you@example.com"Use your email as a temporary key, or get a free
API Key at dashboard.jazz.tools for higher limits.
@linkhttps://dashboard.jazz.toolsapiKey}`,
        when?: "always" | "signedUp" | undefinedwhen: "always" // When to sync: "always", "never", or "signedUp"
      }}
      AccountSchema?: AccountSchema<{
    root: CoMapSchema<{
        todos: CoListSchema<CoMapSchema<{
            title: ZodString;
            completed: ZodBoolean;
        }, unknown, Account | Group>>;
    }, unknown, Account | Group>;
    profile: CoProfileSchema<...>;
}> | undefinedAccountSchema={const MyAppAccount: AccountSchema<{
    root: CoMapSchema<{
        todos: CoListSchema<CoMapSchema<{
            title: ZodString;
            completed: ZodBoolean;
        }, unknown, Account | Group>>;
    }, unknown, Account | Group>;
    profile: CoProfileSchema<...>;
}>MyAppAccount}
    >
      {children: React.ReactNodechildren}
    </function JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider>
  );
}

Tip

Sign up for a free API key at dashboard.jazz.tools for higher limits or production use, or use your email address as a temporary key to get started quickly.

Provider Options

Sync Options

The sync property configures how your application connects to the Jazz network:

import { type type SyncConfig = {
    peer: `wss://${string}` | `ws://${string}`;
    when?: "always" | "signedUp";
} | {
    peer?: `wss://${string}` | `ws://${string}`;
    when: "never";
}SyncConfig } from "jazz-tools";

const const syncConfig: SyncConfigsyncConfig: type SyncConfig = {
    peer: `wss://${string}` | `ws://${string}`;
    when?: "always" | "signedUp";
} | {
    peer?: `wss://${string}` | `ws://${string}`;
    when: "never";
}SyncConfig = {
  // Connection to Jazz Cloud or your own sync server
  peer: `wss://${string}` | `ws://${string}`peer: `wss://cloud.jazz.tools/?key=${const apiKey: "you@example.com"Use your email as a temporary key, or get a free
API Key at dashboard.jazz.tools for higher limits.
@linkhttps://dashboard.jazz.toolsapiKey}`,

  // When to sync: "always" (default), "never", or "signedUp"
  when?: "always" | "signedUp" | undefinedwhen: "always",
}

See Authentication States for more details on how the when property affects synchronization based on authentication state.

Account Schema

The AccountSchema property defines your application's account structure:

// app.tsx
import { const MyAppAccount: AccountSchema<{
    root: CoMapSchema<{
        todos: CoListSchema<CoMapSchema<{
            title: ZodString;
            completed: ZodBoolean;
        }, unknown, Account | Group>>;
    }, unknown, Account | Group>;
    profile: CoProfileSchema<...>;
}>MyAppAccount } from "./schema";

export function function MyApp({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementMyApp ({ children: React.ReactNodechildren }: { children: React.ReactNodechildren: React.type React.ReactNode = string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<...> | 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 }) {
  // Use in provider
  return (
    <function JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider
      sync: SyncConfigsync={const syncConfig: SyncConfigsyncConfig}
      AccountSchema?: AccountSchema<{
    root: CoMapSchema<{
        todos: CoListSchema<CoMapSchema<{
            title: ZodString;
            completed: ZodBoolean;
        }, unknown, Account | Group>>;
    }, unknown, Account | Group>;
    profile: CoProfileSchema<...>;
}> | undefinedAccountSchema={const MyAppAccount: AccountSchema<{
    root: CoMapSchema<{
        todos: CoListSchema<CoMapSchema<{
            title: ZodString;
            completed: ZodBoolean;
        }, unknown, Account | Group>>;
    }, unknown, Account | Group>;
    profile: CoProfileSchema<...>;
}>MyAppAccount}
    >
      {children: React.ReactNodechildren}
    </function JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider>
  );
}

Additional Options

The provider accepts these additional options:

// app.tsx
export function function MyApp({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementMyApp ({ children: React.ReactNodechildren }: { children: React.ReactNodechildren: React.type React.ReactNode = string | number | bigint | boolean | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal | Promise<...> | 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 JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider
      sync: SyncConfigsync={const syncConfig: SyncConfigsyncConfig}

      // Enable guest mode for account-less access
      guestMode?: boolean | undefinedguestMode={false}

      // Enable SSR mode
      enableSSR?: boolean | undefinedenableSSR={false}

      // Set default name for new user profiles
      defaultProfileName?: string | undefineddefaultProfileName="New User"

      // Override the default storage key
      authSecretStorageKey?: string | undefinedauthSecretStorageKey="jazz-logged-in-secret"

      // Handle user logout
      onLogOut?: (() => void) | undefinedonLogOut={() => {
        var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v20.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v20.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v20.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v20.11.1/lib/console.js)console.Console.log(message?: any, ...optionalParams: any[]): void (+2 overloads)[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log("User logged out");
      }}

      // Handle anonymous account data when user logs in to existing account
      onAnonymousAccountDiscarded?: ((anonymousAccount: Account | ({
    readonly [x: string]: any;
} & Account)) => Promise<void>) | undefinedonAnonymousAccountDiscarded={(account: Account | ({
    readonly [x: string]: any;
} & Account)account) => {
        var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v20.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v20.x/api/process.html#processstderr). The global `console` can be used without importing the `node:console` module.

_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v20.x/api/process.html#a-note-on-process-io) for
more information.

Example using the global `console`:

```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```

Example using the `Console` class:

```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```
@see[source](https://github.com/nodejs/node/blob/v20.11.1/lib/console.js)console.Console.log(message?: any, ...optionalParams: any[]): void (+2 overloads)[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log("Anonymous account discarded", account: Account | ({
    readonly [x: string]: any;
} & Account)account.Account.$jazz: AccountJazzApi<Account> | AccountJazzApi<{
    readonly [x: string]: any;
} & Account>Jazz methods for Accounts are inside this property.

This allows Accounts to be used as plain objects while still having
access to Jazz methods.$jazz.CoValueJazzApi<V extends CoValue>.id: stringid);
        // Migrate data here
        return var Promise: PromiseConstructorRepresents the completion of an asynchronous operationPromise.PromiseConstructor.resolve(): Promise<void> (+2 overloads)Creates a new resolved promise.
@returnsA resolved promise.resolve();
      }}
    >
      {children: React.ReactNodechildren}
    </function JazzReactProvider<S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>({ children, guestMode, sync, storage, AccountSchema, defaultProfileName, onLogOut, logOutReplacement, onAnonymousAccountDiscarded, enableSSR, fallback, authSecretStorageKey, }: JazzProviderProps<S>): JSX.Element@categoryContext & HooksJazzReactProvider>
  );
}

See Authentication States for more information on authentication states, guest mode, and handling anonymous accounts.

Authentication

<JazzReactProvider /> works with various authentication methods to enable users to access their data across multiple devices. For a complete guide to authentication, see our Authentication Overview.

Need Help?

If you have questions about configuring the Jazz Provider for your specific use case, join our Discord community for help.

Docs issue?⌝Join Discord⌝

Server-side rendering

Providers

#Setting up the Provider

#Provider Options

#Sync Options

#Account Schema

#Additional Options

#Authentication