Providers

<JazzProvider /> 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 JazzProvider with authentication and real-time data sync.

Setting up the Provider

The <JazzProvider /> accepts several configuration options:

// @filename: schema.ts
import { co, z } from "jazz-tools";

export const TodoItem = co.map({
  title: z.string(),
  completed: z.boolean(),
});

export const AccountRoot = co.map({
  todos: co.list(TodoItem),
});

export const MyAppAccount = co.account({
  root: AccountRoot,
  profile: co.map({ name: z.string() }),
});
// @filename: app.tsx
import * as React from "react";
// ---cut---
// App.tsx
import { JazzProvider } from "jazz-react";
import { MyAppAccount } from "./schema";

export function MyApp({ children }: { children: React.ReactNode }) {
  return (
    <JazzProvider
      sync={{
        peer: "wss://cloud.jazz.tools/?key=your-api-key",
        when: "always" // When to sync: "always", "never", or "signedUp"
      }}
      AccountSchema={MyAppAccount}
    >
      {children}
    </JazzProvider>
  );
}

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=your-api-key",

  // 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:


// @filename: schema.ts
import { co, z } from "jazz-tools";

export const TodoItem = co.map({
  title: z.string(),
  completed: z.boolean(),
});

export const AccountRoot = co.map({
  todos: co.list(TodoItem),
});

export const MyAppAccount = co.account({
  root: AccountRoot,
  profile: co.map({ name: z.string() }),
});

// @filename: app.tsx
import * as React from "react";
import { JazzProvider } from "jazz-react";
import { SyncConfig } from "jazz-tools";

const syncConfig: SyncConfig = {
  peer: "wss://cloud.jazz.tools/?key=your-api-key",
  when: "always",
}

// ---cut---
// app.tsx
import { MyAppAccount } from "./schema";

export function MyApp ({ children }: { children: React.ReactNode }) {
  // Use in provider
  return (
    <JazzProvider
      sync={syncConfig}
      AccountSchema={MyAppAccount}
    >
      {children}
    </JazzProvider>
  );
}

Additional Options

The provider accepts these additional options:

import * as React from "react";
import { JazzProvider } from "jazz-react";
import { SyncConfig } from "jazz-tools";

const syncConfig: SyncConfig = {
  peer: "wss://cloud.jazz.tools/?key=your-api-key",
  when: "always",
}

// ---cut---
// app.tsx
export function MyApp ({ children }: { children: React.ReactNode }) {
  return (
    <JazzProvider
      sync={syncConfig}

      // Enable guest mode for account-less access
      guestMode={false}

      // Set default name for new user profiles
      defaultProfileName="New User"

      // Handle user logout
      onLogOut={() => {
        console.log("User logged out");
      }}

      // Handle anonymous account data when user logs in to existing account
      onAnonymousAccountDiscarded={(account) => {
        console.log("Anonymous account discarded", account.id);
        // Migrate data here
        return Promise.resolve();
      }}
    >
      {children}
    </JazzProvider>
  );
}

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

Authentication

<JazzProvider /> 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.