# SaaS starter (React + Node.js)

A full-stack SaaS starter kit in TypeScript with a React 19 single-page app built by Vite and an Express 5 API on Node.js, using PostgreSQL, Better Auth, Drizzle ORM, Tailwind CSS and shadcn/ui. It is for developers who want sign-up, teams with roles, onboarding, Stripe subscriptions, an admin page, API keys and a REST API already built, served by one Node.js process.

- Framework: Express (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/react-node-saas-starter
- Updated: 2026-11-21

## Features

- Express 5 serves the API and the built React app on one port, with index.html for client routes so a refresh works
- Better Auth sign-up, sign-in and password reset with database sessions; GitHub and Google once their keys are set
- Owner, admin and member workspace roles defined once in shared/permissions.ts and checked on every API route
- Stripe Checkout, the Customer Portal and a subscription webhook; plans and limits in shared/plans.ts for both sides
- Admin page at /admin with searchable users and workspaces, each workspace's plan and subscription, and a ban button
- REST API at /api/v1/projects with per-workspace keys, stored as a hash and limited to 120 requests a minute per key
- Migrations run under an advisory lock before the server listens; GET /api/health answers 503 if the database is down
- Vitest unit tests, a smoke test against an unreachable database and integration tests that run when DATABASE_URL is set

## 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.22 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 and their links go to the server log
- Optional: GitHub or Google OAuth client ids and secrets for social sign-in

## About

In development npm run dev starts the API on port 8080 with node --watch and Vite on port 5173, which proxies /api to Express; npm run build then compiles the client into dist/client and the server into dist/server for a single process to serve. One origin means session cookies work without CORS, and Helmet adds security headers with a content security policy on top. The first change is usually replacing the Projects example: the table is in server/src/db/schema.ts, the rules in server/src/lib/projects.ts, validation in shared/schemas.ts and the pages in client/src/pages/app/. On Light Cloud the deploy runs npm ci, npm run build and npm start on PORT with DATABASE_URL and a generated AUTH_SECRET set, and each push to your copy redeploys.

## Variables

- `AUTH_SECRET`: generated

## Questions

### Is there a React and Express SaaS starter with Stripe billing?

Yes. This MIT-licensed starter has Stripe Checkout, the Customer Portal and a webhook at /api/auth/stripe/webhook, switched on once STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PRICE_PRO and STRIPE_PRICE_BUSINESS are set. Only the workspace owner can upgrade.

### Why serve the React app and the Express API from one server?

One origin means session cookies work without CORS, and there is one thing to deploy. Vite still runs separately in development and proxies /api to Express.

### How do I add a shadcn/ui component to this template?

Run npx shadcn@4.23.0 add <name> from the project root; components land in client/src/components/ui. Colours, radius and font are tokens at the top of client/src/index.css.

### Can I deploy this SaaS starter on Light Cloud's Free plan?

No. It needs PostgreSQL and the Free plan does not include databases, so it needs a paid plan. Deploying on one creates the database, sets DATABASE_URL and generates AUTH_SECRET.

### Can I deploy this React and Node.js app without Light Cloud?

Yes. There is no Light Cloud code in it: any Node.js 22.22 host with PostgreSQL runs it with npm ci, npm run build and npm start, once DATABASE_URL, AUTH_SECRET and NODE_ENV=production are set.
