Starter kit for a SaaS on Next.js

What you get

Left to you, because no check can do it: Create a Stripe account, stay in test mode, and create a product with a monthly price: its id goes into STRIPE_PRICE_ID. Pay once with Stripe's test card to watch the real flow. For a real webhook while developing, install the Stripe CLI and run stripe listen --forward-to localhost:3000/api/stripe/webhook; it prints the whsec_ secret for .env. Create a Resend account and verify a sending domain before real users sign up; until then emails land in .outbox/. Choose where the app and its database run in production; switch Stripe to live mode only after a full test-mode run there.

App

Installed along with them: React DOM 19.3.0, Stripe (JavaScript) 23.0.0, Tailwind CSS Turbopack loader 4.3.3, @types/node 22 22.20.5, PGlite 0.5.9, Drizzle Kit 0.31.11, node-postgres (pg) 8.23.1, @types/pg 8.23.1, Resend (Node.js) 6.32.1.

Accounts

Billing

Email

Checks

For your agent

The plan your agent follows

The agent works one step at a time and does not start a step until the previous one meets its "Done when" lines. The full instructions, with code, are in AGENTS.md.

1. Scaffold · done when:
   • npm run build and npm run lint pass on the empty app.
   • The kit files are unchanged, apart from CREDITS.md rows you add and the block next dev appends to AGENTS.md.
2. Accounts · done when:
   • A user can sign up, sign out and sign in again in the browser, and the user row has plan = 'free'.
3. Protected dashboard · done when:
   • npm run build passes and lists /dashboard as partially prerendered.
   • Signed out, /dashboard redirects to /sign-in; signed in, it shows the plan.
4. Billing · done when:
   • Unit tests: a signed checkout.session.completed makes the user paid; the same event twice changes nothing the second time; a bad signature gives 400; customer.subscription.deleted makes the user free again.
5. Email · done when:
   • Signing up in the end-to-end test leaves a welcome email in .outbox/.
6. End-to-end test · done when:
   • npm run test:e2e passes twice in a row on a fresh database.
7. Verify · done when:
   • Every line under Definition of done is true, and anything that could not be verified is named in PROGRESS.md.

Known traps

What test builds and the official docs showed going wrong with these parts. Each one is in the brief, so the agent reads it before it gets there.

• create-next-app 16.4.0 refuses a folder that contains AGENTS.md, CLAUDE.md, .mcp.json, kit.json or README.md ("contains files that could conflict"), and it has no flag to override that. Scaffold into a sibling folder and copy without overwriting. measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• Next 16 renamed middleware.ts to proxy.ts. The old name still works with a deprecation warning; both files together fail the build; a proxy.ts that exports a function named middleware fails with "Proxy is missing expected function export name". Next.js 16 upgrade guide, and measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• Synchronous cookies() and headers() are gone in Next 16: cookies().get fails type checking with "Property 'get' does not exist on type 'Promise<ReadonlyRequestCookies>'". Next.js 16 upgrade guide, and measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• next lint was removed and next build no longer lints; npx next lint now reads "lint" as a project folder. Run eslint. Next.js 16 upgrade guide, and measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• With cacheComponents (on in a fresh create-next-app 16.4.0 project), a page that reads the session outside <Suspense> fails next build with "encountered uncached or runtime data during prerendering". measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• @better-auth/cli is stuck at 1.4.21 and deprecated; the CLI is now the auth package (npx auth@1.7.7 generate). auth migrate refuses the Drizzle adapter: generate the schema, then migrate with Drizzle Kit. Better Auth docs, and measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• getSessionCookie() only checks that a session cookie exists; it does not validate it. Check the session again in the page or route with auth.api.getSession(). Better Auth docs
• Stripe's constructEvent needs the raw body: a parsed object fails with "Webhook payload must be provided as a string or a Buffer", and a re-serialized body with "No signatures found matching the expected signature". In a route handler, read it with await req.text(). Stripe docs, and measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• Stripe may deliver the same event more than once and does not guarantee order: record processed event ids, and never let the handler depend on which event came first. Stripe docs
• new Resend() with an empty or missing key throws "Missing API key" at once, so a client created at import time breaks the build and every test; emails.send() reports failures in its result instead of throwing. measured with resend 6.32.1, Oct 12, 2026
• Drizzle's PostgreSQL getting-started page installs the @rc (1.0 release candidate) versions of drizzle-orm and drizzle-kit. Keep the pinned 0.45.4 and 0.31.11 from the Stack; Better Auth 1.7.7 supports both lines. Drizzle docs and Better Auth's peer dependencies, Oct 12, 2026
• With cacheComponents, up to three visited routes stay in the page, hidden inside React's <Activity>: a Playwright locator such as getByLabel('Email') can match a hidden copy and fail strict mode. getByRole skips hidden elements. measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• create-next-app's .gitignore ignores .env*, which includes .env.example; a clean clone then has no example file. measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026
• Vitest 5 wants @types/node 22 or newer as a peer; create-next-app installs ^20, and npm install vitest on its own then fails with ERESOLVE until @types/node is upgraded. The dev install line in install.txt upgrades both together, so it does not hit this. measured with next 16.4.0, better-auth 1.7.7, drizzle-orm 0.45.4, stripe 23.0.0 and Node 22.22, Oct 12, 2026

Checks on this kit

• Note Next.js 16 changed several APIs that most examples online still use (middleware.ts, synchronous cookies(), next lint). Follow this brief and the docs bundled with the installed version. Source

What happened when an agent built from it

The recipe was given to a fresh coding agent in a clean sandbox, twice. The agent got only the kit files. It had to build the project and write down everything in the brief that was wrong, missing or unclear.

Result of the last build. A Next.js 16 SaaS starter with sign-up, a protected dashboard, Stripe Checkout and webhooks (stripe-mock, signed test events) and a welcome email; 17 unit and 2 browser tests pass against a production build, also in a fresh clone set up from the README alone, with no real account or key. Its findings went back into the recipe, which is now at v0.3. That version has not been built again as a whole.

Checked again on Oct 19, 2026. AgentGid checks every recipe each week, without a model: 17 pinned packages all still exist on their registries, 10 of them have a newer release than the tested pin; 24 links in the brief: all open (1 refused automated requests, which some sites do). npm lines are checked pin by pin, not installed.

Not checked by anyone yet

• A real Stripe account: real Checkout, the customer portal and webhooks through the Stripe CLI
• Real email delivery through Resend
• The Supabase variant (its local stack needs Docker images that could not be downloaded)
• A production host, macOS and Windows

The kit files

Put them in an empty project folder, open your coding agent there and paste the first prompt (Claude Code first asks you to approve the MCP servers in .mcp.json). These are the files for Claude Code with the default answers; the kit builder writes them for Cursor, Codex, Copilot or another agent, and for other choices. Full guide: how to use a kit.

Download all (.zip)

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then do step 1 of the plan and stop. Report back with:
1. the commands you ran,
2. what each "Done when" check showed (a screenshot or the output),
3. anything in AGENTS.md that turned out to be wrong, missing or out of date.

Do not start step 2 until I reply.

Read AGENTS.md from top to bottom before you do anything else. The kit files it lists are already in this folder.

Then work through the plan in order. After each step, run its "Done when" checks yourself and write one line in PROGRESS.md: the step, what you checked, and the result.
You may install the packages and download the files that AGENTS.md lists without asking. Stop and ask me only for what its "Before you start" section says needs a person.
When a check fails, fix the cause and run it again. If it still fails after two real fixes, stop and tell me what you tried.
Keep a list in PROGRESS.md of anything in AGENTS.md that turned out to be wrong, missing or out of date.
When every line of the Definition of done is true, stop and show me how to run it.

# system packages (use your OS package manager)
postgresql

node --version   # must print v22.12 or newer
# scaffold first (Plan, step 1), then:
npm install --save-exact next@16.4.0 react@19.3.0 better-auth@1.7.7 drizzle-orm@0.45.4 react-dom@19.3.0 stripe@23.0.0 pg@8.23.1 resend@6.32.1
npm install -D --save-exact typescript@5.9.3 tailwindcss@4.3.3 vitest@5.0.4 @playwright/test@1.64.0 @tailwindcss/turbopack@4.3.3 @types/node@22.20.5 @electric-sql/pglite@0.5.9 drizzle-kit@0.31.11 @types/pg@8.23.1

Other versions of this kit

Other versions were not test-built as a whole: the kit says which parts differ from the tested one.

Ask for this kit from your agent

Agents connected to the AgentGid MCP server get the same kit without this page: list_recipes(), then plan_project({"recipe": "saas-starter", "answers": {"agent": "cursor"}, "files": true}). Every brief also tells the agent to ask AgentGid before it adds a part that is not listed.

Recipe saas-starter v0.3. Data snapshot Oct 12, 2026: versions, licenses and prices change, so check the linked pages before you ship.

Comments

Other kits