Skip to main content
skill CX Codex

better-auth · pproenca — Claude Code skill: what it does, how to install

A TypeScript skill for Better Auth: instance setup, adapter choice, sessions and cookies, plugins, plus migration from another auth library.

MIT 150 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill better-auth -a claude-code
Open on GitHub

What better-auth does

The skill covers Better Auth, a TypeScript auth library that works across frameworks. It holds 42 rules in 8 categories, ordered by impact: instance setup and database adapters come first, then route handlers, sessions, sign-in methods, hardening, plugins and migration. The rules are drawn from the official docs and migration guides.

It fires while you write or review Better Auth code, and also when the library goes unnamed but the work touches TypeScript auth, session cookies, OAuth providers or an auth-library swap. Framework coverage runs from Next.js App and Pages Router through SvelteKit, Hono, Express, Nuxt and Astro, with client notes for React, Vue and Svelte. Several rules go after the usual breakage: a null session on the server, a redirect_uri_mismatch from the provider console, a 403 CSRF error.

Order matters here. In Next.js nextCookies() goes last among the plugins, and auth generate plus the ORM migration belong before a deploy. BETTER_AUTH_SECRET and baseURL are set per environment, and trustedOrigins never gets a wildcard.

What it helps with

  • Stand up a Better Auth instance with the adapter for your ORM
  • Trace a redirect_uri_mismatch on an OAuth callback
  • Move an app off NextAuth, Clerk, Auth0 or Supabase Auth
  • Wire 2FA, organizations or magic links through plugins
  • Find out why getSession returns null on the server

Example prompts for the agent

  • Set up Better Auth in a Nuxt app with the Drizzle adapter and a catch-all route under /api/auth/[...all].
  • We are moving from Clerk — port the sign-in flow to Better Auth and keep existing users.
  • Add the two-factor plugin and make sure nextCookies() is the last one in the list.

How to install better-auth

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill better-auth -a claude-code

2Manually: put the files in place

~/.claude/skills/better-auth/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/better-auth/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about better-auth

How do I install better-auth in Claude Code?

Run npx skills add pproenca/dot-skills --skill better-auth -a claude-code, then the skill file sits at ~/.claude/skills/better-auth/SKILL.md.

What does the better-auth skill do?

It gives the agent 42 rules on Better Auth in TypeScript across 8 categories: setup, DB adapters, route handlers, sessions and cookies, sign-in methods, security, plugins and migration. The agent applies them while writing or reviewing auth code.

Which frameworks and clients are covered?

Next.js (App and Pages Router), SvelteKit, Hono, Express, Nuxt, Astro, plus React, Vue and Svelte clients. There are rules for the 2FA, organization, admin, magicLink, JWT and passkey plugins.

Source text

SKILL.md · MIT
---
name: better-auth
description: Better Auth in TypeScript — setting up the auth instance, picking adapters, wiring framework route handlers, configuring sessions and cookies, adding plugins (2FA, organization, admin, magicLink, JWT), or porting from NextAuth/Auth.js, Clerk, Auth0, or Supabase Auth. Covers Next.js, SvelteKit, Hono, Express, Nuxt, Astro, and React/Vue/Svelte clients. Trigger when writing, reviewing, or migrating Better Auth code — and even when the user doesn't explicitly mention Better Auth but is working on TypeScript authentication, session cookies, OAuth providers, or auth-library migration. Contains 42 rules organized by impact across 8 categories.
---
# Better Auth Best Practices

Implementation and migration guide for [Better Auth](https://www.better-auth.com), the framework-agnostic TypeScript authentication and authorization library. This skill contains 42 rules organized by impact across 8 categories, derived from the official documentation and migration guides.

## When to Apply

Reference these guidelines when:

- Setting up a fresh Better Auth instance (config, adapter, route handler, client)
- Wiring framework-specific integrations (Next.js App/Pages Router, SvelteKit, Hono, Express, Nuxt, Astro)
- Configuring sessions, cookies, and security (rate limit, trusted origins, password hashing)
- Adding plugins: 2FA, organization, admin, magicLink, JWT, passkey, multi-session
- Migrating from another auth library (NextAuth/Auth.js, Clerk, Auth0, Supabase Auth)
- Debugging "session is null" / "redirect_uri_mismatch" / 403 CSRF errors
- Reviewing PRs that touch `lib/auth.ts`, `auth-client.ts`, or `/api/auth/` route handlers

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Setup & Configuration | CRITICAL | `setup-` |
| 2 | Database Adapters & Schema | CRITICAL | `db-` |
| 3 | API Route Handlers | CRITICAL | `route-` |
| 4 | Session & Cookies | HIGH | `session-` |
| 5 | Auth Methods & Providers | HIGH | `auth-` |
| 6 | Security & Hardening | HIGH | `security-` |
| 7 | Plugins & Extensions | MEDIUM | `plugins-` |
| 8 | Migration from Other Auth | MEDIUM | `migrate-` |

## Quick Reference

### 1. Setup & Configuration (CRITICAL)

- [`setup-secret`](references/setup-secret.md) — Set a strong `BETTER_AUTH_SECRET` per environment
- [`setup-base-url`](references/setup-base-url.md) — Configure an explicit `baseURL` per environment
- [`setup-client-base-url`](references/setup-client-base-url.md) — Match the client `baseURL` to the server
- [`setup-singleton`](references/setup-singleton.md) — Export a single auth instance from a server-only module
- [`setup-trusted-origins`](references/setup-trusted-origins.md) — Configure `trustedOrigins` for all non-baseURL callers

### 2. Database Adapters & Schema (CRITICAL)

- [`db-adapter-selection`](references/db-adapter-selection.md) — Pick the adapter that matches your ORM
- [`db-schema-generate`](references/db-schema-generate.md) — Run `auth generate` then ORM migrate before every deploy
- [`db-additional-fields`](references/db-additional-fields.md) — Extend the user schema via `additionalFields`
- [`db-plugin-schema-customization`](references/db-plugin-schema-customization.md) — Rename plugin tables via the `schema` option
- [`db-database-hooks`](references/db-database-hooks.md) — Use `databaseHooks` for cross-cutting logic
- [`db-connection-pooling`](references/db-connection-pooling.md) — Share one pooled DB client with the rest of your app

### 3. API Route Handlers (CRITICAL)

- [`route-mount-catchall`](references/route-mount-catchall.md) — Mount the catch-all handler at `/api/auth/[...all]`
- [`route-runtime-selection`](references/route-runtime-selection.md) — Use the Node.js runtime for middleware that calls `auth.api`
- [`route-no-body-consumers`](references/route-no-body-consumers.md) — Mount auth before any body-parsing middleware

### 4. Session & Cookies (HIGH)

- [`session-server-vs-client`](references/session-server-vs-client.md) — Use `auth.api.getSession` on server, `authClient.useSession` on client
- [`session-expiry-tuning`](references/session-expiry-tuning.md) — Configure `expiresIn` and `updateAge` together
- [`session-cookie-cache`](references/session-cookie-cache.md) — Enable `cookieCache` to cut session DB lookups
- [`session-cookie-attributes`](references/session-cookie-attributes.md) — Set `sameSite`, `secure`, `partitioned` for cross-site flows
- [`session-cross-subdomain`](references/session-cross-subdomain.md) — Enable `crossSubDomainCookies` for multi-subdomain apps
- [`session-customsession-fields`](references/session-customsession-fields.md) — Use `customSession` to add computed fields

### 5. Auth Methods & Providers (HIGH)

- [`auth-require-email-verification`](references/auth-require-email-verification.md) — Enable `requireEmailVerification` with `sendVerificationEmail`
- [`auth-oauth-redirect-uri`](references/auth-oauth-redirect-uri.md) — Match OAuth `redirectURI` exactly with the provider console
- [`auth-oauth-env-vars`](references/auth-oauth-env-vars.md) — Load OAuth credentials from environment, never inline
- [`auth-magic-link-setup`](references/auth-magic-link-setup.md) — Implement `sendMagicLink` before enabling the `magicLink` plugin
- [`auth-client-sign-in-helpers`](references/auth-client-sign-in-helpers.md) — Use `authClient.signIn.social` with `callbackURL`
- [`auth-infer-additional-fields`](references/auth-infer-additional-fields.md) — Add `inferAdditionalFields` to the client for type sync

### 6. Security & Hardening (HIGH)

- [`security-rate-limit`](references/security-rate-limit.md) — Enable `rateLimit` with persistent storage in production
- [`security-password-hash-interop`](references/security-password-hash-interop.md) — Override hash function when migrating from bcrypt/argon2
- [`security-revoke-on-password-reset`](references/security-revoke-on-password-reset.md) — Enable `revokeSessionsOnPasswordReset`
- [`security-min-password-length`](references/security-min-password-length.md) — Set `minPasswordLength` to at least 10
- [`security-trusted-origins-strict`](references/security-trusted-origins-strict.md) — Never wildcard `trustedOrigins`

### 7. Plugins & Extensions (MEDIUM)

- [`plugins-next-cookies-last`](references/plugins-next-cookies-last.md) — Place `nextCookies()` as the LAST plugin in Next.js
- [`plugins-two-factor-issuer`](references/plugins-two-factor-issuer.md) — Set `appName` as the 2FA issuer
- [`plugins-shared-access-control`](references/plugins-shared-access-control.md) — Define `ac` + roles once, share server/client
- [`plugins-pair-client-server`](references/plugins-pair-client-server.md) — Pair every server plugin with its client counterpart
- [`plugins-organization-active-context`](references/plugins-organization-active-context.md) — Set active organization on session
- [`plugins-jwt-when-to-use`](references/plugins-jwt-when-to-use.md) — Use the `jwt` plugin only for external service consumers
- [`plugins-admin-impersonation`](references/plugins-admin-impersonation.md) — Use admin plugin's `impersonate` method for support access

### 8. Migration from Other Auth (MEDIUM)

- [`migrate-parallel-cutover`](references/migrate-parallel-cutover.md) — Run Better Auth alongside legacy auth during cutover
- [`migrate-oauth-account-mapping`](references/migrate-oauth-account-mapping.md) — Map legacy OAuth identities to `account` rows
- [`migrate-force-allow-id`](references/migrate-force-allow-id.md) — Use `forceAllowId` to preserve existing user IDs
- [`migrate-nextauth-schema-mapping`](references/migrate-nextauth-schema-mapping.md) — Map NextAuth v5 columns field-by-field

## How to Use

For a fresh implementation, read in priority order: start with all `setup-` rules, then `db-`, then `route-` — these CRITICAL categories must be correct or nothing else works. After the foundation, pick the rules that match your scope: `session-` for cookie/expiry tuning, `auth-` for provider configuration, `security-` for production hardening.

For a migration from another auth library, read `migrate-parallel-cutover` first (strategy), then `security-password-hash-interop` (preserve user passwords), then `migrate-oauth-account-mapping` and `migrate-nextauth-schema-mapping` (data layout).

Read individual reference files for detailed explanations, incorrect vs. correct code examples, and links to the canonical Better Auth documentation.

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions ordered by impact |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for adding new rules |
| [metadata.json](metadata.json) | Version, references, and discipline metadata |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Backend and APIs →

better-auth by other authors comes first.

better-auth mrgoonie Walks your agent through Better Auth: email/password, OAuth, 2FA, passkeys and roles. Useful when a project needs sign-in and sessions. CX Codex +1 402installs better-auth giuseppe-trisciuoglio A skill with ready-made Better Auth patterns: NestJS backend, Drizzle ORM and PostgreSQL, social login, plus plugins like 2FA and passkey. CX Codex +1 3,800installs better-auth secondsky better-auth is a Claude Code skill for adding authentication and diagnosing Cloudflare D1 adapter errors. It also covers OAuth, two-factor authentication, and role-based access. CX Codex +1 511installs better-auth oakoss Hands the agent a reference for better-auth: config, plugins, session strategies and the usual mistakes. Useful when a project needs login, 2FA or multi-tenant organizations. CX Codex +1 114installs better-auth-security-best-practices better-auth better-auth-security-best-practices hardens Better Auth deployments by configuring rate limits, CSRF rules, session caching, and OAuth token encryption. CX Codex +1 52,200installs neon-auth neondatabase neon-auth is a Claude Code skill that sets up authentication with Neon Auth in a new app. It handles requests for login, sign-up, password resets, and OAuth. CX Codex +1 38,600installs better-auth-core bobmatnyc better-auth-core — a skill for wiring Better Auth into TypeScript apps: the instance, server handlers, client, and sessions. Useful when you need auth running without digging through docs. CX Codex +1 376installs better-auth-integrations bobmatnyc better-auth-integrations configures Better Auth route handlers in TypeScript web frameworks like Next.js, Remix, Hono, and Express. Solves cookie and header forwarding for SSR and server actions. CX Codex +1 371installs nuxt-better-auth onmax nuxt-better-auth guides Nuxt authentication with @nuxtjs/better-auth, including route guards, session handling, and Better Auth plugins. CX Codex +1 2,100installs safe-action-better-auth next-safe-action safe-action-better-auth is a Claude Code skill for adding Better Auth authentication and authorization to safe actions. It covers session middleware, access checks, and unauthenticated requests. CX Codex +1 499installs

From the same set139

The whole set →
expo-design-system expo-design-system is a Claude Code skill for building and reviewing shared UI in Expo and React Native apps for web and iOS. It applies to tokens, themes, and reusable components. CX Codex +1 156installs complexity-optimizer complexity-optimizer detects algorithmic complexity bottlenecks in codebases and suggests safe runtime optimizations. CX Codex +1 156installs nextjs-bundle-optimizer nextjs-bundle-optimizer measures Next.js bundle size and build time, then checks optimizations one change at a time. Useful when First Load JS grows or production builds slow down. CX Codex +1 152installs implementation-design-patterns implementation-design-patterns is a Claude Code skill that identifies a Gang of Four pattern from a problem description and explains when to apply or avoid it. CX Codex +1 151installs diataxis diataxis sorts technical docs into four modes: tutorial, how-to, reference, explanation. Tells the agent which one a page needs before it starts writing. CX Codex +1 149installs drizzle-sqlite-scaffold drizzle-sqlite-scaffold generates boilerplate for Drizzle ORM + SQLite: config, client with pragmas, table schemas, CRUD modules and validators. Triggers on phrases like “add a table for X” or “set up the DB”. CX Codex +1 149installs same-results-less-code The same-results-less-code skill helps spot conceptual complexity during code review and refactoring while preserving behavior. It looks beyond the mechanical issues linters catch. CX Codex +1 148installs codebase-comprehension-algorithms codebase-comprehension-algorithms maps an unfamiliar repository into feature domains: which files back a feature, where the architecture actually sits. CX Codex +1 148installs

More in the catalog

Project sponsors

Companies that keep this analytics open