Redirected from /clerkinc/javascript
Clerk JavaScript

https://github.com/clerk/javascript
Admin
The official Clerk JavaScript SDKs provide developers with tools to build user management, including...
Tokens:708,504
Snippets:3,562
Trust Score:8.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies and start dev server

Source: https://github.com/clerk/javascript/blob/main/integration/templates/next-cache-components/README.md

Commands to install dependencies and run the development server for the test app.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Clone the Clerk TanStack Start quickstart template

Source: https://github.com/clerk/javascript/blob/main/integration/templates/tanstack-react-start/README.md

Clone the Clerk TanStack Start quickstart template repository to your local machine.

```bash
git clone https://github.com/clerk/clerk-tanstack-start-quickstart
```

--------------------------------

### Install dependencies and start Expo app

Source: https://github.com/clerk/javascript/blob/main/integration/templates/expo-web/README.md

Install dependencies and start the Expo app. The second command launches the development server, offering options to open the app in a development build, Android emulator, iOS simulator, or Expo Go.

```bash
pnpm install
```

```bash
pnpm expo start
```

--------------------------------

### Full test skeleton with Application setup

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Complete example showing how to set up an Application instance in beforeAll/afterAll hooks, configure parallel mode, and write a test using createTestUtils. The app is cloned from a template, set up, and torn down.

```typescript
import { test } from '@playwright/test';

import type { Application } from '../models/application';
import { appConfigs } from '../presets';

test.describe('Smoke test', () => {
  test.describe.configure({ mode: 'parallel' });
  let app: Application;

  test.beforeAll(async () => {
    // TODO
  });

  test.afterAll(async () => {
    // TODO
  });
});
```

```typescript
import { test } from '@playwright/test';

import type { Application } from '../models/application';
import { appConfigs } from '../presets';

test.describe('Smoke test', () => {
  test.describe.configure({ mode: 'parallel' });
  let app: Application;

  test.beforeAll(async () => {
    app = await appConfigs.react.vite.clone().commit();
    await app.setup();
    await app.withEnv(appConfigs.envs.withEmail);
    await app.dev();
  });

  test.afterAll(async () => {
    await app.teardown();
  });
});
```

```typescript
import { test } from '@playwright/test';

import type { Application } from '../models/application';
import { appConfigs } from '../presets';
import { createTestUtils } from '../testUtils';

test.describe('Smoke test', () => {
  test.describe.configure({ mode: 'parallel' });
  let app: Application;

  test.beforeAll(async () => {
    // ...
  });

  test.afterAll(async () => {
    await app.teardown();
  });

  test('your test', async ({ page, context }) => {
    const u = createTestUtils({ app, page, context });

    // Your tests
  });
});
```

--------------------------------

### Install @clerk/chrome-extension

Source: https://github.com/clerk/javascript/blob/main/packages/chrome-extension/README.md

Install the package using npm.

```bash
npm install @clerk/chrome-extension
```

--------------------------------

### Install @clerk/electron-passkeys

Source: https://github.com/clerk/javascript/blob/main/packages/electron/README.md

Install the optional native module required for native mode passkeys in Electron.

```sh
pnpm add @clerk/electron-passkeys
```

--------------------------------

### Install WebKit for Playwright

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Install the WebKit browser for Playwright testing.

```bash
pnpm playwright install webkit
```

--------------------------------

### Install pkglab globally

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Install pkglab globally using npm.

```bash
npm install -g pkglab
```

--------------------------------

### Install @clerk/nextjs with npm, yarn, or pnpm

Source: https://github.com/clerk/javascript/blob/main/README.md

Install the Clerk SDK for Next.js using your preferred package manager. Choose one of the three commands shown.

```sh
npm install @clerk/nextjs
# or
yarn add @clerk/nextjs
# or
pnpm add @clerk/nextjs
```

--------------------------------

### Install Chromium for Playwright

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Install the Chromium browser for Playwright testing.

```bash
pnpm playwright install chromium
```

--------------------------------

### Eliminate boilerplate with setup<TContext, TEvent>()

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/README.md

Uses setup<TContext, TEvent>() to pre-bind context and event types once per file, eliminating the need to repeat them on every assign call. The assign returned by setup narrows the event type based on its position (e.g., inside on['SET_QUERY'] gives e: { type: 'SET_QUERY'; query: string }).

```ts
import { setup } from '@/mosaic/machine/setup';

const { createMachine, assign } = setup<LoaderContext, LoaderEvent>();

const loader = createMachine({
  // no <LoaderContext, LoaderEvent> needed
  initial: 'idle',
  context: { query: '', data: null, error: null },
  states: {
    idle: {
      on: {
        SET_QUERY: {
          actions: assign((_, e) => ({ query: e.query })), // e: { type: 'SET_QUERY'; query: string } ✓
        },
        FETCH: 'loading',
      },
    },
    loading: {
      invoke: {
        src: async ctx => fetchData(ctx.query),
        onDone: {
          target: 'success',
          actions: assign((_, e) => ({ data: String(e.output), error: null })), // e: DoneInvokeEvent<unknown>
        },
        onError: {
          target: 'failure',
          actions: assign((_, e) => ({ error: String(e.error) })), // e: ErrorInvokeEvent
        },
      },
    },
    success: {},
    failure: { on: { FETCH: 'loading' } },
  },
});
```

--------------------------------

### Install latest Clerk SDK with npm

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/shared/update-version.mdx

Use this command to install the latest version of a Clerk SDK using npm. The placeholder <%= packageName %> should be replaced with the actual package name.

```bash
npm install <%= packageName %>
```

--------------------------------

### Install latest Clerk SDK with yarn

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/shared/update-version.mdx

Use this command to install the latest version of a Clerk SDK using yarn. The placeholder <%= packageName %> should be replaced with the actual package name.

```bash
yarn add <%= packageName %>
```

--------------------------------

### Install latest Clerk SDK with pnpm

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/shared/update-version.mdx

Use this command to install the latest version of a Clerk SDK using pnpm. The placeholder <%= packageName %> should be replaced with the actual package name.

```bash
pnpm add <%= packageName %>
```

--------------------------------

### Basic Toast usage

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/toast/README.md

Basic setup: wrap the app in Toast.Provider, render a viewport with a list of toasts, and add toasts imperatively via useToastManager().add().

```tsx
import { Toast } from '@/primitives/toast';

function App() {
  return (
    <Toast.Provider>
      <SaveButton />
      <Toast.Portal>
        <Toast.Viewport>
          <ToastList />
        </Toast.Viewport>
      </Toast.Portal>
    </Toast.Provider>
  );
}

function ToastList() {
  const { toasts } = Toast.useToastManager();
  return toasts.map(toast => (
    <Toast.Root
      key={toast.id}
      toast={toast}
    >
      <Toast.Content>
        <Toast.Title />
        <Toast.Description />
      </Toast.Content>
      <Toast.Action />
      <Toast.Close aria-label='Close' />
    </Toast.Root>
  ));
}

function SaveButton() {
  const manager = Toast.useToastManager();
  return (
    <button
      type='button'
      onClick={() => manager.add({ title: 'Saved', description: 'Your changes were saved.' })}
    >
      Save
    </button>
  );
}
```

--------------------------------

### Run development server

Source: https://github.com/clerk/javascript/blob/main/integration/templates/next-app-router/README.md

Start the Next.js development server using npm, yarn, or pnpm. The page auto-updates as you edit app/page.tsx.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```

--------------------------------

### ensureInstallationMarker()

Source: https://github.com/clerk/javascript/blob/main/packages/expo-biometrics/README.md

Deletes records and keys left behind by a previous installation of the app. The store functions call it for you.

```APIDOC
## ensureInstallationMarker()

### Description
Deletes records and keys left behind by a previous installation of the app. The store functions call it for you.

### Method
Function

### Signature
`ensureInstallationMarker(): Promise<{ wiped: boolean }>`

### Returns
- **Promise<{ wiped: boolean }>** - Resolves with `{ wiped: boolean }` indicating whether records were wiped.

```

--------------------------------

### Install @clerk/hono

Source: https://github.com/clerk/javascript/blob/main/packages/hono/README.md

Install the @clerk/hono package using npm.

```sh
npm install @clerk/hono
```

--------------------------------

### Initial test file setup

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Create a new file with a .test.ts postfix and import the test function from @playwright/test. The describe block should have a concise name, optionally with annotations like @generic or @nextjs for grep filtering.

```typescript
import { test } from '@playwright/test';

test.describe('Smoke test', () => {});
```

--------------------------------

### Drawer usage example

Source: https://github.com/clerk/javascript/blob/main/packages/swingset/src/stories/drawer.component.mdx

Shows how to compose a Drawer with a trigger button, title, description, and close button. The Popup renders the portal, scrim, box, and grip; Root accepts headless options like open/onOpenChange, snapPoints, dismissible, handleOnly, and autoFocus.

```tsx
import { Button } from '@clerk/mosaic/components/button';
import { Drawer } from '@clerk/mosaic/components/drawer';

<Drawer.Root>
  <Drawer.Trigger render={<Button />}>Sort</Drawer.Trigger>
  <Drawer.Popup>
    <Drawer.Title>Sort members</Drawer.Title>
    <Drawer.Description>Choose how the list is ordered.</Drawer.Description>
    <Drawer.Close>Done</Drawer.Close>
  </Drawer.Popup>
</Drawer.Root>;
```

--------------------------------

### Get user list with clerkClient

Source: https://github.com/clerk/javascript/blob/main/packages/express/README.md

Use clerkClient to access Clerk's Backend API resources. This example retrieves a list of all users using the users.getUserList() method instead of a direct fetch to the API endpoint.

```js
import { clerkClient } from '@clerk/express';
import express from 'express';

const app = express();

app.get('/users', requireAuth, async (req, res) => {
  const users = await clerkClient.users.getUserList();
  return res.json({ users });
});
```

--------------------------------

### Install dependencies with pnpm

Source: https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md

Installs dependencies for all packages in the monorepo. Must be run from the root of the monorepo because pnpm workspaces are used.

```sh
cd javascript
pnpm install
```

--------------------------------

### Using the redirectToSignIn method - After (clerkMiddleware)

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

After migration example using clerkMiddleware() and the redirectToSignIn() helper to redirect unauthenticated users to the sign-in page.

```TypeScript
import { clerkMiddleware, redirectToSignIn } from "@clerk/nextjs/server"

export default clerkMiddleware((auth, req) => {
  if (!auth().userId) return redirectToSignIn()
})

export const config = {
  matcher: ["/((?!.+\.[\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}
```

--------------------------------

### Combining with other Middlewares (like i18n) - Before (authMiddleware)

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

Before migration example showing how authMiddleware() was combined with an i18n middleware using the 'beforeAuth' option.

```TypeScript
import { authMiddleware } from "@clerk/nextjs"
import createMiddleware from "next-intl/middleware"

const intlMiddleware = createMiddleware({
  locales: ["en", "de"],
  defaultLocale: "en"
})

export default authMiddleware({
  beforeAuth: intlMiddleware,
})

export const config = {
  matcher: ["/((?!.+\.[\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}
```

--------------------------------

### Combining with other Middlewares (like i18n) - After (clerkMiddleware)

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

After migration example showing how to combine clerkMiddleware() with an i18n middleware by wrapping it inside the clerkMiddleware callback.

```TypeScript
import { clerkMiddleware } from "@clerk/nextjs/server"
import createMiddleware from "next-intl/middleware"

const intlMiddleware = createMiddleware({
  locales: ["en", "de"],
  defaultLocale: "en"
})

export default clerkMiddleware((auth, req) => {
  intlMiddleware(req)
  auth().protect()
})

export const config = {
  matcher: ["/((?!.+\.[\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}
```

--------------------------------

### Setup ClerkProvider with passkeys

Source: https://github.com/clerk/javascript/blob/main/packages/expo-passkeys/README.md

Import the ClerkProvider and passkeys from @clerk/expo and @clerk/expo/passkeys, then wrap your app with the provider and pass the passkeys object to the __experimental_passkeys prop.

```tsx
import { ClerkProvider } from '@clerk/expo';
import { passkeys } from '@clerk/expo/passkeys';

<ClerkProvider __experimental_passkeys={passkeys}>{/* Your app here */}</ClerkProvider>;
```

--------------------------------

### Run @clerk/upgrade CLI

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/README.md

Run the CLI from the root of the project you want to upgrade. Requires Node.js >=20.9.0 and pnpm, npm, or yarn installed in the target project.

```sh
# with pnpm
pnpm dlx @clerk/upgrade

# with npm
npx @clerk/upgrade

# if installed locally
pnpm clerk-upgrade
```

--------------------------------

### Install @clerk/eslint-plugin

Source: https://github.com/clerk/javascript/blob/main/packages/eslint-plugin/README.md

Install the plugin as a development dependency. Requires ESLint >=9 (flat config); also works with Oxlint when configured as a jsPlugin.

```sh
npm install --save-dev @clerk/eslint-plugin
```

--------------------------------

### JSDoc example for a documented function

Source: https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md

This example demonstrates the recommended JSDoc style for documenting a function, including parameter and return type annotations, @example blocks with h3 headings, and a @default annotation for optional parameters. It is used as a reference for contributing to Clerk's SDKs.

```typescript
type FnParameters = {
  /**
   * Input to the function with a lengthy and good description.
   */
  input: string | Array<string>;
  /**
   * Optional parameter with a default value.
   * @default false
   */
  isOffline?: boolean;
};

type FnReturn = Array<string>;

/**
 * Some long description goes here.
 *
 * > [!NOTE]
 * > This is a note that will be rendered in the documentation.
 *
 * @example
 * ### Example 1
 *
 * This shows how to use the function with a single string input.
 *
 * ```tsx
 * const result = exampleFunction({ input: 'example' });
 * console.log(result); // Output: ['example']
 * ```
 *
 * @example
 * ### Example 2
 *
 * This shows how to use the function with an array of strings as input.
 *
 * ```tsx
 * const result = exampleFunction({ input: ['example1', 'example2'] });
 * console.log(result); // Output: ['example1', 'example2']
 * ```
 */
export function exampleFunction({ input, isOffline = false }: FnParameters): FnReturn {
  if (isOffline) {
    return [];
  }

  if (Array.isArray(input)) {
    return input;
  }

  return [input];
}
```

--------------------------------

### Using the redirectToSignIn method - Before (authMiddleware)

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

Before migration example using authMiddleware() with a custom 'afterAuth' callback that redirects unauthenticated users to the sign-in page.

```TypeScript
import { authMiddleware } from "@clerk/nextjs"

export default authMiddleware({
  afterAuth(auth, req) {
    if (!auth.userId && !auth.isPublicRoute) {
      return Response.redirect(new URL("/sign-in", req.url))
    }
  },
})

export const config = {
  matcher: ["/((?!.+\.[\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}
```

--------------------------------

### Install @clerk/testing

Source: https://github.com/clerk/javascript/blob/main/packages/testing/README.md

Install the @clerk/testing package as a dev dependency. Requires Node.js >=20.9.0 and Playwright v1+ or Cypress v13.x or 14.x.

```shell
npm install @clerk/testing --save-dev
```

--------------------------------

### Configure Clerk appearance prop with theme, variables, and elements

Source: https://github.com/clerk/javascript/blob/main/references/theming-architecture.md

Shows how to pass the `appearance` prop to `<ClerkProvider>` to customize Clerk components. The example uses the `dark` prebuilt theme, sets design tokens via `variables`, applies per-element CSS overrides via `elements`, and demonstrates per-component overrides for `signIn`. Note the `appearance` prop can also be passed directly to individual components like `<SignIn>`.

```tsx
import { ClerkProvider } from '@clerk/nextjs';
import { dark } from '@clerk/themes';

<ClerkProvider
  appearance={{
    // 1. Prebuilt theme (optional base)
    theme: dark,

    // 2. Design tokens — colors, fonts, spacing, radii
    variables: {
      colorPrimary: '#6C47FF',
      fontFamily: 'Inter',
      borderRadius: '0.5rem',
    },

    // 3. Per-element CSS overrides (static object or function)
    elements: {
      card: { boxShadow: 'none' },
      formButtonPrimary: {
        backgroundColor: '#6C47FF',
        '&:hover': { backgroundColor: '#5A38E0' },
      },
    },

    // 4. Per-component overrides
    signIn: {
      variables: { colorPrimary: 'red' },
      elements: { headerTitle: { color: 'red' } },
    },
  }}
/>;
```

--------------------------------

### Create a story file for a new component

Source: https://github.com/clerk/javascript/blob/main/packages/swingset/README.md

Example story file for a new component. Defines metadata with group, title, source path, and variant styles. The Default export renders the component with props. Knobs are generated from _variants and _defaultVariants.

```tsx
import type { StoryMeta } from '@/lib/types';
import { MyComponent, type MyComponentProps } from '@clerk/mosaic/components/my-component';

export const meta: StoryMeta = {
  group: 'Components',
  title: 'My Component',
  source: 'packages/mosaic/src/components/my-component/my-component.tsx', // repo-root path → "View source" link
  // Variant surface, declared by hand — knobs are generated from `_variants`
  styles: {
    _variants: { variant: { primary: {}, outline: {} }, size: { sm: {}, md: {} } },
    _defaultVariants: { variant: 'primary', size: 'md' },
  },
};

export function Default(props: Record<string, unknown>) {
  return <MyComponent {...(props as MyComponentProps)}>Content</MyComponent>;
}
```

--------------------------------

### Run Swingset dev server with pnpm

Source: https://github.com/clerk/javascript/blob/main/packages/swingset/README.md

Starts the Swingset development server for the Mosaic design system. Runs at http://localhost:6006.

```bash
pnpm dev --filter @clerk/swingset
```

--------------------------------

### Install @clerk/mosaic with npm, pnpm, or yarn

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/README.md

Install the @clerk/mosaic package with exact version pinning using npm, pnpm, or yarn. The --save-exact or --exact flag ensures the exact version is saved, which is recommended because the package may introduce breaking changes in minor releases.

```shell
npm install --save-exact @clerk/mosaic
pnpm add --save-exact @clerk/mosaic
yarn add --exact @clerk/mosaic
```

--------------------------------

### Set props for the SignIn component

Source: https://github.com/clerk/javascript/blob/main/packages/clerk-js/sandbox/README.md

Example of setting props for the `SignIn` component using `components.signIn.setProps`. The props are reflected in the URL as query parameters.

```javascript
components.signIn.setProps({
  /* ... */
});
```

--------------------------------

### Accordion.Root

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/accordion/README.md

Documentation for the Accordion.Root component, including its props and usage example.

```APIDOC
## [COMPONENT] Accordion.Root

### Description
Root wrapper for the Accordion component. Provides context for all child parts and manages the open/closed state of items.

### Props
- `value` (string[]) - Optional - Controlled open items
- `defaultValue` (string[]) - Optional - Initial open items (uncontrolled), default `[]`
- `onValueChange` ((value: string[]) => void) - Optional - Called when open items change
- `type` ("single" | "multiple") - Optional - `"single"` enforces at most one open item, default `"multiple"`
- `disabled` (boolean) - Optional - Disables all items, default `false`

### Example
```tsx
<Accordion.Root
  type='single'
  defaultValue={['item-1']}
>
  {/* ... */}
</Accordion.Root>
```
```

--------------------------------

### Define a Platform API configuration file

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Defines a configuration file for a Platform API application. The config sets user lockout max attempts from an environment variable. The optional setup function receives a ClerkClient and patchConfig method to make PATCH requests to the Platform API. Omit setup when no additional operations are required.

```js
import { defineConfig } from '../presets/platformApplication.js';

export default defineConfig({
  config: {
    auth_attack_protection: {
      user_lockout: {
        max_attempts: Number(process.env.CLERK_E2E_USER_LOCKOUT_MAX_ATTEMPTS || 10),
      },
    },
  },
  setup: async ({ clerkClient, patchConfig }) => {
    await clerkClient.instance.update({ allowedOrigins: ['clerk://app'] });
    await patchConfig({
      organization_settings: {
        domains_default_role: 'org:viewer',
      },
    });
  },
});
```

--------------------------------

### Basic Flow.Root and Flow.Step usage

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/flow/README.md

Shows how to render a multi-step flow using Flow.Root and Flow.Step. The controller owns the active value and direction. Multiple ids can select the same step, and moving between them updates the existing step without starting a transition.

```tsx
import { Flow } from '../../primitives/flow';

<Flow.Root
  value={machine.status}
  direction={machine.direction}
>
  <Flow.Step ids={['enter-password', 'enter-password-pending', 'enter-password-error']}>
    <PasswordView {...passwordViewProps} />
  </Flow.Step>
  <Flow.Step ids={['enter-code', 'enter-code-pending', 'enter-code-error']}>
    <OtpView {...otpViewProps} />
  </Flow.Step>
</Flow.Root>;
```

--------------------------------

### Protecting a single route path - After (clerkMiddleware)

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

After migration example using clerkMiddleware() and createRouteMatcher() to protect only the '/dashboard' route.

```TypeScript
import {
  clerkMiddleware,
  createRouteMatcher
} from "@clerk/nextjs/server"

const isDashboardRoute = createRouteMatcher(["/dashboard"])

export default clerkMiddleware((auth, req) => {
  if (isDashboardRoute(req)) auth().protect()
})

export const config = {
  matcher: ["/((?!.+\.[\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}
```

--------------------------------

### Run a machine with createActor

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/README.md

Wraps a machine in an actor to run it. Subscribes to snapshots, starts the actor, and sends a FETCH event to trigger state transitions. The snapshot provides value and context.

```ts
import { createActor } from '@/mosaic/machine/create-actor';

const actor = createActor(loader);

actor.subscribe(snapshot => {
  console.log(snapshot.value); // 'idle' | 'loading' | 'success' | 'failure'
  console.log(snapshot.context); // { data, error }
});

actor.start();
actor.send({ type: 'FETCH' }); // → 'loading', then 'success'/'failure' when the promise settles
```

--------------------------------

### Route protection with clerkMiddleware() and createRouteMatcher()

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

Example showing how to protect routes based on authentication and authorization using clerkMiddleware() and createRouteMatcher(). It defines route matchers for dashboard and admin routes, then uses auth().protect() to restrict access. The config matcher is also included.

```TypeScript
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';

const isDashboardRoute = createRouteMatcher(['/dashboard(.*)']);
const isAdminRoute = createRouteMatcher(['/admin(.*)']);

export default clerkMiddleware((auth, req) => {
  // Restrict admin route to users with specific role
  if (isAdminRoute(req)) auth().protect({ role: 'org:admin' });

  // Restrict dashboard routes to logged in users
  if (isDashboardRoute(req)) auth().protect();
});

export const config = {
  matcher: ['/((?!.*\..*|_next).*)', '/', '/(api|trpc)(.*)'],
};
```

--------------------------------

### Create a passkey

Source: https://github.com/clerk/javascript/blob/main/packages/expo-passkeys/README.md

Use the useUser hook to get the user object, then call user.createPasskey() to create a passkey. Handle errors in the catch block.

```tsx
const { user } = useUser();

const handleCreatePasskey = async () => {
  if (!user) return;
  try {
    return await user.createPasskey();
  } catch (e: any) {
    // handle error
  }
};
```

--------------------------------

### Create Clerk instance before ClerkProvider renders

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/versions/core-3/changes/expo-clerk-export-removed.md

TypeScript example showing how to create a Clerk instance before `ClerkProvider` renders by passing the `publishableKey` to `getClerkInstance()`. The instance can then be used outside of React.

```tsx
import { ClerkProvider, getClerkInstance } from '@clerk/expo';

const clerkInstance = getClerkInstance({ publishableKey: 'pk_xxx' });

// Use the instance outside of React
const token = await clerkInstance.session?.getToken();
```

--------------------------------

### After: createWizardMachine factory and actor usage

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/README.md

The new approach: a factory that builds an XState machine from wizard descriptors, where each step is a state node with an entry guard and NEXT/PREV/GOTO transitions. The initial state is derived as the furthest reachable step. Driving it requires no refs or render-phase passes: create an actor, start it, send events, and call recheck() when external data changes.

```ts
function createWizardMachine(descriptors) {
  const ids = descriptors.map(d => d.id);
  const guardHolds = d => (d.guard ? d.guard() : true);

  const furthestReachable = () => {
    if (descriptors.length === 0) return '';
    let i = 0;
    while (i + 1 < descriptors.length && guardHolds(descriptors[i + 1])) i++;
    return descriptors[i].id;
  };
  const navigated = direction => assign(() => ({ direction, hasNavigated: true }));

  const states = {};
  descriptors.forEach((d, i) => {
    const nextId = ids[i + 1];
    const prevId = ids[i - 1];
    states[d.id] = {
      guard: d.guard, // entry guard — gates every transition that targets this step
      on: {
        ...(nextId ? { NEXT: { target: nextId, actions: navigated(1) } } : {}),
        ...(prevId ? { PREV: { target: prevId, actions: navigated(-1) } } : {}),
        GOTO: descriptors
          .filter(t => t.id !== d.id)
          .map(t => ({ target: t.id, guard: (_c, e) => e.step === t.id, actions: navigated(0) })),
      },
    };
  });

  return createMachine({
    id: 'wizard',
    initial: furthestReachable,
    context: { direction: 0, hasNavigated: false },
    states,
  });
}
```

```ts
const actor = createActor(createWizardMachine(descriptors));
actor.start(); // seats on the furthest-reachable step
actor.send({ type: 'NEXT' }); // advances iff the next step's entry guard holds
actor.recheck(); // external data changed → re-seat off a now-broken step
```

--------------------------------

### createActor(machine, options?)

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/README.md

Creates a running instance of a machine. The actor provides methods to start, stop, send events, get snapshots, subscribe, check if an event can be sent, and recheck guards.

```APIDOC
## createActor(machine, options?)

### Description
Creates a running instance of a machine. The actor provides methods to start, stop, send events, get snapshots, subscribe, check if an event can be sent, and recheck guards.

### Parameters
- **machine** (object) - Required - The machine definition created by `createMachine`.
- **options** (object) - Optional - Additional options for the actor.

### Returns
- **actor** (object) - The actor instance with the following methods:
  - `.start()` - Starts the actor.
  - `.stop()` - Stops the actor.
  - `.send(event)` - Sends an event to the actor.
  - `.getSnapshot()` - Returns the current snapshot.
  - `.subscribe(fn)` - Subscribes a listener to snapshot changes.
  - `.can(event)` - Checks if an event can be sent in the current state.
  - `.recheck()` - Re-evaluates guards that read external data.

```

--------------------------------

### Profile component usage example

Source: https://github.com/clerk/javascript/blob/main/packages/swingset/src/stories/profile.component.mdx

Shows how to compose the Profile component with navigation items and content panels. Root is controlled via value and onValueChange. NavItem and ContentPanel pair by value. Badge defaults to neutral unless color is set. Title is visually hidden and names the navigation and dialog.

```tsx
import { Badge } from '@clerk/mosaic/components/badge';
import { Icon } from '@clerk/mosaic/components/icon';
import { Profile } from '@clerk/mosaic/components/profile';

<Profile.Root
  value={page}
  onValueChange={setPage}
>
  <Profile.Title>User profile</Profile.Title>
  <Profile.Nav>
    <Profile.NavItem
      value='account'
      icon={<Icon name='user-circle' size='sm' />}
    >
      Account
    </Profile.NavItem>
    <Profile.NavItem
      value='security'
      icon={<Icon name='shield-check' size='sm' />}
      badge={<Badge>2</Badge>}
    >
      Security
    </Profile.NavItem>
  </Profile.Nav>
  <Profile.Content>
    <Profile.ContentPanel value='account'>…</Profile.ContentPanel>
    <Profile.ContentPanel value='security'>…</Profile.ContentPanel>
  </Profile.Content>
</Profile.Root>;
```

--------------------------------

### Default project structure

Source: https://github.com/clerk/javascript/blob/main/integration/templates/astro-node/README.md

Shows the default folders and files created by the Astro Starter Kit: Basics template.

```text
/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       └── index.astro
└── package.json
```

--------------------------------

### Create sign-in start machine with activeStrategy and use in React

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/ADOPTION.md

The machine defines a single 'submitting' state with an 'activeStrategy' context field, replacing separate loading hooks. The React component uses 'useMachine' to consume the machine, deriving 'isLocked' from the state value and 'active' from context to control button loading states and error display.

```ts
import { setup } from '@/mosaic/machine/setup';

interface SignInStartContext {
  activeStrategy: OAuthStrategy | 'email' | null;
  identifier: string;
  error: string | null;
  signInFn: (params: SignInCreateParams) => Promise<SignInResource>;
}

type SignInStartEvent =
  | { type: 'CLICK_SOCIAL'; strategy: OAuthStrategy }
  | { type: 'TYPE_IDENTIFIER'; value: string }
  | { type: 'SUBMIT_IDENTIFIER' };

const { createMachine, assign } = setup<SignInStartContext, SignInStartEvent>();

export function createSignInStartMachine(deps: { signInFn: SignInStartContext['signInFn'] }) {
  return createMachine({
    initial: 'idle',
    context: { activeStrategy: null, identifier: '', error: null, signInFn: deps.signInFn },
    states: {
      idle: {
        on: {
          CLICK_SOCIAL: {
            target: 'submitting',
            actions: assign((_, e) => ({ activeStrategy: e.strategy })),
          },
          TYPE_IDENTIFIER: {
            actions: assign((_, e) => ({ identifier: e.value, error: null })),
          },
          SUBMIT_IDENTIFIER: {
            target: 'submitting',
            actions: assign(() => ({ activeStrategy: 'email' as const })),
          },
        },
      },
      submitting: {
        // Both entry points converge here. idle's on-handlers are inactive,
        // so a second CLICK_SOCIAL while already submitting is dropped automatically.
        invoke: {
          src: ctx =>
            ctx.activeStrategy === 'email'
              ? ctx.signInFn({ identifier: ctx.identifier })
              : ctx.signInFn({ strategy: ctx.activeStrategy! }),
          onDone: 'success',
          onError: {
            target: 'idle',
            actions: assign((_, e) => ({ error: String(e.error), activeStrategy: null })),
          },
        },
      },
      success: { type: 'final' },
    },
  });
}
```

```tsx
const [snapshot, send] = useMachine(signInStartMachine, {
  context: { signInFn: params => signIn.create(params) },
  onDone: () => setActive({ session: signIn.createdSessionId }),
});

const isLocked = snapshot.value === 'submitting';
const active = snapshot.context.activeStrategy;

// Social buttons:
{oauthStrategies.map(strategy => (
  <SocialButton
    key={strategy}
    disabled={isLocked}
    isLoading={isLocked && active === strategy}
    onClick={() => send({ type: 'CLICK_SOCIAL', strategy })}
  />
))}

// Identifier form:
<input
  disabled={isLocked}
  onChange={e => send({ type: 'TYPE_IDENTIFIER', value: e.target.value })}
/>
<SubmitButton
  disabled={isLocked}
  isLoading={isLocked && active === 'email'}
  onClick={() => send({ type: 'SUBMIT_IDENTIFIER' })}
/>
{snapshot.context.error && <FieldError>{snapshot.context.error}</FieldError>}
```

--------------------------------

### Create a new Astro project with the basics template

Source: https://github.com/clerk/javascript/blob/main/integration/templates/astro-node/README.md

Run this command in your terminal to scaffold a new Astro project using the 'basics' template.

```sh
npm create astro@latest -- --template basics
```

--------------------------------

### Use Application lifecycle in a Playwright test

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Shows the full lifecycle of an Application in a Playwright test: setup, set environment variables with withEnv, start the dev server, and teardown in afterAll. The test body is left as a TODO placeholder.

```ts
import { expect, test } from '@playwright/test';

import type { Application } from '../models/application';
import { appConfigs } from '../presets';

test.describe('Your test', () => {
  test.describe.configure({ mode: 'parallel' });
  let app: Application;

  test.beforeAll(async () => {
    app = await appConfigs.react.vite
      .clone()
      .addFile(
        'src/metadata.ts',
        () => `export const metadata = {
  name: 'Hello World',
}`,
      )
      .commit();

    // Run the 'setup' npm script and do other setup stuff
    await app.setup();
    // Set the environment variables
    await app.withEnv(appConfigs.envs.withEmailCodes);
    // Start the development server through the 'dev' npm script
    await app.dev();
  });

  test.afterAll(async () => {
    // Remove the temporary test folder and any temporary artifacts
    await app.teardown();
  });

  test('your tests', async ({ page }) => {
    // TODO
  });
});
```

--------------------------------

### Controlled Menu

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/menu/README.md

Use the open and onOpenChange props to control the menu's open state. The example shows a state variable and a comment placeholder for the menu content.

```tsx
const [open, setOpen] = useState(false);

<Menu.Root
  open={open}
  onOpenChange={setOpen}
>
  {/* ... */}
</Menu.Root>;
```

--------------------------------

### Install @clerk/expo-biometrics with npx expo install

Source: https://github.com/clerk/javascript/blob/main/packages/expo-biometrics/README.md

Installs the @clerk/expo-biometrics package in an Expo project. After running this command, you must rebuild your native app.

```sh
npx expo install @clerk/expo-biometrics
```

--------------------------------

### Migrate from `__experimental_simple` import to `appearance` prop

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/versions/core-3/changes/simple-theme-usage-changed.md

Shows the migration from importing the `__experimental_simple` theme from `@clerk/ui` to using the `appearance` prop with `theme: 'simple'` directly on `ClerkProvider`.

```diff
- import { __experimental_simple } from '@clerk/ui';
-
- <ClerkProvider appearance={{ baseTheme: __experimental_simple }}>
+ <ClerkProvider appearance={{ theme: 'simple' }}>
    {/* Your app */}
  </ClerkProvider>
```

--------------------------------

### Install @clerk/express

Source: https://github.com/clerk/javascript/blob/main/packages/express/README.md

Install the @clerk/express package to add Clerk authentication to your Express application.

```sh
npm install @clerk/express
```

--------------------------------

### Add @examples/msw workspace dependency

Source: https://github.com/clerk/javascript/blob/main/packages/msw/README.md

Adds the @examples/msw package as a workspace dependency in the consuming app's package.json.

```json
{
  "dependencies": {
    "@examples/msw": "workspace:*"
  }
}
```

--------------------------------

### Run, build, and format @clerk/swingset

Source: https://github.com/clerk/javascript/blob/main/packages/swingset/CLAUDE.md

Run the swingset dev server on port 6006, build the Next.js app, and format the package. The format command uses format-package.mjs and supports a --check flag for CI. There is no lint script in this package.

```bash
pnpm run dev:swingset                # next dev on port 6006
pnpm build --filter @clerk/swingset  # next build
pnpm format --filter @clerk/swingset # format-package.mjs (--check for CI)
```

--------------------------------

### Set sign-in/up URLs for @clerk/nextjs

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/shared/path-routing.mdx

For the @clerk/nextjs SDK, set these environment variables in .env.local to define the sign-in and sign-up URLs, avoiding the need to pass the path prop to <SignIn /> and <SignUp />.

```env
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
```

--------------------------------

### Check installed @clerk/shared versions

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/README.md

Check the installed versions of @clerk/shared to see if multiple versions remain after deduplication. If multiple versions remain, the supported ranges are likely incompatible.

```shell
npm ls @clerk/shared
pnpm why @clerk/shared
yarn why @clerk/shared
```

--------------------------------

### Renderer (vanilla): createPasskeyProvider before clerk.load()

Source: https://github.com/clerk/javascript/blob/main/packages/electron/README.md

Wire up passkeys manually when managing the Clerk instance yourself, before calling clerk.load().

```ts
// renderer process (vanilla)
import { Clerk } from '@clerk/clerk-js';
import { createPasskeyProvider } from '@clerk/electron/passkeys';

const clerk = new Clerk(publishableKey);
createPasskeyProvider(clerk);
await clerk.load();
```

--------------------------------

### Install React 18 or higher with npm, yarn, or pnpm

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/shared/react-version.mdx

Install the latest versions of react and react-dom using your preferred package manager. Required for all react-dependent Clerk SDKs, which now require React 18 or higher.

```bash
npm install react@latest react-dom@latest
```

```bash
yarn add react@latest react-dom@latest
```

```bash
pnpm add react@latest react-dom@latest
```

--------------------------------

### Build Command

Source: https://github.com/clerk/javascript/blob/main/packages/electron-passkeys/README.md

Build the package from source. Requires a Rust toolchain.

```shell
pnpm --filter @clerk/electron-passkeys build
```

--------------------------------

### Assign without setup requires explicit types

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/README.md

Shows the verbose type annotations required when using assign without setup. The context and event types must be explicitly restated on every assign call.

```ts
// Without setup — types must be restated every time
assign<LoaderContext, Extract<LoaderEvent, { type: 'SET_QUERY' }>>((_, e) => ({
  query: e.query,
}));
```

--------------------------------

### Accordion.Item

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/accordion/README.md

Documentation for the Accordion.Item component, including its props and usage example.

```APIDOC
## [COMPONENT] Accordion.Item

### Description
Wraps a single collapsible section within the Accordion. Must have a unique `value` prop.

### Props
- `value` (string) - Required - Unique identifier for this item
- `disabled` (boolean) - Optional - Disables this specific item, inherits root by default

### Example
```tsx
<Accordion.Item value='item-1'>
  {/* ... */}
</Accordion.Item>
```
```

--------------------------------

### Run tests against an already running app

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Fast-track tests against an already running app on localhost:3000 by providing environment variables for app secret key, publishable key, URL, and clerk-js URL. Replace the placeholder values with your own.

```shell
E2E_APP_SK=sk_test_xxx E2E_APP_PK=pk_test_xxx E2E_APP_URL=http://localhost:3000 E2E_APP_CLERK_JS=https://xxx.clerk.accounts.dev/npm/@clerk/clerk-js@5/dist/clerk.browser.js pnpm test:integration:base -- --ui
```

--------------------------------

### Handle-only dragging

Source: https://github.com/clerk/javascript/blob/main/packages/swingset/src/stories/drawer.mdx

Handle-only dragging. Only a press starting on Drawer.Handle initiates the drag; the body scrolls normally.

```tsx
<Drawer.Root handleOnly>{/* portal */}</Drawer.Root>
```

--------------------------------

### Snap points configuration

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/drawer/README.md

Shows how to configure snap points and the default active snap point.

```tsx
// Ascending fractions of the viewport the sheet can rest at; 1 = full height.
<Drawer.Root
  snapPoints={[0.4, 0.75, 1]}
  defaultActiveSnapPoint={0}
>
  {/* ... */}
</Drawer.Root>
```

--------------------------------

### useState booleans example

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/README.md

Shows the typical pile of useState booleans that a flow is built from, which can lead to impossible combinations.

```tsx
const [isOpen, setIsOpen] = useState(false);
const [isDeleting, setIsDeleting] = useState(false);
const [error, setError] = useState(null);
const [confirmValue, setConfirmValue] = useState('');
```

--------------------------------

### Basic migration from authMiddleware() to clerkMiddleware()

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

Diff showing the most basic migration: updating the import and changing the default export to mirror the previous behavior of protecting all routes. The config matcher remains unchanged.

```Diff
- import { authMiddleware } from "@clerk/nextjs"
+ import { clerkMiddleware } from '@clerk/nextjs/server'

- export default authMiddleware()
+ export default clerkMiddleware((auth) => auth().protect())

  export const config = {
    matcher: ["/((?!.*\..*|_next).*)", "/", "/(api|trpc)(.*)"],
  }
```

--------------------------------

### Import Appearance from @clerk/ui

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/versions/core-3/changes/clerk-types-deprecation.md

The `Appearance` type should be imported from `@clerk/ui` instead of `@clerk/shared/types`. This is a special case noted in the deprecation guide.

```diff
- import type { Appearance } from '@clerk/types';
+ import type { Appearance } from '@clerk/ui';
```

--------------------------------

### Set sign-in/up URLs for @clerk/remix

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/shared/path-routing.mdx

For the @clerk/remix SDK, set these environment variables in .env to define the sign-in and sign-up URLs, avoiding the need to pass the path prop to <SignIn /> and <SignUp />.

```env
CLERK_SIGN_IN_URL=/sign-in
CLERK_SIGN_UP_URL=/sign-up
```

--------------------------------

### Protecting a single route path - Before (authMiddleware)

Source: https://github.com/clerk/javascript/blob/main/packages/upgrade/src/guide-generators/core-2/nextjs/middleware-changes.mdx

Before migration example using authMiddleware() to protect only the '/dashboard' route by specifying it in the 'protectedRoutes' option.

```TypeScript
import { authMiddleware } from "@clerk/nextjs"

export default authMiddleware({
  protectedRoutes: ["/dashboard"],
})

export const config = {
  matcher: ["/((?!.+\.[\w]+$|_next).*)", "/", "/(api|trpc)(.*)"],
}
```

--------------------------------

### Main process: createClerkBridge with passkeys

Source: https://github.com/clerk/javascript/blob/main/packages/electron/README.md

Initialize the Clerk bridge in the main process with passkeys enabled.

```ts
// main process
import { createClerkBridge } from '@clerk/electron';
import { storage } from '@clerk/electron/storage';

createClerkBridge({ storage: storage(), passkeys: true });
```

--------------------------------

### Before: SignInStart state with useLoadingStatus and useState

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/machine/ADOPTION.md

The original SignInStart component state management using useLoadingStatus and multiple useState hooks. This shows the scattered state that the machine migration aims to consolidate.

```tsx
const status = useLoadingStatus();      // 'idle' | 'loading' | 'error'
// …
const [alternativePhoneCodeProvider, setAlternativePhoneCodeProvider] =
  useState<PhoneCodeChannelData | null>(null);
// …
const [shouldAutofocus,    setShouldAutofocus]    = useState(!isMobileDevice() && !hasSocialOrWeb3Buttons);
const [hasSwitchedByAutofill, setHasSwitchedByAutofill] = useState(false);
const [identifierAttribute, setIdentifierAttribute] = useState<SignInStartIdentifier>(…);
```

--------------------------------

### Override npm script with addScript

Source: https://github.com/clerk/javascript/blob/main/integration/README.md

Overrides the default npm script for 'dev' in a preset. Similar methods exist for 'setup', 'build', and 'serve'.

```ts
.addScript('dev', 'pnpm dev')
```

--------------------------------

### Controlled Tabs

Source: https://github.com/clerk/javascript/blob/main/packages/mosaic/src/primitives/tabs/README.md

Use the value and onValueChange props to control the active tab. The example shows a state variable and setter passed to the Tabs component.

```tsx
const [value, setValue] = useState('tab1');

<Tabs
  value={value}
  onValueChange={setValue}
>
  {/* ... */}
</Tabs.Root>;
```
Tokens:
Raw