Migrate from Clerk

Wocha provides equivalent features to Clerk with additional enterprise capabilities like SpiceDB permissions, custom actions, and self-hosting.

Concept mapping

Clerk	Wocha
`ClerkProvider`	`GreetSessionProvider` (Next.js) / `WochaProvider` (React)
`clerkMiddleware()`	`withWochaAuth()`
`auth()`	`getSession()` / `requireSession()`
`currentUser()`	`getUser()`
`<SignIn />`	`<SignIn />` (`@wocha/ui` or headless)
`<UserButton />`	`<UserButton />` (`@wocha/ui`)
`useUser()`	`useUser()`
`useOrganization()`	`useOrg()`
Organization	Organisation
Webhook	Webhook
Backend API	Customer API

Step 1: Install Wocha

npm uninstall @clerk/nextjs
npm install @wocha/nextjs
npx @wocha/cli init --cloud

Step 2: Replace providers

// Before (Clerk)
import { ClerkProvider } from '@clerk/nextjs';
 
// After (Wocha)
import { GreetSessionProvider } from '@wocha/nextjs/client';

Step 3: Replace middleware

// Before (Clerk)
import { clerkMiddleware } from '@clerk/nextjs/server';
export default clerkMiddleware();
 
// After (Wocha)
import { withWochaAuth } from '@wocha/nextjs/middleware';
export default withWochaAuth();

Step 4: Replace server helpers

// Before (Clerk)
import { auth, currentUser } from '@clerk/nextjs/server';
const { userId } = await auth();
const user = await currentUser();
 
// After (Wocha)
import { getSession, getUser } from '@wocha/nextjs/server';
const session = await getSession();
const user = await getUser();

Step 5: Replace hooks

// Before (Clerk)
import { useUser, useOrganization } from '@clerk/nextjs';
 
// After (Wocha)
import { useUser, useOrg } from '@wocha/nextjs/client';

Step 6: Migrate users

CLI migration (recommended)

Always preview the migration first:

export WOCHA_MANAGEMENT_API_KEY=wocha_mgmt_...
export WOCHA_TENANT=your-tenant
 
wocha migrate clerk --dry-run
wocha migrate clerk

The --dry-run flag parses and validates Clerk users without creating anything in Wocha. It reports user counts, duplicate emails, and missing fields, and writes a JSON migration plan to wocha-migrate-plan-clerk-*.json.

After import, verify the migration:

wocha migrate clerk --validate

Validation checks that all Clerk users exist in Wocha (matched by email) and reports any discrepancies.

Manual import via SDK

import { WochaClient } from '@wocha/sdk';
 
const wocha = new WochaClient({ apiKey, tenant });
for (const user of clerkUsers) {
  await wocha.users.create({
    email: user.emailAddresses[0].emailAddress,
    name: `${user.firstName} ${user.lastName}`,
    metadata: { clerk_id: user.id },
  });
}

Step 7: Update environment variables

Clerk	Wocha
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	`WOCHA_CLIENT_ID`
`CLERK_SECRET_KEY`	`WOCHA_CLIENT_SECRET`
—	`WOCHA_ISSUER`

Step 8: Verify

npx @wocha/cli doctor
npx @wocha/cli test-login

Migrate from Clerk

On this page