NestJS REST backend template
Start here: Documentation home · Nontechnical: evaluate the template · Technical: build and operate
New to this project? Read the decision guide before installing it. This is a customizable foundation, not a complete business application. Commercial-use rights are not granted by default: review the PolyForm Noncommercial license and obtain separate permission if required.
A production-ready starting point for NestJS 12 REST APIs: everything a
project would otherwise rebuild is here, so a new project only writes its own
features. JSON in, JSON out; Swagger UI at /api is the API's only page.
You choose the shape once, with the first-run wizard (pnpm setup: one
organization or many, which optional services and security switches are on);
you add features with a generator (pnpm feature:add) that writes everything
standard, so you write only the business logic; and you deploy without
downtime with Docker Compose (rolling or blue-green) or Docker Swarm.
A pnpm + Turborepo monorepo: the API in apps/api, its typed client in
packages/api-client, a web app on that client in apps/web (React, Vite,
TanStack Router and Query, shadcn/ui and Dice UI from packages/ui), and
room for more frontends in apps/ (monorepo).
What's in it
| Area | What you get | Docs |
|---|
| Setup | pnpm setup: a first-run wizard that asks the deployment shape and the few choices, lets you disable unused modules and writes the env file with generated secrets | configuration |
| Choices | Deployment switches, set once: one tenant or many (TENANCY), IDEMPOTENCY (required or optional), WEBHOOKS, REPORTS, USAGE, REALTIME, AUTH_MFA, API_CLIENTS, IMPERSONATION (off by default); auth policies changed at runtime (auth.requireMfa, auth.passwordMinLength) under the env's ceiling | configuration, settings |
| Features | A generator (pnpm feature:add, the /add-feature skill for Claude Code) writes a feature from one declaration, <item>.record.ts: fields, recycle bin, organizational units, and capabilities (tags, comments, attachments, revisions, PDF, bulk, watch, search, export, custom fields, webhooks for its changes, gapless numbers), approvals and settings, plus API-key access, grants and idempotency; pnpm feature:sync applies a changed declaration later | adding a feature |
| Tenants | Many organizations in one deployment behind PostgreSQL row-level security (or one, with TENANCY=single), the tenant of every request, job, workflow and cron run, operators, independent tenants with strict isolation, break-glass (an operator reading a tenant read only), platform analytics on anonymized aggregates | tenancy |
| Accounts | Password sign-in, sessions and tokens (mobile), passkeys, sign-up (optional), invitations, email verification, forgot/reset/change password, TOTP two-factor with recovery codes, magic links, Google/Microsoft/GitHub, enterprise SSO (SAML 2.0, OpenID Connect per tenant) with SCIM 2.0 provisioning, bot protection (Turnstile), sessions list and sign-out everywhere, data export and account deletion, support impersonation (opt in) |
One example feature, notes, shows business logic on top of the platform:
a publish workflow with an approval, conditions and field-level permissions,
numbers, custom fields, webhooks through the outbox, an incoming webhook,
settings. It is there to read, then to remove (pnpm feature:remove notes;
CI proves the template stands without it): new features start from the
generator (pnpm feature:add), never from a copy.
Start
pnpm install
pnpm setup # first run: a few questions, writes apps/api/.env.development (or the root .env: --target production)
pnpm services:up # PostgreSQL, Redis, Mailpit, Floci (AWS S3 and SES), Gotenberg (PDF)
pnpm dev # the API (http://localhost:3000/api) and the web app (http://localhost:5173)
pnpm db:seed:demo # optional, from a second terminal: demo users and organizational units, and each feature's demo data (passwords printed once)
Open http://localhost:5173 and sign in as the administrator (below) or a
demo member the seed printed (monorepo).
pnpm setup asks what shapes a project (one organization or many, mail,
storage, sign-up, bot protection, the deployment switches), keeps the
rest off, and generates the secrets; without it, copy apps/api/env.development.example to
apps/api/.env.development by hand (configuration,
"First setup"). The first start creates the administrator (ADMIN_EMAIL; the password is
logged once unless ADMIN_PASSWORD is set, which pnpm setup does). Or open
the repository in its devcontainer (.devcontainer/): the same services,
nothing to install; pnpm dev runs the API and the web app there. More in
development.
Start a new project
git clone https://github.com/lamberto15/nestjs-monorepo-template my-app # keeps the history: template updates merge
cd my-app && git remote rename origin template
pnpm install
pnpm feature:remove notes # the example feature: the API's and the web app's (pages, tests, texts)
pnpm db:generate # the migration that drops its table
pnpm feature:add invoices --fields "number:string!unique,total:money,dueOn:date?" --with tags,comments,attachments,pdf
pnpm db:generate && pnpm client:generate
pnpm build # the web's build regenerates its route tree
Then run pnpm setup and rename it (the root package.json name, the @nestjs-monorepo-template/
scope, API_TITLE, API_KEY_PREFIX) and write only the business logic, where
the generated service says so. With Claude Code, /add-feature asks what the
feature needs and runs the generator. GitHub's "Use this template" works too,
but its fresh history makes template updates harder (upgrading).
More in adding a feature.
Deploy
pnpm setup --target production # asks, writes .env (chmod 600) with every secret generated
docker compose up -d --build # the first start; later deploys: one of the three below
By hand instead: cp env.example .env && chmod 600 .env; env.example says
which values are required and how to generate each secret.
Caddy (HTTPS, and the web app's files) → api replicas; worker replicas
for the background work; PostgreSQL and Redis; migrations once per deploy. Later deploys keep serving
while the new version starts (deployment):
| Method | Command | Rollback |
|---|
| Rolling (Compose) | pnpm deploy:rolling | deploy the previous APP_IMAGE |
| Blue-green (Compose) | pnpm deploy:blue-green | pnpm deploy:blue-green rollback, instant |
| Docker Swarm | pnpm deploy:swarm | automatic on a failed health check, or pnpm deploy:swarm rollback |
See deployment for staging, scaling, managed services,
backups and the published images.
Template updates
The template keeps shipping fixes and modules as releases (v* tags, with
notes on their migrations and how to roll back). Start your project with
git clone (keeping the history), keep the template as a remote, and merge
each release tag: upgrading.
git remote add template https://github.com/lamberto15/nestjs-monorepo-template
git fetch template --tags && git merge v1.3.0
Documentation
Getting started
- Development: setup, commands, tests, the demo seed, the typed client, the database, the git workflow
- Configuration:
pnpm setup and every variable
- Architecture: the repository, the groups, the processes, how features plug in
- Monorepo: the root scripts, Turborepo, the web app (running it, its pages, its tests), adding a frontend app
Building features
- Adding a feature: the generator, the
<item>.record.ts declaration, the checklist
- API conventions: versions, errors, lists, filters, credentials, idempotency
- Accounts and authentication: sign-in, tokens, passkeys, two-factor, enterprise SSO and SCIM, API clients, impersonation
- Permissions: roles, conditions, fields, grants, organizational units, audit
- Tenancy: tenants, the row-level security wall, single-tenant deployments
- Languages and time
- Pitfalls: mistakes already made
Platform modules
- Background work: queues, mail, outbox, workflows, cron
- Webhooks and realtime: outgoing and incoming webhooks, the ops API, socket.io, health
- Exports and imports
- Bulk operations: delete, restore or change many records as a 202 job
- Scheduled reports: an export on a schedule, mailed with a link
- PDF documents: templates, languages and right to left, Gotenberg, issued attachments
- Approvals: policies, stages, approver rules, delegation, escalation
- Automation rules: a tenant's own triggers, conditions and actions, simulated before activation
- Notifications: in-app, realtime, mail, webhook, push and SMS; preferences, digests
- Settings and feature flags: runtime values, scopes, rollouts
- Custom fields: fields administrators add at runtime, stored in JSONB
- Computed fields: values derived from a record's fields by a safe, typed expression
Operations and deploys
Releases and the roadmap
- Releases: template releases and their notes, the typed client's versions (Changesets)
- Upgrading: pulling template updates into your project (the merge, conflicts, migrations)
- Roadmap: what gets built next, and the status of what is done
License
PolyForm Noncommercial 1.0.0: free for personal, research, education and other
noncommercial use. Commercial use needs a separate licence from the copyright holder.
