adding-authentication

Adding Authentication

Required inputs

Work in the target Product Builder project repository. If the project path is unclear, ask only for the path before changing files.

Require an existing Product Builder-style project that already has D1 and Drizzle configured. If D1 is missing, run the adding-database skill first.

Derive these values from the project or user prompt when possible:

PROJECT_PATH: <absolute path>
D1_BINDING: APP_DB
AUTH_COOKIE_PREFIX: App

Hard rules

• Use pnpm for package installation and project commands.
• Load react-router-patterns before adding or changing React Router routes, loaders, actions, redirects, forms, protected routes, or app-level route files. Any React Router code must follow those patterns.
• Install better-auth, zod@4, @conform-to/react, and @conform-to/zod.
• Generate AUTH_SECRET with openssl rand -base64 32 and write it to .env as AUTH_SECRET=<generated-value>.
• Do not commit real .env secret values. Update .env.example with an AUTH_SECRET= placeholder.
• Use Better Auth with the Drizzle adapter, SQLite provider, and the existing D1 APP_DB binding.
• Keep auth tables in app/db/schema.ts with Better Auth-compatible table aliases in the adapter options.
• Generate the auth migration, then migrate both local and remote D1.
• Keep auth endpoints under app/routes/auth.tsx at route path api/auth/*.
• Add login, signup/register, and logout routes using React Router actions and loaders.
• Preserve existing route, Worker, context, shadcn/ui, and Tailwind patterns.

Gotchas

• Better Auth session cookies use a prefix (App by default). If the cookie prefix in the auth config does not match what the client sends, every session check silently returns null — the user appears logged out with no error.
• Better Auth expects its tables to exist before the server starts. If migrations have not been applied, the auth handler throws a D1 "no such table" error on the first request.
• AUTH_SECRET must be the same between dev and deployed environments. Generating a new secret invalidates all existing sessions.
• The api/auth/* route must be a splat route (route("api/auth/*", "routes/auth.tsx")). Using a non-splat path causes Better Auth sub-endpoints like /api/auth/sign-in/email to 404.

Workflow

1. Verify the target project is a Product Builder Cloudflare Workers, React Router, TypeScript, pnpm, D1, and Drizzle project.
2. Install dependencies and configure secrets using 01-dependencies-and-env.md.
3. Replace or extend the Drizzle schema with the required auth tables using 02-auth-schema-and-migrations.md.
4. Wire Better Auth into React Router context and the Worker using 03-server-integration.md.
5. Load react-router-patterns, then add api/auth/*, login, logout, and signup routes using 04-auth-routes-and-forms.md.
6. Update project documentation using documentation-updates.md with these specifics:
   • Stack addition: Better Auth (email + password).
   • Data model addition: auth entities (users, sessions, accounts, verifications) matching app/db/schema.ts.
   • Convention update: docs/conventions/routes.md — add auth-related route patterns: protected route loader check, login/signup form action with Better Auth API, logout action, safe redirect after auth.
   • README additions: auth setup, AUTH_SECRET, pnpm wrangler secret put AUTH_SECRET for remote deploys, migration commands.
   • AGENTS.md additions: auth instructions (environment variables, migration commands).
7. Run formatting, typecheck, lint, build, and available migration commands. If any command fails, fix the issue and re-run until it passes before committing.
8. Commit the generated and updated files using the repository's Conventional Commits format.

Validation checklist

• better-auth, zod@4, @conform-to/react, and @conform-to/zod are installed.
• .env contains AUTH_SECRET=<secret generated with openssl rand -base64 32>.
• .env.example documents AUTH_SECRET=.
• README.md documents that remote Cloudflare deployments require users to run pnpm wrangler secret put AUTH_SECRET from an authenticated Wrangler session.
• docs/architecture.md includes Better Auth in the Stack section.
• docs/data-model.md includes auth entities (users, sessions, accounts, verifications) matching app/db/schema.ts.
• docs/conventions/routes.md includes auth-related route patterns (protected routes, login/signup actions, logout, safe redirect).
• AGENTS.md documents auth setup, environment variables, and migration commands, and references docs/.
• app/db/schema.ts exports users, sessions, accounts, verifications, their relations, and schema.
• A new Drizzle migration exists under db/migrations.
• Local and remote D1 migrations were applied, or failures are explained.
• app/context.ts exposes auth: ReturnType<typeof betterAuth>.
• workers/app.ts constructs Better Auth with drizzleAdapter.
• app/routes.ts includes api/auth/*, login, logout, and signup.
• react-router-patterns was loaded and followed for auth routes, loaders, actions, redirects, and forms.
• Route loaders and actions access auth with context.get(appContext).
• app/routes/auth.tsx delegates loader and action to auth.handler(request).
• Login and signup use Conform, Zod, Better Auth API errors, and safe redirects.
• Logout signs out through auth.api.signOut.
• pnpm format, pnpm typecheck, pnpm lint, and pnpm build pass after fixes.
• Generated and updated files were committed with a Conventional Commit message.