akghosh111/create-auth-skill

Create Auth Skill

Guide for adding authentication to TypeScript/JavaScript applications using Better Auth.

For code examples and syntax, see better-auth.com/docs.

---

Decision Tree

Is this a new/empty project?
├─ YES → New project setup
│   1. Identify framework
│   2. Choose database
│   3. Install better-auth
│   4. Create auth.ts + auth-client.ts
│   5. Set up route handler
│   6. Run CLI migrate/generate
│   7. Add features via plugins
│
└─ NO → Does project have existing auth?
    ├─ YES → Migration/enhancement
    │   • Audit current auth for gaps
    │   • Plan incremental migration
    │   • See migration guides in docs
    │
    └─ NO → Add auth to existing project
        1. Analyze project structure
        2. Install better-auth
        3. Create auth config
        4. Add route handler
        5. Run schema migrations
        6. Integrate into existing pages

---

Installation

Core: npm install better-auth

Scoped packages (as needed): | Package | Use case | |---------|----------| | @better-auth/passkey | WebAuthn/Passkey auth | | @better-auth/sso | SAML/OIDC enterprise SSO | | @better-auth/stripe | Stripe payments | | @better-auth/scim | SCIM user provisioning | | @better-auth/expo | React Native/Expo |

---

Environment Variables

BETTER_AUTH_SECRET=<32+ chars, generate with: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<your database connection string>

Add OAuth secrets as needed: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, etc.

---

Server Config (auth.ts)

Location: lib/auth.ts or src/lib/auth.ts

Minimal config needs:

• database - Connection or adapter
• emailAndPassword: { enabled: true } - For email/password auth

Standard config adds:

• socialProviders - OAuth providers (google, github, etc.)
• emailVerification.sendVerificationEmail - Email verification handler
• emailAndPassword.sendResetPassword - Password reset handler

Full config adds:

• plugins - Array of feature plugins
• session - Expiry, cookie cache settings
• account.accountLinking - Multi-provider linking
• rateLimit - Rate limiting config

Export types: export type Session = typeof auth.$Infer.Session

---

Client Config (auth-client.ts)

Import by framework: | Framework | Import | |-----------|--------| | React/Next.js | better-auth/react | | Vue | better-auth/vue | | Svelte | better-auth/svelte | | Solid | better-auth/solid | | Vanilla JS | better-auth/client |

Client plugins go in createAuthClient({ plugins: [...] }).

Common exports: signIn, signUp, signOut, useSession, getSession

---

Route Handler Setup

| Framework | File | Handler | |-----------|------|---------| | Next.js App Router | app/api/auth/[...all]/route.ts | toNextJsHandler(auth) → export { GET, POST } | | Next.js Pages | pages/api/auth/[...all].ts | toNextJsHandler(auth) → default export | | Express | Any file | app.all("/api/auth/*", toNodeHandler(auth)) | | SvelteKit | src/hooks.server.ts | svelteKitHandler(auth) | | SolidStart | Route file | solidStartHandler(auth) | | Hono | Route file | auth.handler(c.req.raw) |

Next.js Server Components: Add nextCookies() plugin to auth config.

---

Database Migrations

| Adapter | Command | |---------|---------| | Built-in Kysely | npx @better-auth/cli@latest migrate (applies directly) | | Prisma | npx @better-auth/cli@latest generate --output prisma/schema.prisma then npx prisma migrate dev | | Drizzle | npx @better-auth/cli@latest generate --output src/db/auth-schema.ts then npx drizzle-kit push |

Re-run after adding plugins.

---

Database Adapters

| Database | Setup | |----------|-------| | SQLite | Pass better-sqlite3 or bun:sqlite instance directly | | PostgreSQL | Pass pg.Pool instance directly | | MySQL | Pass mysql2 pool directly | | Prisma | prismaAdapter(prisma, { provider: "postgresql" }) from better-auth/adapters/prisma | | Drizzle | drizzleAdapter(db, { provider: "pg" }) from better-auth/adapters/drizzle | | MongoDB | mongodbAdapter(db) from better-auth/adapters/mongodb |

---

Common Plugins

| Plugin | Server Import | Client Import | Purpose | |--------|---------------|---------------|---------| | twoFactor | better-auth/plugins | twoFactorClient | 2FA with TOTP/OTP | | organization | better-auth/plugins | organizationClient | Teams/orgs | | admin | better-auth/plugins | adminClient | User management | | bearer | better-auth/plugins | - | API token auth | | openAPI | better-auth/plugins | - | API docs | | passkey | @better-auth/passkey | passkeyClient | WebAuthn | | sso | @better-auth/sso | - | Enterprise SSO |

Plugin pattern: Server plugin + client plugin + run migrations.

---

Auth UI Implementation

Sign in flow:

1. signIn.email({ email, password }) or signIn.social({ provider, callbackURL })
2. Handle error in response
3. Redirect on success

Session check (client): useSession() hook returns { data: session, isPending }

Session check (server): auth.api.getSession({ headers: await headers() })

Protected routes: Check session, redirect to /sign-in if null.

---

Security Checklist

• [ ] BETTER_AUTH_SECRET set (32+ chars)
• [ ] advanced.useSecureCookies: true in production
• [ ] trustedOrigins configured
• [ ] Rate limits enabled
• [ ] Email verification enabled
• [ ] Password reset implemented
• [ ] 2FA for sensitive apps
• [ ] CSRF protection NOT disabled
• [ ] account.accountLinking reviewed

---

Troubleshooting

| Issue | Fix | |-------|-----| | "Secret not set" | Add BETTER_AUTH_SECRET env var | | "Invalid Origin" | Add domain to trustedOrigins | | Cookies not setting | Check baseURL matches domain; enable secure cookies in prod | | OAuth callback errors | Verify redirect URIs in provider dashboard | | Type errors after adding plugin | Re-run CLI generate/migrate |

---

Resources

• Docs
• Examples
• Plugins
• CLI
• Migration Guides