Clerk

danwo's Clerk emulator is a development instance on Clerk's real hosts. Your server reaches the Backend API, and the browser loads ClerkJS and <SignIn/> from the Frontend API or signs in on the Account Portal. Clerk's SDKs work against it unchanged.

Set upCopy Anchor Link

Add clerkService and hand the app the instance's keys. clerkInstance(…).env() gives every variable Clerk's SDKs read:

import { appEnvironment, clerkInstance, clerkService, defineConfig } from "@danwo/sdk"

const url = "http://localhost:3000"

export default defineConfig({
  testDir: "tests",
  readiness: { mode: "page+backend", settle: true },
  environment: () => {
    const clerk = clerkService({
      seed: {
        instance: { slug: "my-app", origin: url },
        users: [{ email: "[email protected]", password: "correct-horse-battery", firstName: "Ada" }],
        webhooks: [{ endpoint: `${url}/api/webhooks/clerk`, events: ["user.created"] }],
      },
    })

    return appEnvironment({
      app: { command: "npm run dev", url, env: clerkInstance(clerk.emulator).env() },
      services: [clerk],
    })
  },
})

Seed itCopy Anchor Link

Stable idsCopy Anchor Link

A seeded user's id is derived from their email, and an organization's from its slug or name, so user_… is the same on every run. Rows in your own database that point at a Clerk user keep pointing at the right one after a reset. Give an id to choose it yourself.

To seed your own database with the same ids, import stableClerkId from @danwo/sdk:

const id = stableClerkId("user", "[email protected]")

A key that stays putCopy Anchor Link

The emulator signs session tokens with its own key. If your app pins Clerk's public key in a file, seed instance.signingKey with a PKCS#8 PEM so tokens keep verifying across runs. clerkInstance(clerk).publicKeyPem() reads the public half.

Use it in a testCopy Anchor Link

Sign in on the Account Portal, then check the session:

import { type ClerkFixtures, clerkInstance, test as base } from "@danwo/sdk"

const test = base.extend<ClerkFixtures>()

test("signs in with a password", async ({ app, screen, expect, clerk }) => {
  await app.open("/dashboard")
  await screen.getByLabel("Email address").fill("[email protected]")
  await screen.getByLabel("Password").fill("correct-horse-battery")
  await screen.getByRole("button", { name: "Continue" }).click()

  await expect(screen.getByText("Welcome, Ada")).toBeVisible()
  expect(clerkInstance(clerk).sessions("[email protected]")).toHaveLength(1)
})

With emailed codes, read the code with clerkInstance(clerk).code(email) and type it into "Verification code". Addresses with +clerk_test take the code 424242 and get no email, as on a development instance.

clerkMail(clerk) gives the codes to the mail fixture.

users() and memberships() let an invariant check your own rows against Clerk's. Each user lists the social accounts linked to it, such as Google, under external_accounts.

Sign in with GoogleCopy Anchor Link

Seed a social connection and hand clerkService the Google service it signs in on. Clerk's sign-in and sign-up components then show "Continue with Google". The browser picks an account on the Google emulator's chooser, and Clerk signs that person in, links Google to the account with that email, or signs them up:

const google = googleService({
  seed: {
    users: [{ email: "[email protected]", name: "Lin Wu" }],
    oauth_clients: [
      {
        client_id: "my-app.apps.googleusercontent.com",
        client_secret: "my-app-google-secret",
        name: "My app",
        redirect_uris: ["https://my-app.clerk.accounts.dev/v1/oauth_callback"],
      },
    ],
  },
})
const clerk = clerkService({
  social: [google],
  seed: {
    instance: { slug: "my-app" },
    social: [
      {
        provider: "google",
        clientId: "my-app.apps.googleusercontent.com",
        clientSecret: "my-app-google-secret",
      },
    ],
  },
})

Put both in services. The redirect URI is the instance's Frontend API, as with a real Google app.

Organizations and invitationsCopy Anchor Link

<OrganizationSwitcher/> lists the signed-in user's organizations and creates new ones. An invitation goes out like this:

What's coveredCopy Anchor Link

FaultsCopy Anchor Link

The Frontend API and the Account Portal are left alone, so the browser can always sign in.

WebhooksCopy Anchor Link

Deliveries are signed the Svix way, so verifyWebhook from @clerk/nextjs/webhooks and the svix package accept them.

FidelityCopy Anchor Link

Live. danwo fidelity clerk runs 5 scenarios against a real development instance: users, organizations, sessions and keys, errors, and the Frontend API's sign-up and sign-in with test addresses and 424242. All 5 match. Webhooks are checked offline.

Not covered yetCopy Anchor Link

• Social sign-in other than Google, and enterprise sign-in (SAML)
• Phone numbers, SMS codes and passkeys
• Production instances, satellite domains and the Clerk Dashboard
• Billing

NextCopy Anchor Link