DEV Community: Ship Kit

Moving off Clerk to Better Auth: what's mechanical and what's a rebuild

Ship Kit — Mon, 12 Oct 2026 23:51:57 +0000

I've done a fair number of NextAuth to Better Auth moves, and they're mostly mechanical: same general shape, swap the library, fix a few call sites. Clerk is a different animal, and you should know that going in.

NextAuth is a library. Clerk is a hosted product: pre-built React components plus a hosted user store that lives on Clerk's servers. When you move off Clerk you're not swapping one auth library for another — you're replacing UI you never wrote, re-implementing session logic Clerk did for you, and migrating user records out of someone else's database. The import rewrites are find-and-replace. The rest is a rebuild. This post walks the whole thing so you can scope it honestly before you start.

Coming from NextAuth instead? See the companion guide: Migrating from NextAuth to Better Auth.

The two halves of a Clerk migration

Split the work into two buckets:

Mechanical — imports and session calls. A codemod can handle the textual part and flag the spots where the return shapes don't line up.
Rebuild — UI components, middleware, the auth config, and the user-data export. None of this is find-and-replace, because Clerk did it for you and Better Auth expects you to own it.

Let's do the mechanical half first, because it's the part that looks like a library swap.

Session calls: same intent, different shape

Clerk gives you auth() and currentUser() on the server, and useAuth() / useUser() on the client. Better Auth has one server call and one client hook. A codemod can rewrite the calls, but the return shapes are different, and that's the part you have to fix by hand.

Here's a typical server component before:

import { auth, currentUser } from "@clerk/nextjs/server";

export default async function Page() {
  const { userId } = await auth();
  if (!userId) redirect("/sign-in");
  const user = await currentUser();
  return <div>Hello {user.firstName}</div>;
}

The shape you're moving to is different. Better Auth's getSession returns { user, session } or null — there is no userId at the top level. A naive rewrite of the destructure would compile and be subtly wrong, so the safe approach is to leave a TODO at every rewritten call rather than guess a "plausible" shape:

import { auth } from "@/lib/auth";
import { headers } from "next/headers";

export default async function Page() {
  // TODO(better-auth): Clerk auth() returned { userId }; getSession returns
  // { user, session } | null. Destructure from session.user, not userId.
  const { userId } = await auth.api.getSession({ headers: await headers() });
  if (!userId) redirect("/sign-in");
  const user = await currentUser(); // TODO(better-auth): fold into the session above
  return <div>Hello {user.firstName}</div>;
}

The point of leaving the broken destructure next to a TODO is that it fails loudly instead of compiling into something quietly wrong. The corrected version a human writes:

import { auth } from "@/lib/auth";
import { headers } from "next/headers";

export default async function Page() {
  const session = await auth.api.getSession({ headers: await headers() });
  if (!session) redirect("/sign-in");
  return <div>Hello {session.user.name}</div>;
}

One call now covers both auth() and currentUser() — the user object is already on the session, so the separate currentUser() round-trip goes away.

The client side is the same idea. Before:

"use client";
import { useUser, useAuth } from "@clerk/nextjs";

export function Profile() {
  const { isSignedIn } = useAuth();
  const { user } = useUser();
  if (!isSignedIn) return null;
  return <span>{user.fullName}</span>;
}

After the call rewrite, with the shape fix still owed to you:

"use client";
import { authClient } from "@/lib/auth-client";

export function Profile() {
  // TODO(better-auth): useSession() returns { data, isPending, error }.
  // data is { user, session } | null. Replace isSignedIn / user accordingly.
  const { isSignedIn } = authClient.useSession();
  const { user } = authClient.useSession();
  return null;
}

authClient.useSession() returns { data, isPending, error }, and data is your { user, session } or null. The human-fixed version:

"use client";
import { authClient } from "@/lib/auth-client";

export function Profile() {
  const { data, isPending } = authClient.useSession();
  if (isPending || !data) return null;
  return <span>{data.user.name}</span>;
}

So that's the mechanical half: drop the @clerk/* imports, point them at @/lib/auth, next/headers, and @/lib/auth-client, and rewrite the call sites. A codemod can do the textual part, but it can't make the shapes match — that's on you, which is why every rewritten call is worth marking with a TODO before you move on.

The rebuild half: UI components

This is where Clerk-being-a-product hurts. Clerk ships React components that render entire flows. Better Auth ships none of that — it's headless. So every Clerk component is a TODO, not a rewrite. A codemod can remove the component imports and note what it pulled, but it cannot generate UI for you.

What you have to replace by hand:

<ClerkProvider> — delete it. Better Auth has no client-side provider to wrap your app in; the session hook works without one.
<SignedIn> / <SignedOut> — these gated children on auth state. Replace with an actual session check: read the session (server) or useSession() (client) and branch.
<UserButton> — the avatar dropdown with sign-out. You build this: an account menu and a sign-out button calling authClient.signOut().
<SignIn> / <SignUp> — the hosted forms. These become real routes and real components — an (auth) route group plus form components under src/components/auth/.
<Protect> / <RedirectToSignIn> — replace with your own session-gating and redirects.

There's no shortcut here. If you were leaning on Clerk's components, budget real time to build sign-in, sign-up, and the account menu as first-class UI. A starter that already ships these (more on that at the end) saves you most of this, but the work itself is genuine UI work either way.

Middleware

Clerk's clerkMiddleware() (formerly authMiddleware()) ran auth on the edge for you. This is a rewrite, not a rename — there's no clean textual mapping. You replace it with an edge check plus an authoritative server check.

On Next.js 16 the file is src/proxy.ts; on Next.js 15 and below it's middleware.ts. The pattern is a cheap cookie check at the edge, then a real requireSession call in the server code that actually loads protected data. The edge check keeps unauthenticated traffic out early; the server check is the one that's authoritative. Don't rely on the edge check alone for anything that matters — it only inspects the cookie, it doesn't validate the session against the database.

The auth config and the API route

Two more things a codemod can't write for you, because there's nothing in your Clerk code to translate from:

betterAuth({}) — the server config: your database adapter, which providers you enable, session options. This didn't exist under Clerk (Clerk was the config, hosted), so it's net-new.
The [...all] API route — Better Auth handles its own endpoints through a catch-all route handler. Clerk routed to its own servers, so again, net-new.

Environment variables

Don't reuse anything. Specifically:

Generate a fresh BETTER_AUTH_SECRET. Do not reuse CLERK_SECRET_KEY — it's a different key for a different system. Generate a new secret.
Delete the NEXT_PUBLIC_CLERK_* routing vars — NEXT_PUBLIC_CLERK_SIGN_IN_URL and friends. Those pointed at Clerk's hosted flows; your routes live in your app now, so they're dead config.

Cleaning up .env is on you regardless of tooling.

The part nobody warns you about: user data

Your users live in Clerk's database, not yours. Moving off Clerk means a real data migration, and this is usually the line item people forget to scope.

The shape of it:

Export users from Clerk (their API / dashboard export).
Import them into your user table so Better Auth can read them.
You cannot carry over password hashes. Clerk doesn't hand you usable password hashes, so password users have to go through a password reset on first login. OAuth users (GitHub, Google) re-onboard through the social flow — their identity is the provider, so they just sign in again.

Plan the comms for this. If you have password users, they'll all need a reset email or a "set a new password" prompt the first time they show up after the cutover. That's a product decision, not just a code one, and it's the single biggest reason a Clerk migration isn't a weekend job.

Scoping it honestly

Mechanical: imports and session calls (with the shape fixes you do by hand). Rebuild: every Clerk component, middleware, the betterAuth({}) config, the [...all] route, the .env cleanup, and the user-data export. Expect more manual work than a NextAuth migration — NextAuth is a library-to-library move; Clerk is a product-to-library move, and the product included a lot you now own.

I build Ship Kit (betterauth.app), a production-ready Better Auth starter for Next.js 16 + TypeScript. Its migration codemods are free and open source — authlayerdev/ship-kit-migrate (MIT), deterministic and non-AI (Clerk and NextAuth). Clone the repo and run the Clerk transform against your project, dry-run first:

# preview every change — writes nothing
node ./migrate/cli.mjs --transform clerk --dry ./src
# apply it
node ./migrate/cli.mjs --transform clerk ./src
# then find the manual remainder it marked for you:
grep -rn "TODO(ship-kit)" .

Being straight about what they do: they're an assist, not a one-click migrator. They delete your Clerk wiring and mark the spots that need a human — the import and session-call rewrites, plus // TODO(ship-kit): markers on the shape mismatches and on removed component imports (and they intentionally leave a wrong destructure like const { userId } = … in place so the TODO forces you to fix the session read, never a silently-compiling-but-wrong one). They do not recreate Clerk's components, middleware, or config for you, and a Clerk migration is more manual than the NextAuth one for exactly the product-vs-library reason above. The shape fixes are still yours to make.

What the kit gives you on the other side is the UI and wiring you'd otherwise hand-build: (auth) routes and components, the account menu and sign-out, two-layer route protection (edge cookie check + server requireSession), organizations/teams, and org-level Stripe billing. It's pinned to better-auth 1.6.18 with a nightly canary CI job that bumps Better Auth to latest and re-runs the test suite — that's a CI signal, not a promise that upgrades are painless. It's brand new, so there are no buyer testimonials yet; honest competitors like Makerkit (from $349) and supastarter (from EUR349) are more mature with more templates, and NEXTY (~$188) is cheaper. Ship Kit's distinct edges are the in-product migration codemods (rivals are docs-only) and crypto checkout. Solo is $179, Agency $499 — one-time (not a subscription), lifetime + free updates, crypto -5%, 14-day refund.

Disclosure: Ship Kit is my commercial product and I earn money when you buy it. It is independent and unofficial — not affiliated with or endorsed by Better Auth.

Migrating from NextAuth to Better Auth in Next.js (and What the Boring Parts Actually Are)

Ship Kit — Sun, 21 Jun 2026 22:45:55 +0000

If you've shipped a Next.js app on NextAuth (now Auth.js), you know it works. The reason people move to Better Auth usually isn't that NextAuth is bad — it's that Better Auth gives you typed, first-class access to sessions, organizations, and database-backed concepts without bolting adapters and callbacks together by hand. The session calls are typed end to end, the schema is generated for you, and features like multi-tenancy or admin tooling are first-party rather than community glue.

This post is the honest version of that migration: the mechanical parts you can rewrite almost blindly, and the parts you still have to do by hand. I'll show real before/after code for each.

Coming from Clerk instead? See the companion guide: Moving off Clerk to Better Auth.

The mental model: NextAuth is a library, so a lot of the rewrite is mechanical

Much of a NextAuth integration is call sites — getServerSession here, useSession there, a signIn button. Those follow patterns, which means they're transformable. The part that isn't mechanical is your configuration: providers, the database adapter, and callbacks. That's the logic only you understand, and no tool should silently rewrite it.

Keep that split in your head for the whole migration:

Call sites → mechanical, fast, low-risk.
Config + schema + data → manual, deliberate, where the real work lives.

Step 1: Imports

NextAuth spreads its surface across several entry points. Better Auth centralizes server access in your auth instance and client access in an authClient.

// before
import { getServerSession } from "next-auth";
import { useSession, signIn, signOut } from "next-auth/react";

// after
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
import { authClient } from "@/lib/auth-client";

The next-auth and next-auth/react imports collapse into three: your server auth instance, next/headers (you'll need it for session reads), and the authClient.

Step 2: Server-side session reads

This is the most common change in a real codebase. NextAuth's getServerSession(authOptions) becomes a call on the Better Auth instance that takes the request headers explicitly.

// before
const session = await getServerSession(authOptions);

// after
const session = await auth.api.getSession({
  headers: await headers(),
});

Passing headers() is not boilerplate you can skip — Better Auth reads the session cookie from those headers, so every server-side session read needs them.

Step 3: Client-side session reads

// before
const { data: session } = useSession();

// after
const { data: session } = authClient.useSession();

Same shape, different origin — the hook now comes off authClient instead of a top-level next-auth/react import.

Step 4: signIn / signOut (watch the arguments)

This is the first place where a find-and-replace is not enough, and it's worth slowing down. The import source changes cleanly:

// before
import { signIn, signOut } from "next-auth/react";
signIn("credentials", { email, password });
signIn("github");

// after
import { authClient } from "@/lib/auth-client";
// the call shape is different — see below

Better Auth doesn't use a single signIn(provider, options) function. Credentials and social are distinct methods with their own argument shapes:

// email + password
await authClient.signIn.email({ email, password });

// social provider
await authClient.signIn.social({ provider: "github" });

The signIn/signOut reference can be rewritten automatically, but the arguments cannot — ("credentials", { ... }) and .email({ ... }) are genuinely different APIs. Expect to revisit every sign-in call by hand.

Step 5: Environment variable renames

The names change, and there are enough of them to be error-prone. Here's the full mapping:

NextAuth	Better Auth
`NEXTAUTH_SECRET`	`BETTER_AUTH_SECRET`
`NEXTAUTH_URL`	`BETTER_AUTH_URL`
`GITHUB_ID`	`GITHUB_CLIENT_ID`
`GITHUB_SECRET`	`GITHUB_CLIENT_SECRET`
`GOOGLE_ID`	`GOOGLE_CLIENT_ID`
`GOOGLE_SECRET`	`GOOGLE_CLIENT_SECRET`

One thing to be precise about: there are two places these names live — in code (process.env.NEXTAUTH_SECRET) and in your .env file. Renaming the code references is mechanical. Renaming the actual .env entries is something you do yourself, because nothing should be reaching into your secrets file and editing it.

Step 6: The API route

NextAuth mounts its handler at [...nextauth]. Better Auth uses a catch-all [...all] route wired to its handler:

// before — app/api/auth/[...nextauth]/route.ts
import NextAuth from "next-auth";
import { authOptions } from "@/lib/auth";
const handler = NextAuth(authOptions);
export { handler as GET, handler as POST };

// after — app/api/auth/[...all]/route.ts
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { GET, POST } = toNextJsHandler(auth);

This is a file move plus a rewrite, not an in-place edit — the directory name itself changes from [...nextauth] to [...all].

Step 7: Middleware → cookie check + server `requireSession`

NextAuth's withAuth middleware has no direct equivalent in Better Auth, and that's deliberate. The recommended pattern is two layers:

A lightweight cookie check in middleware/proxy for cheap edge-level redirects.
An authoritative server-side requireSession() in the protected route or layout, which actually validates the session.

// before — middleware.ts
export { default } from "next-auth/middleware";

// after — a cookie presence check at the edge, plus:
const session = await requireSession(); // authoritative, server-side

The edge check is fast but only checks for a cookie's presence; the server check is the one you trust. Don't collapse them into one — the whole point is that the cheap check doesn't have authority and the authoritative check isn't on the hot edge path.

The config, the schema, the data — what you still do by hand

Everything above is the boring, transformable part. Here's the part that isn't — and it's the part that actually decides whether the migration goes well.

The auth config itself. Your authOptions / NextAuth({}) body doesn't translate one-to-one. You port it deliberately:

providers: [...] → socialProviders: { ... }
your adapter → the matching Better Auth adapter (e.g. drizzleAdapter)
callbacks: { ... } → databaseHooks or plugin options
email/password, verification, and reset are explicit features you enable, not implicit defaults

// the shape you're porting *to* (illustrative)
export const auth = betterAuth({
  database: drizzleAdapter(db, { /* ... */ }),
  emailAndPassword: { enabled: true },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

The database schema. NextAuth's tables are not Better Auth's tables. You generate the Better Auth schema and migrate:

pnpm auth:generate   # produce the Better Auth schema
pnpm db:migrate      # apply it

Existing user rows. This is the awkward one. Better Auth won't move your users for you — you map columns from the old tables to the new ones yourself. Password hashes only carry over if the hashing scheme matches; if it doesn't, those users need a password reset. Plan a real data-migration task here, not a script you run once and hope.

A sane order to do this in

git commit or stash first — you want a clean diff to review.
Rewrite the call sites (imports, getServerSession, useSession, sign-in references).
Port the config, generate the schema, run the migration.
Fix the sign-in/sign-out arguments by hand.
Move the API route to [...all].
Rebuild middleware as cookie-check + requireSession.
Rename .env entries.
Verify: run your typecheck, then pnpm auth:generate && pnpm db:migrate, then pnpm dev and click through the actual flows.

One thing to expect: even though the call-site rewrites are the most repetitive change, most of your time will go into the config, schema, and data — that's normal, and that's where to be careful.

Disclosure: I build a starter that automates the mechanical part

I make Ship Kit, a commercial Better Auth starter for Next.js 16 + TypeScript. (It's an independent, unofficial project — not affiliated with or endorsed by Better Auth.) I sell it, so treat this section as the ad it is.

Those migration codemods are free and open source — authlayerdev/ship-kit-migrate (MIT), deterministic and non-AI. Clone the repo and run the NextAuth transform against your project, dry-run first:

# preview every change — writes nothing
node ./migrate/cli.mjs --transform nextauth --dry ./src
# apply it (rewrites files in place)
node ./migrate/cli.mjs --transform nextauth ./src

It's idempotent (running it twice is safe), but commit or stash first regardless.

What it does: rewrites the imports, turns getServerSession(authOptions) into auth.api.getSession({ headers: await headers() }), swaps useSession() for authClient.useSession(), repoints signIn/signOut references (leaving a // TODO(ship-kit): marker because the arguments differ), renames the in-code env references, and annotates your config block with a TODO.

What it explicitly does not do — and leaves marked so you can find the remainder with one grep — is the genuinely manual work:

grep -rn "TODO(ship-kit)" .   # the manual checklist the codemod left you

…that remainder being: porting the config body, the sign-in argument shapes, the DB schema, the user-row migration, the API route move, the .env file itself, and middleware. In other words, exactly the "by hand" section above. It's an assist for the mechanical part, not a one-click migrator — the parts that need judgment stay yours.

For full context: Ship Kit is one-time ($179 solo / $499 agency, lifetime updates, 14-day refund, crypto −5%), built by one developer in Berlin. It's brand new, so there are no buyer testimonials yet. More established starters like Makerkit (from $349) and supastarter (from €349) have more templates and maturity; Ship Kit's narrower distinctions are the in-product migration codemods (most rivals are docs-only) and crypto checkout. It also runs a nightly canary CI job that bumps Better Auth to the latest version and re-runs the test suite — that's a signal it tracks upstream, not a guarantee that any given upgrade will be painless.

If you'd rather not hand-write the repetitive call-site rewrites, the codemod handles that part. The config, schema, and data migration are still yours to do.

Disclosure: I'm the author of Ship Kit, a commercial product mentioned above, and I earn revenue from its sales.