Claude Templates / S-tier · Foundation
Foundation
The Auth & Onboarding Playbook
Supabase auth, the signup → onboarding wizard, and edge-level account gating.
AUTH-ONBOARDING-PLAYBOOK.md · 10 sections · 1,204 words · 10 KB · markdown
By Moe Ameen, founder of BILT · Published · Updated
The Auth & Onboarding Playbook has Claude Code wire Supabase auth into a Next.js 16 app: signup, signin, password reset and the OAuth callback, a database trigger that creates a profile row for every new user, a multi-step onboarding wizard that saves its stage, and account-status enforcement (active, suspended, billing_paused, cancelled) at the proxy.ts edge layer. At about 1,200 words, it is the shortest S-tier file.
Key takeaways
- Builds /signup, /signin, /reset-password, /auth/callback and /onboarding routes.
- A trigger creates a profile on signup so no auth user is left without one.
- proxy.ts gates routes at the edge, including admin routes.
- The file has a separate section on the email-confirmation setting.
Everything between "stranger hits your site" and "activated user inside the product." Covers Supabase auth wiring, the auto-profile trigger that prevents orphaned accounts, a multi-step onboarding wizard, and the proxy-level auth gate that default-denies your API surface.
What does the Auth & Onboarding Playbook build?
It builds the path from visitor to signed-in, onboarded user on Supabase Auth, with edge gating in proxy.ts and account-status checks.
It also wires auth events (signup, signin, email confirmed) to the hooks that enroll users in emails.
When should you use it?
Use it in week 1, right after App Infrastructure. Billing, admin and analytics playbooks all read the profile table it creates.
Skip it if your app uses a different auth provider; the file is written for Supabase only.
What decisions do you make before running it?
Decide which OAuth providers to allow (the file recommends Google only at launch), the main sign-in method, and whether to require email confirmation.
You also need the Supabase URL, anon key and service-role key from a new project.
What's inside
What does the playbook give you?
- //Supabase auth setup with email + OAuth providers
- //The auto-profile database trigger (no orphaned auth.users rows)
- //A multi-step onboarding wizard with resumable step state
- //Account-status gating: trial, active, past_due, cancelled
- //proxy.ts edge auth with an explicit public-route allowlist
When to use it
Week 1, right after infrastructure.
Build these first
Straight from the file
What does the writing look like?
If you keep confirmation disabled, the DB trigger from §4 handles everything. Simpler. Recommended for B2B/SaaS where the cold-email-list signal is the primary conversion event.
Table of contents
Which sections does the file cover?
- 0. Use this spec
- 1. Architecture
- 2. Schema (Supabase)
- 3. proxy.ts (Edge auth)
- 4. Auto-create profile on signup
- 5. Onboarding wizard pattern
- 6. Account status enforcement
- 7. Email confirmation gotcha (read before configuring)
- 8. Common pitfalls
- 9. Kickoff prompt
How do you run it?
Drop AUTH-ONBOARDING-PLAYBOOK.md into your repo, then tell Claude Code: “Read AUTH-ONBOARDING-PLAYBOOK.md and implement it in this codebase.” It's written for an agent to execute end to end. Search the file for angle-bracket placeholders and swap in your own project names, domains, and keys before the first run.
Who is this for, and who should skip it?
Best for
- New Next.js apps on Supabase that need signup and onboarding fast
- Products with a multi-step setup before the first useful screen
- Apps that will later add billing and admin from this library
Not ideal for
- Apps using Auth0, Clerk or another provider
- Enterprise SSO/SAML requirements (not covered)
- Apps with no user accounts
- Builders who won't adapt paths: the file points to a reference app you won't have
What else do people ask?
What is in the Auth & Onboarding Playbook download?
The Auth & Onboarding Playbook is a markdown file of about 1,200 words. It contains SQL for the profiles and workspaces tables with RLS, the handle_new_user trigger, the route lists proxy.ts needs, a pitfalls list, a kickoff prompt and the reference files it was drawn from.
Why use getUser() instead of getSession() in proxy.ts?
The Auth & Onboarding Playbook says to call supabase.auth.getUser() in proxy.ts and never getSession(). Its reasoning: getSession() reads the cookie without checking with the auth server, so a stale or revoked token still resolves.
Why is my new API route blocked after running it?
The Auth & Onboarding Playbook sets proxy.ts to deny every /api/* route by default. A new route stays blocked until you add its prefix to PUBLIC_API_PREFIXES, which the playbook calls its most important hygiene rule.
Where does onboarding progress get saved?
The Auth & Onboarding Playbook saves each step to the user's profile or an onboarding_state table, never to URL params or localStorage, so a closed tab or a new device picks up where the user left off. Any user without profiles.onboarding_completed_at gets redirected from the dashboard back to their current step.
What do the account statuses do?
The Auth & Onboarding Playbook defines four statuses: active, suspended (an overlay on every page and no API access), billing_paused (a soft block with a fix-payment prompt) and cancelled. A cancelled account keeps read-only access for 30 days and is then archived.
How do we know this?
This page is based on the playbook file itself, AUTH-ONBOARDING-PLAYBOOK.md, which Moe Ameen wrote from the Kompozy codebase (called BKE in the file). We read the file on November 4, 2026; the facts here come from it, not from independent testing in other codebases.
More foundation playbooks
App Infrastructure
The mother playbook: the full stack, the topology, and the Week 0 → launch sequence.
Read + download →S-tierStripe Billing
Customer linkage, plan tiers, a webhook handler that survives replays, and checkout.
Read + download →S-tierCredit Metering
A credit ledger, atomic spend RPC, refund-on-failure, and cost analytics that hold up.
Read + download →