Create Auth Skill

1---
2name: create-auth-skill
3description: Skill for creating auth layers in TypeScript/JavaScript apps using Better Auth.
4---
5 
6# Create Auth Skill
7 
8Guide for adding authentication to TypeScript/JavaScript applications using Better Auth.
9 
10**For code examples and syntax, see [better-auth.com/docs](https://better-auth.com/docs).**
11 
12---
13 
14## Phase 1: Planning (REQUIRED before implementation)
15 
16Before writing any code, gather requirements by scanning the project and asking the user structured questions. This ensures the implementation matches their needs.
17 
18### Step 1: Scan the project
19 
20Analyze the codebase to auto-detect:
21- **Framework** — Look for `next.config`, `svelte.config`, `nuxt.config`, `astro.config`, `vite.config`, or Express/Hono entry files.
22- **Database/ORM** — Look for `prisma/schema.prisma`, `drizzle.config`, `package.json` deps (`pg`, `mysql2`, `better-sqlite3`, `mongoose`, `mongodb`).
23- **Existing auth** — Look for existing auth libraries (`next-auth`, `lucia`, `clerk`, `supabase/auth`, `firebase/auth`) in `package.json` or imports.
24- **Package manager** — Check for `pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, or `package-lock.json`.
25 
26Use what you find to pre-fill defaults and skip questions you can already answer.
27 
28### Step 2: Ask planning questions
29 
30Use the `AskQuestion` tool to ask the user **all applicable questions in a single call**. Skip any question you already have a confident answer for from the scan. Group them under a title like "Auth Setup Planning".
31 
32**Questions to ask:**
33 
341. **Project type** (skip if detected)
35   - Prompt: "What type of project is this?"
36   - Options: New project from scratch | Adding auth to existing project | Migrating from another auth library
37 
382. **Framework** (skip if detected)
39   - Prompt: "Which framework are you using?"
40   - Options: Next.js (App Router) | Next.js (Pages Router) | SvelteKit | Nuxt | Astro | Express | Hono | SolidStart | Other
41 
423. **Database & ORM** (skip if detected)
43   - Prompt: "Which database setup will you use?"
44   - Options: PostgreSQL (Prisma) | PostgreSQL (Drizzle) | PostgreSQL (pg driver) | MySQL (Prisma) | MySQL (Drizzle) | MySQL (mysql2 driver) | SQLite (Prisma) | SQLite (Drizzle) | SQLite (better-sqlite3 driver) | MongoDB (Mongoose) | MongoDB (native driver)
45 
464. **Authentication methods** (always ask, allow multiple)
47   - Prompt: "Which sign-in methods do you need?"
48   - Options: Email & password | Social OAuth (Google, GitHub, etc.) | Magic link (passwordless email) | Passkey (WebAuthn) | Phone number
49   - `allow_multiple: true`
50 
515. **Social providers** (only if they selected Social OAuth above — ask in a follow-up call)
52   - Prompt: "Which social providers do you need?"
53   - Options: Google | GitHub | Apple | Microsoft | Discord | Twitter/X
54   - `allow_multiple: true`
55 
566. **Email verification** (only if Email & password was selected above — ask in a follow-up call)
57   - Prompt: "Do you want to require email verification?"
58   - Options: Yes | No
59 
607. **Email provider** (only if email verification is Yes, or if Password reset is selected in features — ask in a follow-up call)
61   - Prompt: "How do you want to send emails?"
62   - Options: Resend | Mock it for now (console.log)
63 
648. **Features & plugins** (always ask, allow multiple)
65   - Prompt: "Which additional features do you need?"
66   - Options: Two-factor authentication (2FA) | Organizations / teams | Admin dashboard | API bearer tokens | Password reset | None of these
67   - `allow_multiple: true`
68 
699. **Auth pages** (always ask, allow multiple — pre-select based on earlier answers)
70   - Prompt: "Which auth pages do you need?"
71   - Options vary based on previous answers:
72     - Always available: Sign in | Sign up
73     - If Email & password selected: Forgot password | Reset password
74     - If email verification enabled: Email verification
75   - `allow_multiple: true`
76 
7710. **Auth UI style** (always ask)
78   - Prompt: "What style do you want for the auth pages? Pick one or describe your own."
79   - Options: Minimal & clean | Centered card with background | Split layout (form + hero image) | Floating / glassmorphism | Other (I'll describe)
80 
81### Step 3: Summarize the plan
82 
83After collecting answers, present a concise implementation plan as a markdown checklist. Example:
84 
85```
86## Auth Implementation Plan
87 
88- **Framework:** Next.js (App Router)
89- **Database:** PostgreSQL via Prisma
90- **Auth methods:** Email/password, Google OAuth, GitHub OAuth
91- **Plugins:** 2FA, Organizations, Email verification
92- **UI:** Custom forms
93 
94### Steps
951. Install `better-auth` and `@better-auth/cli`
962. Create `lib/auth.ts` with server config
973. Create `lib/auth-client.ts` with React client
984. Set up route handler at `app/api/auth/[...all]/route.ts`
995. Configure Prisma adapter and generate schema
1006. Add Google & GitHub OAuth providers
1017. Enable `twoFactor` and `organization` plugins
1028. Set up email verification handler
1039. Run migrations
10410. Create sign-in / sign-up pages
105```
106 
107Ask the user to confirm the plan before proceeding to Phase 2.
108 
109---
110 
111## Phase 2: Implementation
112 
113Only proceed here after the user confirms the plan from Phase 1.
114 
115Follow the decision tree below, guided by the answers collected above.
116 
117```
118Is this a new/empty project?
119├─ YES → New project setup
120│   1. Install better-auth (+ scoped packages per plan)
121│   2. Create auth.ts with all planned config
122│   3. Create auth-client.ts with framework client
123│   4. Set up route handler
124│   5. Set up environment variables
125│   6. Run CLI migrate/generate
126│   7. Add plugins from plan
127│   8. Create auth UI pages
128│
129├─ MIGRATING → Migration from existing auth
130│   1. Audit current auth for gaps
131│   2. Plan incremental migration
132│   3. Install better-auth alongside existing auth
133│   4. Migrate routes, then session logic, then UI
134│   5. Remove old auth library
135│   6. See migration guides in docs
136│
137└─ ADDING → Add auth to existing project
138    1. Analyze project structure
139    2. Install better-auth
140    3. Create auth config matching plan
141    4. Add route handler
142    5. Run schema migrations
143    6. Integrate into existing pages
144    7. Add planned plugins and features
145```
146 
147At the end of implementation, guide users thoroughly on remaining next steps (e.g., setting up OAuth app credentials, deploying env vars, testing flows).
148 
149---
150 
151## Installation
152 
153**Core:** `npm install better-auth`
154 
155**Scoped packages (as needed):**
156| Package | Use case |
157|---------|----------|
158| `@better-auth/passkey` | WebAuthn/Passkey auth |
159| `@better-auth/sso` | SAML/OIDC enterprise SSO |
160| `@better-auth/stripe` | Stripe payments |
161| `@better-auth/scim` | SCIM user provisioning |
162| `@better-auth/expo` | React Native/Expo |
163 
164---
165 
166## Environment Variables
167 
168```env
169BETTER_AUTH_SECRET=<32+ chars, generate with: openssl rand -base64 32>
170BETTER_AUTH_URL=http://localhost:3000
171DATABASE_URL=<your database connection string>
172```
173 
174Add OAuth secrets as needed: `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, `GOOGLE_CLIENT_ID`, etc.
175 
176---
177 
178## Server Config (auth.ts)
179 
180**Location:** `lib/auth.ts` or `src/lib/auth.ts`
181 
182**Minimal config needs:**
183- `database` - Connection or adapter
184- `emailAndPassword: { enabled: true }` - For email/password auth
185 
186**Standard config adds:**
187- `socialProviders` - OAuth providers (google, github, etc.)
188- `emailVerification.sendVerificationEmail` - Email verification handler
189- `emailAndPassword.sendResetPassword` - Password reset handler
190 
191**Full config adds:**
192- `plugins` - Array of feature plugins
193- `session` - Expiry, cookie cache settings
194- `account.accountLinking` - Multi-provider linking
195- `rateLimit` - Rate limiting config
196 
197**Export types:** `export type Session = typeof auth.$Infer.Session`
198 
199---
200 
201## Client Config (auth-client.ts)
202 
203**Import by framework:**
204| Framework | Import |
205|-----------|--------|
206| React/Next.js | `better-auth/react` |
207| Vue | `better-auth/vue` |
208| Svelte | `better-auth/svelte` |
209| Solid | `better-auth/solid` |
210| Vanilla JS | `better-auth/client` |
211 
212**Client plugins** go in `createAuthClient({ plugins: [...] })`.
213 
214**Common exports:** `signIn`, `signUp`, `signOut`, `useSession`, `getSession`
215 
216---
217 
218## Route Handler Setup
219 
220| Framework | File | Handler |
221|-----------|------|---------|
222| Next.js App Router | `app/api/auth/[...all]/route.ts` | `toNextJsHandler(auth)` → export `{ GET, POST }` |
223| Next.js Pages | `pages/api/auth/[...all].ts` | `toNextJsHandler(auth)` → default export |
224| Express | Any file | `app.all("/api/auth/*", toNodeHandler(auth))` |
225| SvelteKit | `src/hooks.server.ts` | `svelteKitHandler(auth)` |
226| SolidStart | Route file | `solidStartHandler(auth)` |
227| Hono | Route file | `auth.handler(c.req.raw)` |
228 
229**Next.js Server Components:** Add `nextCookies()` plugin to auth config.
230 
231---
232 
233## Database Migrations
234 
235| Adapter | Command |
236|---------|---------|
237| Built-in Kysely | `npx @better-auth/cli@latest migrate` (applies directly) |
238| Prisma | `npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev` |
239| Drizzle | `npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` |
240 
241**Re-run after adding plugins.**
242 
243---
244 
245## Database Adapters
246 
247| Database | Setup |
248|----------|-------|
249| SQLite | Pass `better-sqlite3` or `bun:sqlite` instance directly |
250| PostgreSQL | Pass `pg.Pool` instance directly |
251| MySQL | Pass `mysql2` pool directly |
252| Prisma | `prismaAdapter(prisma, { provider: "postgresql" })` from `better-auth/adapters/prisma` |
253| Drizzle | `drizzleAdapter(db, { provider: "pg" })` from `better-auth/adapters/drizzle` |
254| MongoDB | `mongodbAdapter(db)` from `better-auth/adapters/mongodb` |
255 
256---
257 
258## Common Plugins
259 
260| Plugin | Server Import | Client Import | Purpose |
261|--------|---------------|---------------|---------|
262| `twoFactor` | `better-auth/plugins` | `twoFactorClient` | 2FA with TOTP/OTP |
263| `organization` | `better-auth/plugins` | `organizationClient` | Teams/orgs |
264| `admin` | `better-auth/plugins` | `adminClient` | User management |
265| `bearer` | `better-auth/plugins` | - | API token auth |
266| `openAPI` | `better-auth/plugins` | - | API docs |
267| `passkey` | `@better-auth/passkey` | `passkeyClient` | WebAuthn |
268| `sso` | `@better-auth/sso` | - | Enterprise SSO |
269 
270**Plugin pattern:** Server plugin + client plugin + run migrations.
271 
272---
273 
274## Auth UI Implementation
275 
276**Sign in flow:**
2771. `signIn.email({ email, password })` or `signIn.social({ provider, callbackURL })`
2782. Handle `error` in response
2793. Redirect on success
280 
281**Session check (client):** `useSession()` hook returns `{ data: session, isPending }`
282 
283**Session check (server):** `auth.api.getSession({ headers: await headers() })`
284 
285**Protected routes:** Check session, redirect to `/sign-in` if null.
286 
287---
288 
289## Security Checklist
290 
291- [ ] `BETTER_AUTH_SECRET` set (32+ chars)
292- [ ] `advanced.useSecureCookies: true` in production
293- [ ] `trustedOrigins` configured
294- [ ] Rate limits enabled
295- [ ] Email verification enabled
296- [ ] Password reset implemented
297- [ ] 2FA for sensitive apps
298- [ ] CSRF protection NOT disabled
299- [ ] `account.accountLinking` reviewed
300 
301---
302 
303## Troubleshooting
304 
305| Issue | Fix |
306|-------|-----|
307| "Secret not set" | Add `BETTER_AUTH_SECRET` env var |
308| "Invalid Origin" | Add domain to `trustedOrigins` |
309| Cookies not setting | Check `baseURL` matches domain; enable secure cookies in prod |
310| OAuth callback errors | Verify redirect URIs in provider dashboard |
311| Type errors after adding plugin | Re-run CLI generate/migrate |
312 
313---
314 
315## Resources
316 
317- [Docs](https://better-auth.com/docs)
318- [Examples](https://github.com/better-auth/examples)
319- [Plugins](https://better-auth.com/docs/concepts/plugins)
320- [CLI](https://better-auth.com/docs/concepts/cli)
321- [Migration Guides](https://better-auth.com/docs/guides)
322