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:

  1. Users sign up or sign in through Clerk's authentication system
  2. Jazz securely stores the user's account keys with Clerk
  3. When logging in, Jazz retrieves these keys from Clerk
  4. 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

We offer Clerk integration through our package: jazz-react-auth-clerk.

After installing, use <JazzProviderWithClerk /> to wrap your app:

import * as React from "react";
import { createRoot } from "react-dom/client";
const apiKey = "you@example.com";
const PUBLISHABLE_KEY = "fake_key";
function App() {
  return <div>Hello World</div>;
}
// ---cut---
import { useClerk, ClerkProvider } from '@clerk/clerk-react';
import { JazzProviderWithClerk } from "jazz-react-auth-clerk";

function JazzProvider({ children }: { children: React.ReactNode }) {
  const clerk = useClerk();

  return (
    <JazzProviderWithClerk
      clerk={clerk}
      sync={{
        peer: `wss://cloud.jazz.tools/?key=${apiKey}`,
      }}
    >
      {children}
    </JazzProviderWithClerk>
  );
}

createRoot(document.getElementById("root")!).render(
  <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
    <JazzProvider>
      <App />
    </JazzProvider>
  </ClerkProvider>
);

Once set up, you can use Clerk's auth methods for login and signup:

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> | AnyAccountSchema>(AccountSchema?: A): {
    me: Loaded<A, true>;
    logOut: () => void;
} (+1 overload)
useAccount, function useIsAuthenticated(): booleanuseIsAuthenticated } from "jazz-react";

export function function AuthButton(): React.JSX.ElementAuthButton() {
  const { const logOut: () => voidlogOut } = 
useAccount<AccountClass<Account> | AnyAccountSchema>(AccountSchema?: AccountClass<Account> | AnyAccountSchema | undefined): {
    ...;
} (+1 overload)
useAccount();

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

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

GitHubDocs issue?⌝DiscordJoin Discord⌝
Passphrase
Writing your own