This boilerplate is built for teams who want a clean split between the customer-facing app and the API from day one. The web layer is Next.js (App Router); the API is a dedicated Hono server with its own process boundary, not a thin wrapper around route handlers. That keeps deploy units, scaling, and ownership obvious as the codebase grows.
Every meaningful contract flows through Zod: request bodies, query params, and responses are validated at runtime, and the same schemas drive an OpenAPI document your frontend and third parties can trust. Shared DTOs and error shapes live in workspace packages so the web app, API, and future workers never drift silently.
Data access goes through Prisma against Postgres, with migrations and a schema you own. Authentication is Supabase-backed—email and password, refreshable sessions, HTTP-only cookies where it matters, and hooks for OAuth and role-aware UI—so you can ship sign-up, sign-in, dashboards, and protected JSON without inventing auth infrastructure on week one.
Monorepo layout
The repo is organized as a pnpm + Turborepo workspace: one Next.js application for marketing and the authenticated product UI, one Hono service for HTTP APIs, and shared packages for database types, validation schemas, and OpenAPI artifacts. Turbo pipelines orchestrate type-checks, tests, and builds so CI stays fast as packages multiply.
That layout means you can version and deploy the API independently from the web app, share code without copy-paste, and add packages later—billing webhooks, a background worker, or an admin CLI—without restructuring the tree.
API design with Hono
Routes are grouped with Hono’s composable routers: public endpoints for health and auth callbacks, authenticated routes for tenant-scoped resources, and consistent middleware for CORS, logging, and error formatting.
Responses follow a small set of JSON envelopes so the Next.js app can branch predictably on success vs validation vs auth errors, and generated OpenAPI clients (or hand-rolled fetch wrappers) stay aligned with what the server actually returns.
Schema-first validation and docs
Zod schemas are the single source of truth. They validate inbound traffic, shape outbound DTOs, and feed OpenAPI generation so documentation is never a stale markdown file on the side.
When the API changes, TypeScript surfaces mismatches in the web app at build time—especially valuable when multiple engineers touch the same feature across stacks.
Database and migrations
Prisma models map to Postgres tables with explicit relations, indexes where you need them for multi-tenant queries, and a migration history you can review in PRs. The API imports a thin data layer so route handlers stay focused on orchestration, not raw SQL.
Auth and sessions
Supabase Auth handles identity primitives while your Hono layer enforces session cookies, refresh flows, and server-side guards on protected routes. The starter wires common paths—sign up, sign in, password reset, and sign out—so you can extend with OAuth providers or organization invites without replacing the foundation.
Role and permission checks are structured so UI gating and API authorization can share the same mental model as you introduce admin vs member vs billing roles.
Who it is for
Founding engineers who want a serious baseline before writing product-specific code.
Agencies spinning up multiple SaaS MVPs where consistent API and auth patterns save review time.
Teams migrating off a single Next.js API folder toward a dedicated service without a big-bang rewrite.
Summary of features
| Feature | What it means for you |
|---|---|
| Split web + API | Clear ownership and deploy story instead of everything living in one Next process. |
| Zod + OpenAPI | Validated I/O and living API docs generated from the same definitions. |
| Prisma + Postgres | Typed queries, migrations, and a database you can grow into multi-tenant workloads. |
| Supabase Auth | Hosted identity with session patterns suited to dashboards and protected APIs. |
| Turborepo + pnpm | Fast incremental builds and strict workspace boundaries between packages. |
The live demo mirrors the structure described above: browse the UI, hit documented endpoints, and use the repo as a template to start billing, teams, or vertical features on top of a stack that already agrees on types, auth, and API shape.