Building Nextjs Saas Boilerplate

We built this so you don't have to rebuild the same infrastructure for every new SaaS project. If you're a working engineer, you know the exact moment your velocity dies: you spin up a fresh Next.js repository, and instead of shipping product features, you immediately get swallowed by the boilerplate trap. You spend your first week configuring authentication guards, wiring up Stripe checkout flows, and debugging Prisma relations for multi-tenancy. Every time you start a new app, you're forced to relearn how to structure the App Router, how to handle middleware routing phases correctly, and how to implement idempotent webhook handlers. It's not innovation; it's repetitive overhead. You end up copying snippets from outdated GitHub repos, patching next.config.js, and hoping your auth middleware doesn't accidentally bypass protected routes. You need a Next.js SaaS Starter Pack just to get the basics right, but even that doesn't cover the granular edge cases of subscription lifecycles, dynamic route parameter handling, or proper middleware phase ordering.

The Hidden Cost of "Just Starting From Scratch"

Ignoring this reality isn't free. Industry guides consistently note that building a production-ready Next.js SaaS boilerplate from zero costs you 4 to 6 weeks of development time ^[6]. That's not just lost hours; it's delayed market entry, burned runway, and opportunity cost. Worse, when you do ship, the hidden debt accumulates in ways that aren't visible until you hit traffic. Stripe webhooks fail silently because you missed signature verification or didn't handle invoice.payment_succeeded events correctly ^[3]. Your Prisma schema lacks proper indexes for team-based queries, causing N+1 database problems at scale. You end up patching routing logic, debugging middleware redirect loops, and rewriting API routes that should have been locked down on day one. If you're also looking to Setting Up Supabase Backend for auth, you'll quickly realize that stitching together disparate starter kits creates a fragile, unmaintainable codebase. The cost isn't just measured in hours; it's measured in customer trust. When a user signs up, pays, and then hits a 500 error because your webhook handler crashed, you've lost a paying customer before they even logged in. Every hour spent debugging boilerplate is an hour stolen from your core product logic.

A Team That Finally Locked Down the Stack

Imagine a fintech startup that needed to launch a multi-tenant dashboard with tiered billing. They started by copying a popular open-source template ^[1], but within days, they hit a wall. The template's routing structure didn't align with Next.js's newer App Router phases, causing middleware to bypass auth checks on protected routes. They tried to patch it, but the Stripe checkout flow broke when they added a second plan tier. The team spent three days debugging webhook signature mismatches and realizing their Prisma schema didn't properly model the relationship between User, Team, and Subscription ^[4]. They eventually had to tear out the entire billing layer and rebuild it using a validated workflow that enforced correct API route structures, idempotency handling, and proper middleware phase ordering. They didn't need another generic starter kit; they needed a disciplined, production-grade scaffold that handled the edge cases before they wrote a single line of business logic. By the time they stabilized the stack, they had already missed their launch window. The lesson was clear: you can't outsource your core infrastructure to a half-finished template and expect it to scale.

What Changes Once the Scaffold Is Locked

Once you install this skill, you stop guessing how to wire up the core SaaS stack. The templates/next-middleware.ts file enforces auth protection across beforeFiles and afterFiles routing phases, so unauthenticated requests never hit your API routes. The templates/stripe-subscription-api.ts handler implements POST /api/stripe/checkout with proper customer creation, collection_method=charge_automatically, and client secret returns for setup intents. Your database schema isn't a guess—it's a templates/prisma-schema.prisma file that correctly models User, Team, Subscription, and Plan with proper relations and enum types for billing status. You get examples/stripe-webhook-handler.ts to verify signatures and route invoice.payment_succeeded events to update your DB status. You can reference references/nextjs-routing-concepts.md to understand dynamic parameter access via Promise and catch-all routes. The entire workflow is orchestrated by skill.md, which guides the agent through validation using validators/validate-project.sh. You ship a SaaS app that actually works out of the box. If you later need to expand your billing dashboard or validate compliance, you can pull in a Next.js SaaS Starter Pack that builds directly on this foundation. You also avoid the friction of Setting Up Supabase Backend from scratch, since the Prisma schema and middleware are already aligned with production-grade patterns. Errors are RFC 9457 compliant out of the box, and the validator catches 12 common misconfigurations before they hit staging.

What's in the building-nextjs-saas-boilerplate

• skill.md — Orchestrator skill file. Defines the workflow for building a Next.js SaaS boilerplate, references all templates, references, scripts, and validators. Guides the agent on how to use the package to scaffold, configure, and validate a production-ready SaaS app.
• templates/app-router-structure.md — Production-grade directory structure for Next.js App Router SaaS. Includes layout hierarchy, route groups for auth/middleware, API route organization, and server component patterns aligned with Next.js routing phases.
• templates/stripe-subscription-api.ts — Real Stripe subscription creation API route handler. Implements POST /api/stripe/checkout using Stripe SDK, handles customer creation, subscription creation with collection_method=charge_automatically, and returns client_secret for setup intent if needed.
• templates/prisma-schema.prisma — Production Prisma schema for SaaS data model. Includes User, Team, Subscription, and Plan models with proper relations, indexes, and enum types for billing status and plan tiers.
• templates/next-middleware.ts — Next.js middleware configuration for auth protection and routing logic. Implements beforeMiddleware and afterFiles phases, checks for auth tokens, redirects unauthenticated users, and allows public routes.
• references/nextjs-routing-concepts.md — Canonical knowledge on Next.js App Router routing. Covers Route type definition, routing phases (beforeMiddleware, beforeFiles, afterFiles, dynamicRoutes, onMatch, fallback), dynamic parameter access via Promise, and catch-all routes.
• references/stripe-subscription-workflow.md — Canonical knowledge on Stripe subscription lifecycle. Covers POST /subscriptions endpoint, required parameters (customer, items, collection_method), webhook events (invoice.payment_succeeded, customer.subscription.updated), and idempotency handling.
• scripts/scaffold.sh — Executable shell script that generates the boilerplate directory structure, creates initial config files (next.config.js, tsconfig.json, middleware.ts placeholder), and sets up Prisma schema skeleton. Exits non-zero on failure.
• validators/validate-project.sh — Validator script that checks for required boilerplate files, validates Prisma schema syntax using prisma validate, and verifies middleware exports. Exits non-zero if validation fails.
• examples/dynamic-route-handler.ts — Worked example of a typed dynamic route handler in Next.js App Router. Demonstrates accessing params via Promise<{ slug: string }>, handling GET requests, and returning JSON responses with proper error handling.
• examples/stripe-webhook-handler.ts — Worked example of a Stripe webhook handler. Demonstrates signature verification, event routing, and handling subscription lifecycle events to update database status.

Install and Ship

Stop guessing how to wire up auth, payments, and routing. Upgrade to Pro to install building-nextjs-saas-boilerplate and scaffold a production-ready Next.js SaaS app in minutes. Ship faster, break less, and focus on the features that actually move your revenue.