Quickstart

Four commands

git clone https://github.com/ixartz/Next-js-Boilerplate.git my-saas
cd my-saas
npm install --legacy-peer-deps
npm run db:setup && npm run dev

That's it. Open http://localhost:3000 and you'll see:

• A real marketing page (not a "coming soon" placeholder).
• A working sign-in / sign-up flow against a local Postgres (PGlite, no Docker).
• The dashboard with seeded demo data.
• The audit chain, credits ledger, evidence completeness, and webhook replay surfaces all live.

What db:setup actually does

npm run db:setup boots a local PGlite Postgres on port 5433 (file-backed, persists across restarts) and runs every Drizzle migration in migrations/ in order. There is no Docker, no managed Postgres, no remote dependency.

If the boot ever gets weird, just delete local.db/ and re-run.

Why --legacy-peer-deps

The boilerplate ships with Storybook 10 + Chromatic + Playwright 1.56 + React 19. Some of those have peer-dep conflicts with each other that npm 10 refuses to auto-resolve. --legacy-peer-deps is the documented escape hatch and is already used by every CI step.

Required env vars (zero, for local dev)

You can run npm run dev with no .env.local at all. Every external provider (Stripe, Resend, Sentry, PostHog, Arcjet, S3, Anthropic, OpenAI) is optional and degrades gracefully:

• No STRIPE_SECRET_KEY → checkout buttons are visible but won't dispatch.
• No RESEND_API_KEY → emails print to stdout instead of sending.
• No ANTHROPIC_API_KEY / OPENAI_API_KEY → LLM calls throw a clear LlmProviderKeyMissing error pointing at the missing var.
• No SENTRY_DSN → Sentry no-ops.
• No ARCJET_KEY → bot detection middleware short-circuits.

This is intentional. Forks of this boilerplate are expected to remove the providers they don't use and add their own.

See deployment/env-vars for the production list.

Next steps

• Sign in with the seeded dev user (dev@example.com / any password).
• Visit /dashboard — the demo seed includes credits, audit-log rows, webhooks, and a sample subscription.
• Open CLAUDE.md at the repo root — every feature is documented with a rollback plan.