Migrate from Better Auth

Move Better Auth server and client sign-in calls onto the MainSDK auth interface, keeping your users until you choose to move them.

Planned for 0.7

Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.

Stability The promise an interface ships with.

Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
Beta Usable in production; may change before it becomes stable.
Experimental May change or go away; needs an explicit opt-in in main.yaml.

Stability levels

View as Markdown Open in Claude Edit

Updated 2026-10-28

Move Better Auth server and client sign-in calls onto the MainSDK auth interface, keeping your users until you choose to move them. Your Better Auth account stays; nothing here deletes it.

Before you start:

A git repository with a clean working tree. mainsdk migrate works on a branch and never touches yours.
Node 22 and npx mainsdk. No main.yaml yet? migrate writes one; or start with Adopt an existing app.
Your Better Auth keys stay where they are. Move them to secret: references when the driver is chosen (see Secrets).

1. Read the report

text

npx mainsdk migrate better-auth --report-only

The report writes no file. It sorts every Better Auth call in your code into three lists: mapped (an interface call replaces it), raw (it stays behind raw(), with the reason) and needs a person (a policy, a rule file or a call with no interface). Add --json for a machine-readable report.

For the sample app of this guide (packages/cli/test/fixtures/migrate/better-auth), the report finds 2 mapped, 0 raw and 1 for a person.

2. What the codemod changes

Where	Before	After
`app/api/me/route.ts:4`	`const session = await auth.api.getSession({ headers: req.headers })`	`auth.require(req)`
`lib/client.ts:6`	`authClient.signIn.email({ email, password })`	`auth.signIn()`

Each rewrite is mechanical and one line at a time. Imports of Better Auth go when no call needs them, and mainsdk is added to package.json.

3. What stays behind raw()

Nothing in the sample stays behind raw().

A call behind raw() keeps working through the Better Auth host on your network allow list, and mainsdk check still sees it. Each one has a marker comment, // mainsdk migrate: ..., so you can find it later.

4. What needs a person

lib/auth.ts:3: no interface call for betterAuth(; a person decides

The codemod leaves these lines alone and marks them. No tool should guess a policy.

5. Stateful moves are guided jobs

Data does not move with the code. Each stateful move is a job with steps and a rollback, listed in the pull request and never run by the codemod.

users: Keep Better Auth as the auth driver; move nothing

Set auth.driver: better-auth in main.yaml; it reads the same tables.
Replace calls one module at a time and run mainsdk check after each.

Rollback: Revert the pull request; no data moved.

6. Open the pull request

text

npx mainsdk migrate better-auth

This records your sign-in and checkout flows as locked flows first, then creates the branch migrate/better-auth, applies the codemods, adds .github/workflows/mainsdk-migrate.yml, runs mainsdk check and the locked flows, commits, pushes and opens one pull request with gh. If a gate fails, the branch is kept and no pull request opens (MAIN-MIGRATE-0001). --no-pr stops after the commit.

Locked flows run again in CI: npx mainsdk migrate flows.

Where you end

You end at the reference architecture mainsdk/saas-web: the same shape, with its tests, benchmark and chaos drills.

text

npx mainsdk init --template mainsdk/saas-web

Was this page helpful?