auth-setup

name	auth-setup
description	Set up authentication for web apps. Supports Better Auth and Firebase Auth. Handles email/password, Google OAuth, sessions, middleware, protected routes. Includes UI components. Auto-detects existing project themes. (GitHub & Apple OAuth coming soon)
version	1.7.1
license	MIT

Auth Setup

Production-ready authentication for any web app in under 45 minutes. 2 auth providers (Better Auth & Firebase), Google OAuth, copy-paste UI components, and a verification script. GitHub & Apple OAuth coming soon.

When to Use

• Starting a new project needing user authentication
• Adding auth to an existing app (auto-detects and adapts to existing theme)
• Migrating between auth providers
• Setting up OAuth social login (Google, GitHub, Apple)
• Need login/register page components

CRITICAL — New Project Scaffolding

If scaffolding a new Next.js project, never run create-next-app . in the current directory. Claude Code plugins (OMC, gstack) create dotfiles (.omc/, .claude/) that conflict with create-next-app, which requires a completely empty directory. The dotfiles are recreated by hooks between deletion and scaffolding, causing an infinite failure loop.

Correct pattern — scaffold in /tmp, pin to Next.js 14:

SCAFFOLD_DIR=/tmp/nextjs-scaffold-$RANDOM && \
npx create-next-app@14 "$SCAFFOLD_DIR" \
  --typescript --tailwind --eslint --app --src-dir \
  --import-alias "@/*" --use-npm --no-turbopack && \
cp -a "$SCAFFOLD_DIR"/. . && rm -rf "$SCAFFOLD_DIR"

Why @14 not @latest? Next.js 16 deprecated middleware.ts in favor of proxy.ts. All templates, guides, and middleware examples in this plugin use the middleware.ts convention (Next.js 14/15). Using @latest will install Next.js 16+ and the build will fail. See pitfall #37 for details.

Or scaffold into a named subdirectory, then move files up.

shadcn/ui: Use npx shadcn@2.1.0 init -d (NOT shadcn@2 or shadcn@latest). shadcn@2.5+ expects Tailwind v4's CSS-based config and fails with Next.js 14's tailwind.config.ts. After shadcn init, you MUST install tailwindcss-animate — shadcn adds it to tailwind.config.ts but does NOT auto-install it: {pm} install tailwindcss-animate (use package manager detected in Step 0). See pitfall #44.

Provider Decision Framework

Your situation	Best choice	Why
Full control, no vendor lock-in	Better Auth	Open-source, self-hosted, most flexible, zero cost
Google ecosystem or mobile + web	Firebase Auth	Best mobile/KMP support, free < 50K MAU

Note: Clerk, Auth.js, and Supabase Auth support is planned for a future release. Currently only Better Auth and Firebase Auth are fully supported.

Full comparison with cost analysis: references/01-choosing-provider.md

Quick Start

Step 0: Auto-Discover Project Stack (SILENT — no user interaction)

Before asking ANY questions, scan the project silently:

0a. Framework & Router:

• Check next.config.* (.js, .mjs, .ts) → Next.js
• Check astro.config.* → Astro
• Check remix.config.* or @remix-run/* in deps → Remix
• Check vite.config.* without framework deps → Vite
• Check app/ directory → App Router | pages/ directory → Pages Router
• If no framework detected → warn: "No supported framework detected. This plugin is designed for Next.js App Router."
• If Pages Router only (no app/) → warn: "Pages Router detected. This plugin requires Next.js App Router (app/ directory)."

0b. Version Compatibility:

• Read package.json and extract versions:
  • next — check major version (14, 15, 16+)
  • react — must be ≥18 for Server Components
  • node — check engines field or .nvmrc if exists
• ❌ BLOCK if Next.js < 14: "This plugin requires Next.js 14+ with App Router."
• ❌ BLOCK if React < 18: "React 18+ required for Server Components."
• ⚠️ WARNING if Next.js ≥ 16: "Next.js 16 detected. middleware.ts is deprecated — plugin will use proxy.ts pattern instead."
• Store version for later decisions:
  • Next.js 14 → experimental: { serverComponentsExternalPackages: [...] }
  • Next.js 15+ → serverExternalPackages: [...]

0c. Database ORM:

• Check drizzle.config.ts or drizzle.config.js → Drizzle
• Check prisma/schema.prisma → Prisma
• Fallback: check package.json for drizzle-orm or @prisma/client
• If both detected → prefer the one with config file
• If none detected → will ask user in Q3 (don't block)

0d. Existing Auth:

• Check src/lib/auth.ts + better-auth in deps → Better Auth already installed
• Check src/lib/firebase.ts + firebase in deps → Firebase already installed
• Check @clerk/nextjs in deps → Clerk detected
• Check next-auth in deps → Auth.js/NextAuth detected
• Check @supabase/ssr in deps → Supabase Auth detected
• If auth detected → ⚠️ WARNING: "Existing auth setup detected ({provider}). Running setup may conflict. Run /shipwithai-auth:doctor first to check health, or confirm you want to replace it."

0e. Existing Auth Pages & Routes:

• Check for existing pages: src/app/(auth)/login/, src/app/login/, app/login/
• Check for existing API routes: src/app/api/auth/, app/api/auth/
• Check for existing middleware: src/middleware.ts, middleware.ts
• If found → store list, will warn before overwriting in Step 2

0f. Package Manager:

• pnpm-lock.yaml → pnpm
• yarn.lock → yarn
• bun.lockb → bun
• package-lock.json → npm
• Default to npm if no lockfile found

0g. UI Library:

• Check components.json → shadcn/ui (read style and baseColor fields)
• Check @mui/material in deps → MUI
• Check @chakra-ui/react in deps → Chakra UI
• Check @mantine/core in deps → Mantine
• Check for Tailwind: tailwind.config.* or tailwindcss in deps
• If shadcn/ui detected → skip shadcn init in setup, only add missing components
• If non-shadcn UI library detected → ⚠️ WARNING: "Detected {library}. Auth components use shadcn/ui — you may need to adapt styling."

0h. Existing Design System (Context Project):

• This is detected via Question 5 (cannot auto-detect parent project path)
• But if globals.css already has shadcn CSS variables → Scenario A (skip theme generation)

Show discovery summary to user:

🔍 Project scan complete

Framework:     Next.js 14.2.18 (App Router)
Package mgr:   npm
ORM:           Drizzle (drizzle-orm@0.30.10)
UI:            shadcn/ui (new-york style)
Existing auth: None detected
Existing pages: /dashboard (protected)
Node.js:       v20.11.0
React:         18.3.1

Ready to set up authentication.

If critical issues found, STOP and report:

⛔ Cannot proceed:
- Next.js 13 detected — requires Next.js 14+ with App Router
- No `app/` directory found — Pages Router not supported

Fix these issues first, then re-run /shipwithai-auth:setup

Step 1: Choose provider

Ask user which provider using AskUserQuestion. Present options:

1. Better Auth (Recommended) — Free, self-hosted, full control. Open-source, no vendor lock-in. Best for most projects.
2. Firebase Auth — Google ecosystem, best for mobile/KMP apps. Free < 50K MAU.
3. Clerk — ⚠️ Coming Soon
4. Supabase Auth — ⚠️ Coming Soon
5. Auth.js — ⚠️ Coming Soon

If user selects a "Coming Soon" provider: Do NOT proceed. Warn and re-ask with only supported options.

If unsure, ask:

• "Need mobile support (KMP/React Native)?" → Firebase Auth
• "Want self-hosted, full control, zero cost?" → Better Auth
• "Using Google ecosystem (Firebase, GCP)?" → Firebase Auth
• "Building a SaaS with custom auth logic?" → Better Auth

Step 1a: Choose OAuth

Ask user which social login using AskUserQuestion. Present options:

1. Google only (Recommended) — Most common, covers 90%+ of users
2. Google + GitHub — ⚠️ GitHub Coming Soon
3. Google + GitHub + Apple — ⚠️ GitHub & Apple Coming Soon
4. None — Email/password only, add social login later

If user selects an option with "Coming Soon" providers: Warn, then proceed with Google only. Mention /shipwithai-auth:add-oauth for future providers.

Step 1b: Detect theme context

ALWAYS run this step — even for new projects. Use Step 0 discovery results to auto-classify where possible.

There are 4 scenarios:

Scenario	Condition	globals.css Action
A	Existing project with shadcn/ui (detected in 0g)	SKIP — use existing CSS variables
B	Existing project with Tailwind but no shadcn/ui (detected in 0g)	MERGE — add shadcn/ui vars to existing globals.css
C	Standalone new project (no parent design system)	AUTO-SELECT — AI picks Ocean or Sunrise preset
D	New project inside/alongside existing project	INHERIT — map parent's design tokens to shadcn/ui vars

Auto-classification from Step 0:

• If Step 0 detected shadcn/ui (components.json exists) → Scenario A — skip to Step 2, no question needed
• If Step 0 detected Tailwind but no shadcn/ui → Scenario B — confirm with user, then merge
• If Step 0 detected existing auth pages → likely Scenario A or B, confirm with user

Only ask Question 5 if scenario is ambiguous:

• If this is a new project being scaffolded (no existing globals.css) → ask: "Is this new app part of an existing project with its own design system?"
• If YES → get the parent project path and run: npx ts-node scripts/detect-theme.ts /path/to/new-app --context /path/to/parent-project
• If NO → Scenario C, proceed with AI theme auto-selection (see below)

Scenario C (NEW PROJECT) — AI auto-selects theme:

Two curated theme presets are available in assets/themes/. Do NOT ask the user to choose — pick automatically based on project signals:

Theme	File	Font	Best for
Ocean	assets/themes/ocean.css	DM Sans	SaaS, dashboard, dev tools, API, analytics, admin, B2B
Sunrise	assets/themes/sunrise.css	Outfit	Consumer, blog, shop, community, education, portfolio, e-commerce

Auto-selection logic (SILENT — no user interaction):

1. Read package.json → name and description fields
2. Read README.md first paragraph (if exists)
3. Match keywords against domain signals:
   • SaaS / dashboard / admin / api / analytics / dev / tool / platform / monitor / deploy → Ocean
   • blog / shop / store / community / social / education / learn / portfolio / landing / market → Sunrise
4. If ambiguous or no signals → Ocean (default)

After selecting theme:

1. Run npx shadcn@2.1.0 init -d first (creates default globals.css)
2. Overwrite globals.css with the selected theme preset file
3. Add the theme's Google Font import at the top of globals.css:
   • Ocean: @import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&display=swap');
   • Sunrise: @import url('https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700&display=swap');
4. Update layout.tsx to use the theme's font instead of default Geist:
   • Ocean: import { DM_Sans } from "next/font/google" → const font = DM_Sans({ subsets: ["latin"] })
   • Sunrise: import { Outfit } from "next/font/google" → const font = Outfit({ subsets: ["latin"] })
5. Ocean is dark-first → set <html className="dark"> in layout.tsx
6. Show the selected theme in the Step 0 summary:

   Theme:         Ocean (dark, DM Sans) — auto-selected for SaaS project
   

Scenario D (INHERIT) — what to do:

• CRITICAL ordering: Run npx shadcn@2.1.0 init -d FIRST, then apply the inherited theme. shadcn init overwrites globals.css with default variables — if you apply the inherited theme first, shadcn will destroy it.
• The script scans the parent's CSS files and extracts design tokens (backgrounds, text colors, accents, borders, fonts, border-radius)
• It maps them to shadcn/ui CSS variables and outputs a shadcnMapping with dark and light mode values
• After shadcn init completes, overwrite globals.css with the inherited theme mapping
• Add the parent's Google Fonts @import to globals.css
• Set className="dark" on <html> if the parent is dark-first
• Update layout.tsx to use the parent's font-family instead of default Geist

Key rule: Auth components use shadcn/ui CSS variables (--primary, --background, etc.). The theme detection ensures these variables match the surrounding project's design — whether it's the same project (A/B), a parent/sibling project (D), or an auto-selected preset (C).

See references/10-existing-project-integration.md for detailed adaptation steps.

Step 2: Follow provider guide

Provider	Guide
Better Auth	references/02-better-auth-guide.md
Firebase Auth	references/05-firebase-auth-guide.md

Step 3: Email provider (Better Auth only)

Skip this step for Firebase — Firebase handles email delivery automatically.

For Better Auth — you MUST ask the user before proceeding. Do NOT skip this question. Do NOT assume console-only. STOP and ASK:

"How should auth emails be sent? (verification emails, password reset links)

A) Resend (Recommended) — free tier: 100 emails/day, simple API, works in 2 minutes B) Console only (Development) — emails log to terminal, no real delivery C) Other provider — you'll configure SendGrid/Nodemailer/etc. yourself"

WAIT for the user's answer before writing any auth config files.

If A (Resend):

1. Install: {pm} install resend (use package manager detected in Step 0)
2. Add to .env.local: RESEND_API_KEY=re_xxxxx and EMAIL_FROM=[e-mail]
3. Create src/lib/email.ts with the sendAuthEmail helper from the Better Auth guide → "Email Provider — Resend" section
4. Update sendVerificationEmail and sendResetPassword callbacks in src/lib/auth.ts to use sendAuthEmail
5. IMPORTANT — Tell the user after setup: "With Resend's free tier and [e-mail] as sender, emails can ONLY be delivered to the email address that owns your Resend account. To send to any email, verify your own domain at resend.com/domains and change EMAIL_FROM to [e-mail]."

If B (Console):

1. Keep the console.log stubs in auth config (already the default)
2. Tell user: "Check your terminal for verification/reset links during development"

If C (Other):

1. Keep the console.log stubs as placeholder
2. Tell user to replace the callbacks with their email service

Step 4: Add social login

Currently supported: Google OAuth only. GitHub and Apple are coming soon.

See references/07-oauth-social-login.md for Google setup across all providers.

Step 5: Database schema

See references/08-database-auth-schema.md for Drizzle/Prisma/Supabase schemas.

Step 6: Add UI components

Use Step 0 discovery results:

• If shadcn/ui already detected (0g) → skip shadcn init, only run npx shadcn@2.1.0 add button input label card separator for missing components
• If shadcn/ui NOT detected → run npx shadcn@2.1.0 init -d first, then add components. Remember: for Scenario D, apply inherited theme AFTER shadcn init.
• If existing auth pages detected (0e) → ⚠️ WARN user before overwriting: "Found existing {page}. Overwrite with plugin component?"
• Use detected package manager (0f) for all install commands

Components are organized by provider. Copy from the correct folder:

• Better Auth: assets/components/better-auth/
• Firebase Auth: assets/components/firebase/
• Shared (provider-agnostic): assets/components/shared/

REQUIRED — Core auth pages (MUST copy all of these):

File	Source folder	Place at	Purpose
login-page.tsx	{provider}/	app/(auth)/login/page.tsx	Login with email + social buttons
register-page.tsx	{provider}/	app/(auth)/register/page.tsx	Registration form
forgot-password.tsx	{provider}/	app/(auth)/forgot-password/page.tsx	Password reset request (sends email)
reset-password.tsx	{provider}/	app/(auth)/reset-password/page.tsx	Complete password reset (token from email → new password)
protected-layout.tsx	{provider}/	app/(protected)/layout.tsx	Server-side session verification
dashboard-client.tsx	{provider}/	app/(protected)/dashboard/dashboard-client.tsx	Sign-out button (client component)
dashboard-page.tsx	shared/	app/(protected)/dashboard/page.tsx	Protected dashboard page
icons.tsx	shared/	src/components/icons.tsx	OAuth provider SVG icons (Google, GitHub) — required by login/register pages
globals.css	shared/	app/globals.css	Tailwind CSS directives + shadcn/ui variables

RECOMMENDED — User management (copy unless user explicitly declines):

File	Source folder	Place at	Purpose
user-profile.tsx	{provider}/	app/(protected)/profile/page.tsx	Profile view + update name + sign out + delete account

OPTIONAL:

• auth-provider-buttons.tsx — Standalone OAuth buttons (already included in login/register pages)

Copy from assets/config/:

• next.config.ts — Security headers (X-Frame-Options, HSTS, etc.) — merge into existing config
• drizzle.config.ts — Drizzle Kit config with dialect: "sqlite" (Better Auth only) — copy to project root

Where {provider} = better-auth or firebase depending on the chosen provider.

CRITICAL for Firebase Auth — File creation checklist: You MUST create ALL of these files for Firebase to work. Do NOT skip any:

1. src/lib/firebase.ts — Client SDK init (from firebase.config.ts → "Client SDK Setup")
2. src/lib/firebase-admin.ts — Admin SDK init (from firebase.config.ts → "Admin SDK Setup")
3. src/lib/firebase-session.ts — createSessionCookie() + clearSessionAndSignOut() helpers (from firebase.config.ts → "Session Cookie Helper" + "Sign-Out Helper")
4. src/lib/auth-server.ts — getServerUser() helper (from firebase.config.ts → "Server Component Auth Check"). Import this in BOTH (protected)/layout.tsx AND (protected)/dashboard/page.tsx — do NOT duplicate the function inline
5. src/app/api/auth/session/route.ts — Session API with rate limiting + CSRF (from firebase.config.ts → "Session Cookie API Route"). The POST handler MUST be wrapped in try/catch — return 401 on invalid token, never 500
6. src/middleware.ts — Route protection (from assets/middleware/firebase/nextjs-middleware.ts)
7. app/globals.css — Tailwind v3 directives (@tailwind base; @tailwind components; @tailwind utilities;) + shadcn/ui hsl CSS variables — layout.tsx imports this file. Copy from assets/components/shared/globals.css

CRITICAL for Firebase Auth — Google OAuth Setup: If using Google sign-in with signInWithPopup, you MUST complete the 5-step OAuth setup checklist in references/05-firebase-auth-guide.md → "Google OAuth Setup Checklist". Without it, sign-in will fail with 400 Bad Request. Key points:

1. Enable Google provider in Firebase Console (not just Google Cloud Console)
2. Configure the correct OAuth client ID in Google Cloud Console (must match Firebase's Web client ID)
3. Add https://<PROJECT>.firebaseapp.com/__/auth/handler to Authorized redirect URIs (NOT /api/auth/callback/google — that's Auth.js)
4. If OAuth consent screen is in Testing mode, add test user emails → Read references/05-firebase-auth-guide.md → "Google OAuth Setup Checklist" for full steps

CRITICAL for Firebase Auth — Session flow:

1. After sign-in/register, call createSessionCookie(result.user) and await it
2. Only THEN redirect to /dashboard
3. On sign-out, call clearSessionAndSignOut() FIRST (clears server cookie + Firebase), then redirect
4. Never rely on onAuthStateChanged for the initial login redirect

CRITICAL for Firebase Auth Security:

1. Set NEXT_PUBLIC_APP_URL env var — required for CSRF protection on session endpoint
2. Place protected pages under app/(protected)/ and use protected-layout.tsx to verify sessions server-side (middleware only checks cookie existence, NOT validity)
3. The session DELETE handler revokes Firebase refresh tokens — stolen sessions are invalidated immediately
4. Error messages use generic text — never expose Firebase error codes to users

CRITICAL for Firebase Auth — Middleware routes: Only include routes in protectedRoutes that have actual pages. Default: ["/dashboard"]. Add /profile only if user-profile.tsx was copied. Do NOT add /settings or /profile unless those pages exist.

CRITICAL for Firebase Auth — Middleware security: The middleware runs on Edge Runtime and CANNOT use Firebase Admin SDK. It MUST only check cookie existence (request.cookies.get("__session")?.value). Do NOT attempt to decode, parse, or validate the JWT in middleware — Base64-decoding the payload without verifying the cryptographic signature gives a false sense of security. An attacker can craft a fake JWT that passes the decode check. Real verification happens in (protected)/layout.tsx via adminAuth.verifySessionCookie().

CRITICAL for Better Auth — File creation checklist: You MUST create ALL of these files for Better Auth to work. Do NOT skip any:

1. src/db/schema.ts — Drizzle schema with Better Auth tables (from assets/db/better-auth-schema.ts)
2. src/lib/db.ts — Drizzle client (from assets/db/better-auth-db.ts). MUST import and pass schema to drizzle(client, { schema })
3. src/lib/auth.ts — Server config (from assets/config/better-auth.config.ts). MUST pass schema to drizzleAdapter: drizzleAdapter(db, { provider: "sqlite", schema })
4. src/lib/auth-client.ts — Client setup (from better-auth.config.ts → "Client Setup" section)
5. src/app/api/auth/[...all]/route.ts — API route handler
6. src/middleware.ts — Route protection using cookie-based pattern (from assets/middleware/better-auth/nextjs-middleware.ts). Do NOT use auth() wrapper — that's Auth.js, not Better Auth (see pitfall #43)
7. src/app/(protected)/layout.tsx — Server-side session verification
8. .env.local — Copy from assets/config/better-auth.env.example and fill in values
9. drizzle.config.ts — Copy from assets/config/drizzle.config.ts. MUST use dialect: "sqlite" (NOT driver: "better-sqlite" — removed in drizzle-kit 0.21+). See pitfall #48.
10. Database migration — Create tables with npx drizzle-kit push (or npx @better-auth/cli generate && npx @better-auth/cli migrate)
11. UI components — Copy login, register, forgot-password, reset-password, dashboard from assets/components/better-auth/ (shared components from assets/components/shared/)
12. reset-password.tsx already includes a <Suspense> wrapper — useSearchParams() requires this in Next.js 14+ App Router or the build fails. Do NOT remove the Suspense wrapper.
13. shadcn/ui: Use npx shadcn@2.1.0 (NOT @latest or @2) to avoid Tailwind v4 conflicts with Next.js 14. See pitfall #44.

CRITICAL for Better Auth — next.config.ts compatibility: When adding better-sqlite3 or other native packages to next.config.ts:

• Next.js 14: Use experimental: { serverComponentsExternalPackages: ["better-sqlite3"] }
• Next.js 15+: Use serverExternalPackages: ["better-sqlite3"] Check the project's Next.js version in package.json BEFORE writing the config. Using the wrong syntax causes: Unrecognized key(s) in object: 'serverExternalPackages'.

CRITICAL for Better Auth — Session flow:

1. Better Auth manages sessions via cookies (better-auth.session_token) — no manual cookie creation needed (unlike Firebase)
2. cookieCache is enabled by default (5 min) — session changes (role updates, email verification) take up to 5 minutes to propagate
3. In Server Components, use auth.api.getSession({ headers: await headers() }) — this verifies the session cryptographically
4. In middleware, check the better-auth.session_token cookie directly — do NOT use auth() wrapper (that's Auth.js, see pitfall #43). Do NOT use headers() from next/headers in middleware (Edge Runtime incompatible)

NOTE for Better Auth: The forgot-password page sends a reset link via email. You MUST also copy reset-password.tsx to app/(auth)/reset-password/page.tsx to handle the link destination. Without it, users get a 404.

CRITICAL for shadcn/ui Button: If using buttonVariants in a Server Component (e.g., home page), extract buttonVariants into a separate file WITHOUT "use client" directive. The Button component needs "use client" but buttonVariants is a pure function that can run on the server.

Step 7: Verify

Run scripts/verify-auth-setup.ts to confirm auth works end-to-end. The script now includes dangerous code pattern detection — it catches module-scope SDK instantiation, wrong middleware patterns, missing Suspense wrappers, and other pitfalls automatically.

Step 8: Generate README (CRITICAL — must run, even after compaction)

Copy the provider's assets/templates/providers/{better-auth|firebase}/README.md.tmpl, substitute placeholders, write to end-user project root as README.md. Do NOT improvise — template is source of truth.

MANDATORY FLOW: Read → Ask → Write. Never call Write on README.md without first checking existence and asking the user. The Write tool fails with Error writing file when the target exists and has not been Read in this session — this is a guard against silent overwrites.

Step 8a — Existing README guard (MUST run before any Write):

1. Check existence FIRST. Use Glob with pattern README.md (or Bash: ls README.md 2>/dev/null) to detect.
2. If README.md does NOT exist → skip to Step 8b, proceed with Write directly.
3. If README.md EXISTS: a. Read it first (Read README.md) — required before any later Write to that path AND so you can summarize current content to the user. b. Call AskUserQuestion with these 3 options (do NOT silently pick one):
   • A) Append AUTH section (default — preserves existing content, adds auth docs at the end via Edit)
   • B) Overwrite (backup current → README.md.bak via Bash: cp README.md README.md.bak, then Write new README)
   • C) Save separately as README.AUTH.md (Write to a new path; existing README untouched) c. Wait for the user's answer. Do NOT proceed on assumption. d. Execute the chosen branch:
   • A (Append): Use Edit to append the rendered template under a new ## Authentication section. Do NOT use Write (it would overwrite).
   • B (Overwrite): Run backup Bash command first → verify .bak exists → then Write README.md with new content.
   • C (Separate): Write to README.AUTH.md instead of README.md. Mention the new file in the final summary.

Recovery — if Write README.md already failed with Error writing file: The file exists and was not Read. Do NOT retry the same Write. Instead: Read README.md → run Step 8a's AskUserQuestion → execute the chosen branch.

Step 8b — Substitute placeholders (double-brace {{NAME}}):

Placeholder	Source	Fallback chain
{{PROJECT_NAME}}	package.json name	1) strip @scope/ → 2) basename(cwd) → 3) My App
{{NEXT_VERSION}}	Step 0b	14+ if unknown
{{ORM}}	Step 0c	Drizzle (Better Auth default)

Provider name is pre-resolved by selecting the correct template file (firebase/ vs better-auth/), not via placeholder.

Step 8c — Process conditional blocks <!-- IF key=value -->...<!-- /IF -->:

• oauth=google → keep if Step 1a included Google, else delete (and remove markers).
• email=resend|console|other → keep matching Step 3 choice, delete the rest.

Step 8d — Verify (mandatory): No raw {{ remains. No raw <!-- IF remains. Every env var in .env.example appears in the README env table. At least one link to provider's console (Firebase / Google Cloud / Resend). No orphan intra-doc anchor links. If any check fails → re-run substitution.

CRITICAL CODE RULES — Violating any of these causes runtime crashes

These rules are mandatory. They are extracted from 60 production pitfalls (references/09-common-pitfalls.md) and represent the most common causes of auth failures. Claude MUST follow these rules when generating ANY auth code:

R1 — NEVER instantiate SDK clients at module scope. new Resend(process.env.X) or new Stripe(process.env.X) at the top of a file crashes during build/SSR because env vars aren't available at module evaluation time. Use lazy initialization (singleton getter function) or create instances inside handler functions. Copy assets/config/email.ts for the correct Resend pattern. (#50)

R2 — ALWAYS await session cookie BEFORE redirect. router.push("/dashboard") without await createSessionCookie() first → middleware bounces user back to /login because cookie doesn't exist yet. Firebase: await createSessionCookie(user) then redirect. Better Auth: handled automatically via cookie. (#22)

R3 — Sign-out: clear server cookie FIRST, then client, then redirect. Calling signOut() (client) before DELETE /api/auth/session (server) leaves an orphan server cookie. Order: server delete → client signOut → window.location.href = "/login". (#23)

R4 — NEVER use auth() wrapper in middleware for Better Auth. auth() is Auth.js (NextAuth v5), NOT Better Auth. Better Auth middleware checks request.cookies.get("better-auth.session_token") directly. Using auth() gives "auth is not a function". (#43)

R5 — NEVER decode JWT in middleware for Firebase. Middleware runs on Edge Runtime — no Firebase Admin SDK. Only check cookies.get("__session")?.value existence. Real verification happens in (protected)/layout.tsx via adminAuth.verifySessionCookie(). Base64-decoding without crypto verification gives false security. (#28)

R6 — ALWAYS copy email.ts from assets/config/email.ts template. Do NOT write email helper code from scratch. The template has correct lazy-init, dev fallback (console.log), and production guard. Inline code examples in guides may be simplified — the template is the source of truth.

R7 — useSearchParams() requires <Suspense> wrapper in Next.js 14+ App Router. reset-password.tsx uses useSearchParams() — without Suspense, next build fails. The template already includes it. Do NOT remove the Suspense wrapper. (#47)

R8 — Copy ALL files in the provider checklist. Skipping any file (e.g., auth-server.ts for Firebase, auth-client.ts for Better Auth) causes cascading import errors. Use the numbered checklist in the CRITICAL section above — every item is required.

Full 60 pitfalls: references/09-common-pitfalls.md

Implementation Checklist

• Choose auth provider (use decision framework above)
• Install packages + set environment variables
• Configure auth server/client
• Set up database schema + run migrations
• Mount API routes/handlers
• Add OAuth providers (Google only — GitHub & Apple coming soon)
• Create login/register UI pages
• Add middleware for protected routes
• Test: sign up → verify email → sign in → sign out → reset password
• Test: OAuth sign in → account linking
• Add security headers to next.config.ts (use assets/config/next.config.ts template)
• Add protected layout for server-side session verification (Firebase)
• Set NEXT_PUBLIC_APP_URL for CSRF protection (Firebase)
• Enable rate limiting for production (see 05-firebase-auth-guide.md Security Hardening section)
• Run verify-auth-setup script