The SaaS Starter Stack

NOTE

Use this page as a prompt reference. Every file below is built to be handed straight to an AI. Download it, drop it into Claude, ChatGPT, Cursor, or Lovable, and say "use this as my playbook." The prompts on this page are copy-paste ready.

NOTE

The selection rule behind every pick: when an agent writes 90% of your code, choose the tool the agent is best at, not the tool with the best benchmark. Next.js over SvelteKit is the clearest example: SvelteKit polls at 93% dev satisfaction, but AI coding tools are measurably stronger at React/Next.js. The training-data moat compounds in your favor every single session.

WATCH OUT

Three 2026 pricing changes people still get wrong: Clerk killed its famous 10K-MAU free tier on Feb 5, 2026 (replaced with 50K monthly retained users, actually more generous). Neon cut storage from $1.75 to $0.35/GB-mo after the Databricks acquisition in May 2026 and removed the monthly minimum. Stripe Billing consolidated to a flat 0.7% of billing volume. Any stack advice quoting the old numbers is stale.

PAYOFF

The bottom line at MVP: the only money anyone forces you to spend at 100 users is Vercel Pro at $20/mo, because Hobby is strictly non-commercial and hard-stops on overage. Everything else rides free tiers that are genuinely generous in 2026.

WATCH OUT

Gotcha: agents love sprinkling "use client" everywhere because it makes errors go away. Every one of those turns a server component into shipped JavaScript. Tell the agent (the kickoff prompt does): server components by default, client components only where interactivity requires it.

WATCH OUT

Gotcha: the Hobby plan is non-commercial, and Vercel enforces it. The moment you take money you need Pro, and Hobby hard-stops on usage overages with a 30-day wait to unfreeze. Upgrade before your first paying customer, not after your site goes dark mid-launch.

WATCH OUT

Gotcha: free-tier projects pause after 1 week of inactivity. Fine while building, a self-inflicted outage at launch. Go Pro ($25/mo, includes backups) the day you launch. Second, sharper gotcha: the service-role key bypasses RLS entirely. It belongs in exactly one server-only file, and prefixing it with NEXT_PUBLIC_ is the single most catastrophic typo available in this stack.

WATCH OUT

Gotcha: the webhook is the only truth. If any code path other than your verified webhook handler sets a user's plan, you have a free-Pro exploit: anyone can hit your success URL without paying. Verify signatures against the raw request body, handle events idempotently, and never trust the client's word that money moved.

WATCH OUT

Gotcha: the free tier's 100/day cap is the one that bites, right when a launch spike sends 300 welcome emails in an afternoon. Also: send from a subdomain (mail.yourproduct.com) so your transactional reputation is isolated, and never send marketing through it. Deliverability is a savings account; newsletters from your receipt domain are a withdrawal.

WATCH OUT

Gotcha: session replays, not events, are the first thing that costs money. Set billing limits in the PostHog dashboard on day one so a traffic spike is a happy surprise instead of an invoice.

WATCH OUT

Gotcha: two setup mistakes neuter it. Skip source-map upload and every production error is minified soup. Skip the tunnel route and ad-blockers silently eat a chunk of your client-side error reports. The kickoff prompt wires both.

You are scaffolding a production SaaS from zero in this empty directory. Work through the phases in order. Do not skip ahead. After each phase, run the verification step before moving on, and fix anything that fails.

# Product

- Name: [PRODUCT_NAME]
- Slug: [PRODUCT_SLUG]
- Pitch: [ONE_LINE_PITCH]
- Core entity users create: [CORE_ENTITY]
- Plans: Free ([FREE_PLAN_LIMIT]) and Pro ([PRO_PRICE], unlimited)

# Stack (fixed, do not substitute anything)

- Next.js (latest stable) App Router, TypeScript strict mode, src/ directory, ESLint
- Tailwind CSS + shadcn/ui for all UI. No other component or CSS libraries.
- Supabase: Postgres, Auth, and Storage. @supabase/ssr for cookie-based auth in the App Router.
- Stripe: Checkout for subscription purchase, Customer Portal for management, webhooks for state.
- Resend + react-email for transactional email, sending from [SENDER_DOMAIN].
- PostHog (posthog-js on client, posthog-node on server) for product analytics.
- Sentry (@sentry/nextjs) for error tracking, client and server.
- zod for env validation and all input validation.

# Global rules (these override anything you would normally do)

1. Every database table gets RLS enabled and explicit policies IN THE SAME MIGRATION that creates it. A table without policies is a bug, even if it "works".
2. The Supabase service-role key is used ONLY inside src/lib/supabase/admin.ts, and that module must start with `import "server-only"`. Nothing under any client component may import it.
3. Subscription state is written ONLY by the Stripe webhook handler. No other code path ever sets a user's plan. Client-side "success" pages read state, never write it.
4. Every env var is read through one validated config module (zod schema, parsed at boot). No `process.env.X` scattered through the codebase. Missing required vars must crash the app at startup with the variable name in the error.
5. Amounts are integer cents everywhere. Never floats for money.
6. Every server action and API route validates its input with zod before touching the database.
7. Generate a .env.example listing every variable with placeholder values and a one-line comment each. Never write real secrets to any committed file.
8. Prefer server components; use "use client" only where interactivity requires it.
9. Do not invent extra features, admin panels, or settings beyond what is specified. Small surface, finished, correct.

# Phase 1: Scaffold

Create the Next.js app with TypeScript, Tailwind, ESLint, App Router, src/ dir. Initialize shadcn/ui with the default theme. Install all dependencies for the stack above. Create this structure:

- src/app/(marketing)/page.tsx        landing page
- src/app/(marketing)/pricing/page.tsx
- src/app/(auth)/login/page.tsx
- src/app/(auth)/signup/page.tsx
- src/app/(app)/dashboard/page.tsx    auth-required
- src/app/(app)/settings/page.tsx     profile + billing management
- src/app/api/webhooks/stripe/route.ts
- src/lib/env.ts                      zod-validated env config
- src/lib/supabase/client.ts, server.ts, admin.ts, middleware.ts
- src/lib/stripe.ts
- src/lib/email/ (Resend client + react-email templates)
- src/lib/analytics/ (PostHog client + server helpers)
- supabase/migrations/
- STACK.md placeholder, .env.example, README.md with local setup steps

Verify: `npm run build` succeeds with placeholder env values.

# Phase 2: Database with RLS

Write supabase/migrations/0001_init.sql containing:

1. `profiles` table: id uuid primary key references auth.users on delete cascade, email text, full_name text, created_at timestamptz default now(). Trigger on auth.users insert that auto-creates the profile row.
2. `subscriptions` table: user_id uuid primary key references profiles, stripe_customer_id text unique, stripe_subscription_id text, plan text not null default 'free' check (plan in ('free','pro')), status text, current_period_end timestamptz, updated_at timestamptz.
3. `[CORE_ENTITY]s` table: id uuid default gen_random_uuid() primary key, user_id uuid not null references profiles on delete cascade, [CORE_ENTITY_FIELDS], created_at timestamptz default now().

RLS for all three tables:
- profiles: users can select and update only their own row (auth.uid() = id). No insert policy (trigger handles it), no delete policy.
- subscriptions: users can select only their own row. NO insert/update/delete policies for users at all; only the service role (which bypasses RLS) writes here, from the webhook.
- [CORE_ENTITY]s: users can select/insert/update/delete only rows where user_id = auth.uid(), with the insert policy also enforcing user_id = auth.uid() via WITH CHECK.

Also create a Postgres function `get_user_plan(uid uuid)` (security definer) returning the plan, defaulting to 'free' when no subscription row exists.

Verify: migration applies cleanly with `supabase db reset` on a local instance if available; otherwise lint the SQL and re-read every policy against the rules above.

# Phase 3: Auth

Implement email+password and Google OAuth via Supabase Auth using @supabase/ssr:
- login and signup pages using shadcn form components, zod validation, real error states (wrong password, unconfirmed email, rate limited)
- OAuth callback route at src/app/auth/callback/route.ts exchanging the code for a session
- Next.js middleware that refreshes the session and redirects unauthenticated users hitting (app) routes to /login, and authenticated users hitting /login to /dashboard
- logout server action
- the dashboard page reads the session server-side and greets the user by email

Verify: build passes; walk through the file flow and confirm no client component imports the server or admin Supabase client.

# Phase 4: Payments

- src/lib/stripe.ts: Stripe client pinned to the current API version.
- Pricing page: Free vs Pro ([PRO_PRICE]) cards. Pro CTA hits a server action that creates a Stripe Checkout Session (mode: subscription, price from env STRIPE_PRICE_ID_PRO, client_reference_id = user id, customer_email = user email, success_url /dashboard?upgraded=true, cancel_url /pricing).
- Settings page: shows current plan (from subscriptions via get_user_plan) and a "Manage billing" button that creates a Stripe Customer Portal session.
- Webhook handler at /api/webhooks/stripe:
  - verifies the signature with STRIPE_WEBHOOK_SECRET against the RAW request body (read the raw body, not parsed JSON)
  - handles checkout.session.completed (create/update subscription row: customer id, subscription id, plan 'pro', status, current_period_end), customer.subscription.updated (sync status, plan, period end; downgrade to 'free' when status is not active or trialing), customer.subscription.deleted (set plan 'free', status 'canceled')
  - idempotent: processing the same event twice must not corrupt state (upsert by user_id, and log+skip unknown event types)
  - uses the admin Supabase client (service role), returns 200 fast, wraps handler logic so a thrown error returns 400 and gets captured by Sentry
- Plan gating: a server-side helper requirePlan('pro') plus enforcement of [FREE_PLAN_LIMIT] on the [CORE_ENTITY] create action, returning a typed error the UI turns into an upgrade CTA linking to /pricing.

Verify: build passes. Print for me the exact `stripe listen --forward-to localhost:3000/api/webhooks/stripe` command and the test-mode flow I should click through.

# Phase 5: Transactional email

- Resend client in src/lib/email/resend.ts using RESEND_API_KEY, from address `[PRODUCT_NAME] <hello@[SENDER_DOMAIN]>` via env.
- react-email templates: WelcomeEmail (sent after first login, checked via a welcomed_at column or metadata flag, never sent twice) and UpgradeReceiptEmail (sent from the checkout.session.completed webhook branch).
- Email sends must never break the main flow: wrap in try/catch, report failures to Sentry, continue.

Verify: build passes; confirm both templates render with the react-email preview script added to package.json.

# Phase 6: Analytics + error tracking

- PostHog: provider component in the app layout (respect NEXT_PUBLIC_POSTHOG_KEY absent = no-op), identify users on login with their user id, capture events: signed_up, logged_in, [CORE_ENTITY]_created, checkout_started, upgraded_to_pro, subscription_canceled (last two fired server-side from the webhook via posthog-node with immediate flush).
- Sentry: run the standard @sentry/nextjs setup (client, server, edge configs + instrumentation), DSN from env, no-op when the DSN is absent so local dev works without it, tunnelRoute enabled so ad-blockers do not eat error reports.

Verify: build passes with and without the PostHog/Sentry env vars set.

# Phase 7: The product itself

- Dashboard: list the user's [CORE_ENTITY]s (server component), empty state with a create CTA, create form in a shadcn dialog (server action + zod), delete with confirmation. Free-plan limit enforced server-side with the upgrade CTA from Phase 4.
- Landing page: hero with the pitch "[ONE_LINE_PITCH]", 3 feature bullets derived from the core entity, pricing teaser, footer with links to /pricing, /login, and placeholder /terms and /privacy pages (generate simple placeholder text marked as PLACEHOLDER, DO NOT SHIP AS-IS).
- Clean, minimal, shadcn defaults. Do not invent a brand.

# Phase 8: Final self-check

Run through this list and print PASS/FAIL for each line with the file that proves it:
1. Every table in every migration has RLS enabled and explicit policies.
2. Service-role key appears only in src/lib/supabase/admin.ts, which imports "server-only".
3. No code path outside the webhook writes to subscriptions.
4. Webhook verifies signatures against the raw body and is idempotent.
5. All env access goes through src/lib/env.ts; grep proves no stray process.env.
6. .env.example lists every required variable with placeholders and comments.
7. All money values are integer cents.
8. `npm run build` passes clean.
9. README documents: local setup, Supabase migration command, Stripe CLI webhook testing, and the deploy checklist.

Then print a short "NEXT STEPS (human)" list: creating the Supabase project, Stripe product + price, Resend domain verification, and the Vercel env vars to set. Do not attempt to do these yourself.

NOTE

Why the phases and PASS/FAIL gates matter: a one-paragraph "build me a SaaS" prompt produces a demo. This prompt produces a system, because every dangerous decision is pre-made as a numbered global rule (RLS in the same migration, service-role key in one server-only file, webhook-only subscription writes, integer cents) and the agent has to prove compliance at the end instead of you auditing 4,000 lines by hand.

WATCH OUT

Two things the prompt deliberately does NOT do: it generates placeholder terms/privacy pages marked DO NOT SHIP AS-IS (get real ones before charging money), and it never touches live keys or DNS. Any prompt that claims to handle those for you is lying to you.

PAYOFF

The 80/20 of this list: if you only have 15 minutes, run the live-mode money path and the RLS spot-check. Payments and data isolation are the two failures you cannot apologize your way out of.

Get the next drop

Every new Vault system ships to the list first. Twice a week, free.