# SaaS starter (Next.js)

A Next.js 16 SaaS starter kit in TypeScript with React 19, PostgreSQL, Better Auth, Drizzle ORM, Tailwind CSS and shadcn/ui, for developers who want accounts, teams and billing already built. It includes workspaces with owner, admin and member roles, onboarding, Stripe subscriptions, an admin panel, per-workspace API keys and a REST API.

- Framework: Next.js (JavaScript)
- Category: Starters / SaaS
- Creates: a server app and a PostgreSQL database on the Shared tier (1 GB)
- Plan: Lite or above
- Price: Free
- Author: Light Cloud
- Page: https://templates.light-cloud.com/starters/saas/nextjs-saas-starter
- Updated: 2026-11-21

## Features

- Email and password sign-up, sign-in and password reset, plus GitHub and Google buttons once their keys are set
- Workspaces with owner, admin and member roles, a workspace switcher and invitations by email or a copyable link
- Onboarding stepper to name the workspace, invite teammates and pick a plan; /sign-up?plan=pro carries the choice
- Stripe Checkout, the customer portal and a webhook keep each workspace's plan in sync; plans live in src/lib/plans.ts
- Admin panel at /admin to search users and workspaces, disable a user or sign in as them; the first account is admin
- Per-workspace API keys, stored as a SHA-256 hash, for a REST API at /api/v1/projects that answers 402 at the plan limit
- SQL migrations run on each npm start under an advisory lock; GET /api/health answers 503 if the database is down
- Vitest unit tests, an integration test that signs up two users and drives the API, and npm run smoke for a running app

## What you need

- A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
- To run it locally: Node.js 22.12 or newer, npm, and Docker for a local PostgreSQL
- Optional: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_PRO and STRIPE_PRICE_BUSINESS to take payments; without them billing stays off
- Optional: RESEND_API_KEY and EMAIL_FROM to send email; without them emails are printed to the server log
- Optional: GitHub or Google OAuth client ids and secrets for social sign-in

## About

Every integration is switched on in src/lib/config.ts only when all of its variables are set, so a deploy with just DATABASE_URL and AUTH_SECRET works end to end. Better Auth's organization, admin and Stripe plugins handle workspaces, roles and subscriptions, and src/lib/permissions.ts keeps the app's own role checks in step with them. The first change is usually replacing the Projects example: add a table in src/lib/db/schema.ts, run npm run db:generate and copy the pattern of src/lib/projects.ts and the routes in src/app/api/v1. On Light Cloud the deploy runs npm run build and then npm start on PORT, with DATABASE_URL and a generated AUTH_SECRET set, and every push to your copy redeploys.

## Variables

- `AUTH_SECRET`: generated

## Questions

### Does this Next.js SaaS starter include Stripe billing?

Yes. Stripe Checkout, the customer portal and a webhook at /api/auth/stripe/webhook switch on when STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_PRO and STRIPE_PRICE_BUSINESS are all set. Subscriptions belong to the workspace, and only owners can upgrade.

### Can I run a Next.js SaaS starter without Stripe or an email provider?

Yes. With only DATABASE_URL and AUTH_SECRET, sign-up, teams, projects, the admin panel and the API all work. Everyone stays on the Free plan and emails are printed to the server log.

### How do I change the plans and prices in this SaaS template?

Edit src/lib/plans.ts, which drives the pricing page, the project and member limits and Stripe Checkout. The prices there are for display only; Stripe charges what the price ids say.

### How do I deploy a Next.js app with a PostgreSQL database?

On a paid Light Cloud plan, the Deploy button copies the repo into your GitHub account, creates the database, sets DATABASE_URL and generates AUTH_SECRET. Migrations run when the app starts, and each push to your copy redeploys.

### Can I host this Next.js SaaS starter without Light Cloud?

Yes. It is a standard Next.js app with no Light Cloud code: any Node.js 22.12 host that can reach PostgreSQL runs it with npm ci, npm run build and npm start, once DATABASE_URL and AUTH_SECRET are set.
