better-auth-scaffold — Claude Code skill: what it does, how to install
better-auth-scaffold scaffolds Better Auth in a Next.js App Router project on Drizzle: file templates, three plugin presets, schema generation and migrations.
MIT 143 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill better-auth-scaffold -a claude-codeWhat better-auth-scaffold does
The skill lays down the Better Auth wiring for a Next.js App Router project running the Drizzle adapter. It fills templates with your values and writes lib/auth.ts, lib/auth-client.ts, the catch-all handler at app/api/auth/[...all]/route.ts, middleware.ts and .env.example. Pick one of three presets: minimal for email and password, social to add Google and GitHub, advanced for social plus twoFactor and magicLink.
You must supply db_provider (pg, mysql or sqlite) and app_name; anything else comes from config.json or gets asked for. Conditional // PRESET[...] blocks are stripped to match the chosen preset, and protected_paths turn into the routes the middleware guards. A file that already exists with different contents is never overwritten quietly: you get a diff and a choice between overwrite, merge and skip. Then the CLI runs npx @better-auth/cli@latest generate, npx drizzle-kit generate and npx drizzle-kit migrate, replacing the db/schema/auth.ts stub with the real schema.
Handwork is left over. Copy .env.example to .env.local, make a secret with openssl rand -base64 32, register redirect URIs in each provider console for social and advanced, and fill in lib/email.ts for advanced. The templates follow house rules: lib/auth.ts is server-only, nextCookies() sits last in the plugin array, secrets go through process.env. Middleware only looks for a cookie, so pages still have to validate the session themselves.
What it helps with
- bootstrap email and password auth in a fresh Next.js project
- add Google and GitHub sign-in to an existing Drizzle schema
- fill in the missing catch-all route handler for Better Auth
- generate the auth schema and apply migrations with
drizzle-kit - break a middleware redirect loop by adding a sign-in page
Example prompts for the agent
- Set up Better Auth here: Postgres, app name Academy, social preset
- Add auth to Next.js with Drizzle, email and password plus twoFactor
- Initialize auth and put
/dashboardand/billingbehind middleware
How to install better-auth-scaffold
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill better-auth-scaffold -a claude-code2Manually: put the files in place
~/.claude/skills/better-auth-scaffold/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/better-auth-scaffold/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill better-auth-scaffold -a codex2Manually: put the files in place
.agents/skills/better-auth-scaffold/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill better-auth-scaffold -a cursor2Manually: put the files in place
.cursor/skills/better-auth-scaffold/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/better-auth-scaffold2Manually: put the files in place
.github/skills/better-auth-scaffold/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill better-auth-scaffold -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/better-auth-scaffoldManually: put the files in place
.devin/skills/better-auth-scaffold/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill better-auth-scaffold -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about better-auth-scaffold
How to install better-auth-scaffold in Claude Code?
Run npx skills add pproenca/dot-skills --skill better-auth-scaffold -a claude-code. The skill lands at ~/.claude/skills/better-auth-scaffold/SKILL.md.
What does better-auth-scaffold do?
It writes the Better Auth files from templates: server and client modules, the catch-all route, middleware, .env.example, a Drizzle schema stub and a sign-in page. The preset decides which plugins go in, from email and password up to twoFactor with magicLink.
Which parameters do I have to provide?
db_provider (pg, mysql or sqlite) and app_name, which also becomes the issuer name in authenticator apps for the advanced preset. The rest, such as protected_paths, have defaults.
Source text
SKILL.md · MIT
---
name: better-auth-scaffold
description: Scaffolds a Better Auth setup in a Next.js (App Router) + Drizzle project — lib/auth.ts, lib/auth-client.ts, the /api/auth/[...all] route handler, middleware.ts, .env.example, and a permissions module. Produces convention-enforced templates for three plugin presets (minimal, social, advanced with twoFactor+magicLink). Trigger even when the user doesn't explicitly say "scaffold" — phrases like "set up Better Auth", "wire up auth", "initialize auth in this project", or "add auth to Next.js" should pull this in. Pairs with the `better-auth` skill, which covers the rules these templates encode.
---
# 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.
© pproenca · MIT · pproenca/dot-skills