Add TypeScript authentication with ak:better-auth

Use ak:better-auth to add or refine authentication in a TypeScript or JavaScript application. The Skill covers Better Auth server and client setup, email/password flows, social OAuth, sessions, database adapters, and optional plugins such as two-factor authentication, passkeys, magic links, usernames, and organizations.

Choose ak:better-auth for a Better Auth integration

Use ak:better-auth when

• The project uses TypeScript or JavaScript and has selected Better Auth.
• You need an email/password, OAuth, session, account-linking, MFA, passkey, magic-link, username, or organization flow.
• You need to connect authentication to an existing database and framework handler.
• You want a scoped implementation plus migration and flow-verification evidence.

Choose another workflow when

• You are still comparing authentication products or defining the threat model. Use ak:brainstorm or ak:advise before selecting an implementation.
• The task is general backend work without a Better Auth decision. Use ak:backend-development.
• You only need an independent security review. Use ak:security or ak:code-review against the existing implementation.
• The application is not compatible with the installed Better Auth package or its adapters. Preserve the current authentication stack unless a migration is separately approved.

Prepare the application and credentials

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Identify the framework, runtime, package manager, Better Auth version, database, ORM, route layout, cookie policy, and existing user schema from the project.
• Define supported sign-in methods, session lifetime, account-linking rules, email verification, password reset, recovery, roles, and deletion behavior.
• Use development credentials and an isolated database. Keep BETTER_AUTH_SECRET, database URLs, OAuth client secrets, email-provider credentials, and production tokens out of prompts, logs, code, and Git.
• Record whether package installation, schema generation, migration execution, email delivery, provider-console changes, or deployment is authorized.

The bundled examples cover Next.js, Nuxt, SvelteKit, Astro, Hono, and Express, plus direct SQLite, PostgreSQL, MySQL, MongoDB, Drizzle, Prisma, and Kysely connections. Treat them as patterns, not proof that the current package version or project exposes the same API.

See Runtime adapters for component-level differences.

Run the Skill

The declared argument shape is [auth-method or feature]. Name the existing stack, user-visible flow, security boundary, migration authority, and required evidence in the request.

/ak:better-auth "Add GitHub OAuth to the existing Next.js app and Better Auth database. Preserve email/password login, request only identity scopes, add callback and account-linking tests, generate but do not apply migrations, and do not use production credentials or deploy."

/ak:better-auth "Add GitHub OAuth to the existing Next.js app and Better Auth database. Preserve email/password login, request only identity scopes, add callback and account-linking tests, generate but do not apply migrations, and do not use production credentials or deploy."

$ak:better-auth "Add GitHub OAuth to the existing Next.js app and Better Auth database. Preserve email/password login, request only identity scopes, add callback and account-linking tests, generate but do not apply migrations, and do not use production credentials or deploy."

Useful input distinguishes configuration from external actions:

Observe the integration stages

You should be able to inspect these stages:

1. The run maps the current authentication surface. It finds the real framework handler, server and client configuration, schema, session use, protected routes, environment contract, and existing tests.
2. The run confirms the flow and threat boundaries. It defines redirects, account linking, verification, recovery, session revocation, authorization, and abuse handling before editing code.
3. The run selects compatible Better Auth APIs. Built-in methods and plugins are checked against the installed version; adding a plugin also triggers a schema-impact review.
4. The run implements the smallest approved slice. Server configuration, route handler, client calls, UI states, and error behavior stay tied to the existing project patterns.
5. The run prepares database changes safely. Generated schema or migrations are reviewed as artifacts. Applying them to any database is a separate mutation boundary.
6. The run verifies and reports. It records focused tests, typecheck or build results, flow coverage, changed files, schema impact, and unperformed provider or deployment steps.

Keep secrets, migrations, and live flows under approval

• Installing packages can run lifecycle scripts and modify a lockfile.
• npx @better-auth/cli generate creates schema artifacts; migration commands can alter tables and data. Review generated output before applying it.
• Provider dashboard work can create credentials and change redirect URLs. Grant that authority separately and request only necessary scopes.
• The optional bundled initializer is an interactive example. It can write an auth.ts file, print generated environment content to the terminal, and replace an existing .env after renaming it to .env.backup. Inspect the diff and protect existing secret files before using it.
• Email, SMS, OAuth, passkey, and external rate-limit tests can contact live services or real users. Prefer fakes, local mail capture, and test tenants.
• Commit, push, publication, and deployment remain separate approvals.

Verify the result

A complete result should provide:

• The implemented flow matrix, including success, invalid input, expired token, unverified account, duplicate account, and signed-out behavior where relevant.
• Exact changed files, packages, environment-variable names, generated schema, and unapplied migration artifacts without revealing values.
• Focused server, client, callback, session, authorization, and rate-limit test commands with results.
• Evidence that redirects are constrained, secrets stay server-side, cookies and session behavior match policy, and OAuth scopes are minimal.
• A production checklist for provider URLs, secret injection, email delivery, database backup/migration, monitoring, rollback, and deployment approval.

Troubleshoot or continue

Continue with ak:databases for a separately scoped schema review, ak:security for a security audit, or the Engineer Kit overview for a coordinated implementation.

Know the current limits

• The Skill is guidance and implementation context, not an identity provider, secrets manager, email/SMS service, database backup system, or penetration test.
• Better Auth and provider APIs evolve. Confirm current package documentation, adapter support, plugin requirements, callback formats, and security notices before relying on a bundled example.
• The source does not prove compatibility with every framework version, deployment host, proxy, browser, passkey device, mail provider, or database topology.
• Its bundled tests exercise the initializer, not your application’s complete authentication, authorization, recovery, migration, or production rollout.
• Stable and beta contain identical Skill content and resources for this release pair. Beta Codex Hook diagnostics do not change this workflow.