ai-saas-starter

The free, open-source AI SaaS boilerplate and starter kit for Next.js 16.

Auth, Stripe subscriptions, an append-only credits ledger, and AI image generation — built as an AI-native repo that Claude Code, Cursor, and Codex can extend without breaking the money paths.

Live demo · Deploy guide · Pro version

• This website is the demo — sign up, everything works.
• The code is a free GitHub repo — MIT, clone it.
• You build YOUR product on top — auth and payments are done.

A free, open-source SaaS boilerplate / starter kit for Next.js 16 · React 19 · TypeScript strict · Better Auth · Drizzle + PostgreSQL · Stripe · AI SDK 6 · Tailwind v4 + shadcn/ui · Resend · Vitest + Playwright.

Credits ledger on the dashboard — balance is SUM(amount), enforced	AI image generation — 1 credit per image
Busy state	Plans from one config file
Real Stripe checkout (test mode)	Auth + account settings

AI assistants are good at building product features and bad at the 20% that loses money when improvised: webhook retries, concurrent spends, refund paths, idempotency. This repo ships that 20% finished and tested — an append-only credit ledger whose balance is enforced equal to SUM(amount), Stripe webhooks that verify raw-body signatures and survive replays, a double-spend race test against real Postgres — plus the context files (AGENTS.md, rules, skills, hooks) that keep an agent from quietly unpicking any of it while you vibe-code the product on top.

git clone https://github.com/nikandr-surkov/ai-saas-starter.git my-app
cd my-app
pnpm install
docker compose up -d        # Postgres 17
cp .env.example .env        # fill in BETTER_AUTH_SECRET (openssl rand -base64 32)
pnpm db:migrate
pnpm dev

That boots with graceful degradation: no Stripe keys → billing page shows a setup card; no Resend key → emails no-op with a console warning; no OAuth keys → those buttons hide; AI_MOCK=true → image generation is free and offline. Every variable is documented in .env.example.

Paste this into your coding agent:

Clone https://github.com/nikandr-surkov/ai-saas-starter.git and get it
running: install deps, start Postgres via docker compose, create .env
from the example (generate the secret), migrate, run dev. Then read
AGENTS.md and brief me on the rules you're operating under.

Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI. The repo briefs the agent itself — AGENTS.md, path-scoped rules, skills, hooks.

• Auth — email/password with verification, Google, GitHub, magic links. Sessions live in your Postgres. Settings page with password change, account linking, and cascade-safe account deletion (cancels the Stripe subscription first).

  

• Billing — Stripe Checkout + Customer Portal as server actions, a signature-verified webhook, and one sync function as the only writer of subscription state. Plans, prices, and credit amounts live in src/config/plans.ts and nowhere else.

  

• Credits ledger — append-only credit_transactions with UNIQUE idempotency keys. Grants on invoice.paid (grant_{invoiceId}), top-ups on checkout (topup_{sessionId}), spends as one conditional UPDATE (the race guard), refunds as compensating rows. The database itself refuses negative balances and zero-amount rows.

• AI generation — prompt → rate limit (10/min) → spend 1 credit → AI SDK 6 generateImage → store (Vercel Blob, or ./.generated in dev) → history grid. Provider failure refunds automatically. Swap models via AI_IMAGE_MODEL=provider/model; add providers by implementing one interface (src/lib/ai/provider.ts).

• Design system — "The Ledger, LOUD MODE": tokens and hard rules in DESIGN.md, light and dark, generated illustrations, an interaction grammar with press physics. /styleguide (dev only) shows every primitive in both themes.

This repo assumes an agent will extend it, and briefs the agent accordingly:

With Claude Code: open the repo and the context loads itself; type /add-feature to scaffold the repo way. With Cursor: .cursor/rules/ mirrors the same invariants. Everything defers to AGENTS.md, so there is one source of truth to edit. Agent-assisted contributions are welcome — run the repo's own gates and the code-reviewer agent before opening a PR (see CONTRIBUTING.md).

Server Components by default; Server Actions for mutations; API routes only for the Stripe webhook and the Better Auth handler. Zod validates every boundary — forms, webhook payloads, and env (src/lib/env.ts, the only place process.env is read). Money is integer cents, credits are integers, and two modules own the dangerous writes: src/lib/credits/ is the only code that touches credit tables, and syncStripeDataToDb in src/lib/billing/sync.ts is the only writer of subscription state — webhooks are triggers, never sources of truth.

pnpm test        # Vitest — needs Postgres: docker compose up -d
pnpm test:e2e    # Playwright — boots its own dev server on :3100

94 unit/integration tests: the full ledger behavioral suite against real Postgres (double-spend race, exact-boundary spends, idempotent replays, refunds, key-collision detection, invariant checks, DB CHECK probes), webhook signature verification with real HMAC fixtures, sync derivation, plans-config locks, env validation, email rendering. 12 e2e tests: signup to dashboard, mock generation, the FAIL-refund path, the 0-credit block, open-redirect guards, image-route authorization, billing plan cards from the plans config.

The spend→refund loop is user-visible, not just tested: a failed generation refunds its credit automatically and says so on the tile.

e2e runs against next dev deliberately — AI_MOCK=true is refused in production builds, so a build+start e2e would hit a real provider. The comment in playwright.config.ts explains.

1. Create three test-mode prices (Pro $9/mo, Ultra $29/mo, Top-up $5 one-time) in the Stripe dashboard or via the API, and put the price_... IDs in .env.
2. pnpm stripe:listen (Stripe CLI) — copy the printed whsec_... into .env, restart pnpm dev.
3. Subscribe with card 4242 4242 4242 4242 → the webhook grants the plan's credits, keyed by invoice ID. Resend the event from the Stripe dashboard — the ledger's unique key makes the replay a no-op.
4. Renewals and cancellations can't wait a month: use test clocks to advance time. Portal cancellations set cancel_at (not the legacy boolean) — the sync handles both; don't "simplify" it.

The order matters — follow it top to bottom.

1. Neon — create a project and copy BOTH connection strings: the pooled one (contains -pooler, for the running app) and the direct one (for migrations).

2. Vercel — import the GitHub repo. Don't deploy yet.

3. Blob store — in the Vercel project: Storage → Create → Blob, with Access: Public, and tick "Add a read-write token env var" — the default flow skips it and leaves BLOB_READ_WRITE_TOKEN unset, which silently sends generated images to the (nonexistent) local fallback.

4. Environment variables — everything from .env.example:

   Variable	Value
   DATABASE_URL	the pooled Neon URL (runtime traffic)
   BETTER_AUTH_SECRET	openssl rand -base64 32
   BETTER_AUTH_URL	the exact deployed URL — see step 9
   STRIPE_SECRET_KEY + 3 price IDs	from your Stripe dashboard
   STRIPE_WEBHOOK_SECRET	placeholder for now — replaced in step 7
   AI_GATEWAY_API_KEY, AI_IMAGE_MODEL	AI Gateway; AI_MOCK stays UNSET
   RESEND_API_KEY, EMAIL_FROM	verified Resend domain
   BLOB_READ_WRITE_TOKEN	added by step 3's checkbox

5. Deploy and note the real production domain Vercel assigns — it may suffix the project name (e.g. -six).

6. Migrate once, locally, with the direct URL (the pooler rejects some DDL): DATABASE_URL="<direct Neon URL>" pnpm db:migrate

7. Stripe webhook — create the endpoint for the REAL deployed domain: https://<real-domain>/api/stripe/webhook, events invoice.paid, checkout.session.completed, customer.subscription.updated, customer.subscription.deleted — then copy its whsec_... into the Vercel env, replacing the placeholder.

8. Redeploy — env changes never apply to a running deployment.

9. Pin the domain — set BETTER_AUTH_URL (env) and siteConfig.url (src/config/site.ts) to the exact production URL from step 5, push, and redeploy if either changed.

Every env change requires a redeploy — Vercel bakes env at build time.

Is this production-ready? The billing and ledger core is tested to a standard most products never reach (races, replays, invariants, adversarial webhooks). The legal pages are placeholders and the product on top is yours to build.

Does it work with Claude Code / Cursor? Yes — that's the point. The repo carries its own agent context (AGENTS.md, CLAUDE.md, path-scoped rules, skills, hooks); Cursor reads the mirrored .cursor/rules/. Open the repo and the agent is briefed.

How does the credits system work? Every credit movement is an append-only row in credit_transactions with a unique idempotency key, so webhook replays can't double-grant. Spends are one conditional UPDATE that refuses to go below zero, and the cached balance is enforced equal to SUM(amount) by tests and a DB CHECK.

Can I swap gpt-image for another model? One env string: AI_IMAGE_MODEL=provider/model — no code changes.

Why Better Auth instead of NextAuth/Clerk? Sessions and users live in YOUR Postgres next to the ledger, so account deletion, credit grants, and webhooks are one transaction-safe world. No per-user vendor pricing on a free starter.

Is this a free alternative to ShipFast or Makerkit? It overlaps where every SaaS starter overlaps — auth, Stripe, landing page — but the focus is different: a tested credits ledger, an AI generation loop, and agent context files, free and MIT. The paid kits are broader (teams, i18n, admin); the Pro version covers that ground.

Why is generation mocked by default? So a fresh clone works offline and free. Set AI_GATEWAY_API_KEY and AI_MOCK=false for real images; in mock mode, a prompt containing FAIL demos the refund path.

Can I swap Postgres providers? Anything with a postgres:// URL — Neon, Supabase, RDS, the bundled Docker.

Where do I start extending? Copy specs/TEMPLATE.md, write ten lines, and hand it to your agent with /add-feature.

The free repo is complete — nothing above is crippled. Pro is what comes after product-market fit.

Built by Nikandr Surkov — nikandr.com. If this repo saved you time, star it — stars are how other builders find it.

MIT — see LICENSE.