Clerk Authentication

Jazz can be integrated with Clerk to authenticate users. This method combines Clerk's comprehensive authentication services with Jazz's local-first capabilities.

How it works

When using Clerk authentication:

Users sign up or sign in through Clerk's authentication system
Jazz securely stores the user's account keys with Clerk
When logging in, Jazz retrieves these keys from Clerk
Once authenticated, users can work offline with full Jazz functionality

This authentication method is not fully local-first, as login and signup need to be done online, but once authenticated, users can use all of Jazz's features without needing to be online.

Key benefits

Rich auth options: Email/password, social logins, multi-factor authentication
User management: Complete user administration dashboard
Familiar sign-in: Standard auth flows users already know
OAuth providers: Google, GitHub, and other popular providers
Enterprise features: SSO, SAML, and other advanced options

Implementation

Use <JazzReactProviderWithClerk /> to wrap your app:

import { const useClerk: () => LoadedClerkuseClerk, const ClerkProvider: React.ComponentType<ClerkProviderProps>ClerkProvider } from '@clerk/clerk-react';
import { const JazzReactProviderWithClerk: <S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>(props: {
    clerk: MinimalClerkClient;
} & JazzProviderProps<S>) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<...> | Iterable<React.ReactNode> | null | undefined> | JSX.Element | nullJazzReactProviderWithClerk } from "jazz-tools/react";

function function JazzProvider({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementJazzProvider({ 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 }) {
  const const clerk: LoadedClerkclerk = function useClerk(): LoadedClerkuseClerk();

  return (
    <const JazzReactProviderWithClerk: <S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>(props: {
    clerk: MinimalClerkClient;
} & JazzProviderProps<S>) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<...> | Iterable<React.ReactNode> | null | undefined> | JSX.Element | nullJazzReactProviderWithClerk
      clerk: MinimalClerkClientclerk={const clerk: LoadedClerkclerk}
      sync: SyncConfigsync={{
        peer: "wss://cloud.jazz.tools/?key=you@example.com"peer: `wss://cloud.jazz.tools/?key=${const apiKey: "you@example.com"apiKey}`,
      }}
    >
      {children: React.ReactNodechildren}
    </const JazzReactProviderWithClerk: <S extends (AccountClass<Account> & CoValueFromRaw<Account>) | CoreAccountSchema>(props: {
    clerk: MinimalClerkClient;
} & JazzProviderProps<S>) => string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<...> | Iterable<React.ReactNode> | null | undefined> | JSX.Element | nullJazzReactProviderWithClerk>
  );
}

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(
  <const ClerkProvider: React.ComponentType<ClerkProviderProps>ClerkProvider publishableKey: stringThe Clerk publishable key for your instance
@noteThis can be found in your Clerk Dashboard on the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) pagepublishableKey={const PUBLISHABLE_KEY: "fake_key"PUBLISHABLE_KEY} afterSignOutUrl: stringafterSignOutUrl="/">
    <function JazzProvider({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementJazzProvider>
      <function App(): React.JSX.ElementApp />
    </function JazzProvider({ children }: {
    children: React.ReactNode;
}): React.JSX.ElementJazzProvider>
  </const ClerkProvider: React.ComponentType<ClerkProviderProps>ClerkProvider>
);

import { const SignInButton: {
    (props: Without<WithClerkProp<SignInButtonProps>, "clerk">): React.JSX.Element | null;
    displayName: string;
}SignInButton } from "@clerk/clerk-react";
import { function useAccount<A extends AccountClass<Account> | CoreAccountSchema, R extends ResolveQuery<A> = true>(AccountSchema?: A, options?: {
    resolve?: ResolveQueryStrict<A, R>;
}): {
    me: Loaded<A, R> | undefined | null;
    agent: AnonymousJazzAgent | Loaded<A, true>;
    logOut: () => void;
}React hook for accessing the current user's account and authentication state.

This hook provides access to the current user's account profile and root data,
along with authentication utilities. It automatically handles subscription to
the user's account data and provides a logout function.
@returnsAn object containing:
- `me`: The loaded account data, or `undefined` if loading, or `null` if not authenticated
- `agent`: The current agent (anonymous or authenticated user). Can be used as `loadAs` parameter for load and subscribe methods.
- `logOut`: Function to log out the current user@example```tsx
// Deep loading with resolve queries
function ProjectListWithDetails() {
  const { me } = useAccount(MyAppAccount, {
    resolve: {
      profile: true,
      root: {
        myProjects: {
          $each: {
            tasks: true,
          },
        },
      },
    },
  });

  if (!me) {
    return me === null
      ? <div>Failed to load your projects</div>
      : <div>Loading...</div>;
  }

  return (
    <div>
      <h1>{me.profile.name}'s projects</h1>
      <ul>
        {me.root.myProjects.map((project) => (
          <li key={project.id}>
            {project.name} ({project.tasks.length} tasks)
          </li>
        ))}
      </ul>
    </div>
  );
}
```useAccount, function useIsAuthenticated(): booleanuseIsAuthenticated } from "jazz-tools/react";

export function function AuthButton(): React.JSX.ElementAuthButton() {
  const { const logOut: () => voidlogOut } = useAccount<AccountClass<Account> | CoreAccountSchema<$ZodLooseShape>, true>(AccountSchema?: AccountClass<Account> | CoreAccountSchema<...> | undefined, options?: {
    ...;
} | undefined): {
    ...;
}React hook for accessing the current user's account and authentication state.

This hook provides access to the current user's account profile and root data,
along with authentication utilities. It automatically handles subscription to
the user's account data and provides a logout function.
@returnsAn object containing:
- `me`: The loaded account data, or `undefined` if loading, or `null` if not authenticated
- `agent`: The current agent (anonymous or authenticated user). Can be used as `loadAs` parameter for load and subscribe methods.
- `logOut`: Function to log out the current user@example```tsx
// Deep loading with resolve queries
function ProjectListWithDetails() {
  const { me } = useAccount(MyAppAccount, {
    resolve: {
      profile: true,
      root: {
        myProjects: {
          $each: {
            tasks: true,
          },
        },
      },
    },
  });

  if (!me) {
    return me === null
      ? <div>Failed to load your projects</div>
      : <div>Loading...</div>;
  }

  return (
    <div>
      <h1>{me.profile.name}'s projects</h1>
      <ul>
        {me.root.myProjects.map((project) => (
          <li key={project.id}>
            {project.name} ({project.tasks.length} tasks)
          </li>
        ))}
      </ul>
    </div>
  );
}
```useAccount();

  const const isAuthenticated: booleanisAuthenticated = function useIsAuthenticated(): booleanuseIsAuthenticated();

  if (const isAuthenticated: booleanisAuthenticated) {
    return <React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button React.DOMAttributes<HTMLButtonElement>.onClick?: React.MouseEventHandler<HTMLButtonElement> | undefinedonClick={() => const logOut: () => voidlogOut()}>Logout</React.JSX.IntrinsicElements.button: React.DetailedHTMLProps<React.ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>button>;
  }

  return <const SignInButton: {
    (props: Without<WithClerkProp<SignInButtonProps>, "clerk">): React.JSX.Element | null;
    displayName: string;
}SignInButton />;
}

Examples

You can explore Jazz with Clerk integration in our example projects. For more Clerk-specific demos, visit Clerk's documentation.

When to use Clerk

Clerk authentication is ideal when:

You need an existing user management system
You want to integrate with other Clerk features (roles, permissions)
You require email/password authentication with verification
You need OAuth providers (Google, GitHub, etc.)
You want to avoid users having to manage passphrases

Limitations and considerations

Online requirement: Initial signup/login requires internet connectivity
Third-party dependency: Relies on Clerk's services for authentication
Not fully local-first: Initial authentication requires a server
Platform support: Not available on all platforms

Additional resources

Clerk Documentation

Docs issue?⌝Join Discord⌝

Passphrase

Better Auth

Clerk Authentication

#How it works

#Key benefits

#Implementation

#Examples

#When to use Clerk

#Limitations and considerations