better-auth-scaffold

# Better Auth Scaffold (Next.js + Drizzle) Parameterized templates for bootstrapping a Better Auth setup in a Next.js App Router project using the Drizzle adapter. Each template enforces the conventions documented in [`references/conventions.md`](references/conventions.md) — file layout, plugin ordering, env handling, runtime selection. ## When to Apply Reference these templates when: - Starting a new Next.js project that needs authentication - Adding Better Auth to an existing Next.js + Drizzle codebase - Refactoring a partial Better Auth setup that's missing the catch-all route, middleware, or `nextCookies()` ordering - Generating a per-feature variant (minimal, social, advanced) on top of an existing project ## Setup ### Required parameters | Parameter | Required | Default | Description | |---|---|---|---| | `preset` | no | `minimal` | `minimal` (email+password) \| `social` (adds Google + GitHub) \| `advanced` (social + twoFactor + magicLink) | | `db_provider` | yes | — | `pg` \| `mysql` \| `sqlite` (Drizzle provider) | | `app_name` | yes | — | Display name (becomes 2FA issuer in authenticator apps when preset=advanced) | ### Optional parameters | Parameter | Default | Description | |---|---|---| | `auth_path` | `lib/auth.ts` | Server auth module path | | `client_path` | `lib/auth-client.ts` | Client module path | | `api_route_path` | `app/api/auth/[...all]/route.ts` | Catch-all route handler path | | `protected_paths` | `["/dashboard"]` | Routes the middleware guards | If `config.json` already exists with values, the skill uses those; otherwise it asks the user. ## Available Templates | Template | Output File | When to emit | |---|---|---| | [`auth.ts.template`](assets/templates/auth.ts.template) | `lib/auth.ts` | Always | | [`auth-client.ts.template`](assets/templates/auth-client.ts.template) | `lib/auth-client.ts` | Always | | [`route.ts.template`](assets/templates/route.ts.template) | `app/api/auth/[...all]/route.ts` | Always | | [`middleware.ts.template`](assets/templates/middleware.ts.template) | `middleware.ts` | When `protected_paths` is non-empty | | [`env.template`](assets/templates/env.template) | `.env.example` | Always | | [`db-schema-better-auth.ts.template`](assets/templates/db-schema-better-auth.ts.template) | `db/schema/auth.ts` | Always (stub — replace with output of `better-auth generate`) | | [`db-index.ts.template`](assets/templates/db-index.ts.template) | `db/index.ts` | When the project has no Drizzle client yet | | [`email.ts.template`](assets/templates/email.ts.template) | `lib/email.ts` | When `preset=advanced` (and the file doesn't already exist) | | [`sign-in-page.tsx.template`](assets/templates/sign-in-page.tsx.template) | `app/sign-in/page.tsx` | When the project has no sign-in page (closes the middleware redirect loop) | | [`permissions.ts.template`](assets/templates/permissions.ts.template) | `lib/permissions.ts` | Optional starter for org/admin plugin work | ## How to Use 1. **Resolve parameters.** Read `config.json` first; for any missing required parameter (`db_provider`, `app_name`), ask the user via `AskUserQuestion`. 2. **Render each template.** For each template file: - Read the template. - Substitute `{{placeholder}}` values (`{{app_name}}`, `{{db_provider}}`, etc.) with the resolved parameter values. - Apply `PRESET[...]` conditional blocks using these rules: 1. Find every pair of marker lines matching `// PRESET[<tags>]` and `// /PRESET[<tags>]` (or `/* PRESET[...] */` / `# PRESET[...]` for non-JS files — same syntax, different comment style). 2. Parse `<tags>` as a comma-separated list (e.g. `social,advanced`). 3. If the chosen preset value is in `<tags>` → remove ONLY the two marker lines; keep the lines between them. 4. If the chosen preset value is NOT in `<tags>` → remove the ENTIRE block including both marker lines. 5. Markers may be nested (e.g. `PRESET[advanced]` inside `PRESET[minimal,social,advanced]`); process from inside out. - For Mustache-style iteration in `middleware.ts.template` (`// {{#protected_paths}}` ... `// {{/protected_paths}}`), repeat the lines between the markers once per item in the list, substituting `{{path}}` with each value. 3. **Write output files.** Before writing, check if the target file already exists: - If it doesn't exist → write it. - If it exists and is identical → no-op. - If it exists and differs → show a diff and ask the user (overwrite / merge / skip). 4. **Run the CLI sequence.** After all files are written: ```bash npx @better-auth/cli@latest generate npx drizzle-kit generate npx drizzle-kit migrate ``` These commands replace the placeholder `db/schema/auth.ts` with the real schema and apply migrations. 5. **Print next steps.** Tell the user to: - Fill in `.env.local` (copy from `.env.example`) - Generate a secret: `openssl rand -base64 32` - Register OAuth redirect URIs with each provider console (for `social`/`advanced` presets) - Implement `lib/email.ts` to wire transactional email (for `advanced` preset) ## Conventions Read [`references/conventions.md`](references/conventions.md) for the rationale behind every convention these templates encode. Highlights: - `lib/auth.ts` is server-only (`import "server-only"`) - `nextCookies()` is ALWAYS the last plugin in the array - Middleware does a cookie-presence check only; real validation in pages - All secrets via `process.env.*`, never inline - Sliding-window sessions with `cookieCache` enabled ## Related Skills - [`better-auth`](../better-auth/SKILL.md) — Library/API Reference with 42 rules covering setup, sessions, security, plugins, and migration. The templates here are one canonical realization of those rules; read the rule for the underlying reasoning when you need to deviate. ## Gotchas See [`gotchas.md`](gotchas.md) — initialized empty, populated as we discover them.