chassis — Next.js Starter Template

SHA-256: fd205d9b0f31f0b31cae1b96dd40209e1e182aa300cf72af7a52c6e75b3d7941

2026-10-13T00:20:05.053Z

# 🏎️ Chassis

**A lightweight, decorator-driven Express + TypeScript backend starter. Clone, run, ship.**

**[📖 Documentation](https://dvd90.github.io/chassis/)** · [Getting started](https://dvd90.github.io/chassis/#getting-started) · [create-chassis on npm](https://www.npmjs.com/package/create-chassis)

Chassis gives you NestJS-style controller ergonomics on plain Express 5 — in a handful of small files you can actually read. Zero configuration required: the server boots standalone, and every integration switches on only when you add its environment variable. Scaffold with a preset or pick à la carte — a database (Mongo, Postgres, or SQLite, ORM included), an auth provider (Auth0, Clerk, or built-in local sign-in), an optional Next.js front end, Sentry, an MCP server, and x402 payments — and the CLI ships only what you chose.

```ts
export class UserController extends Routable {
  constructor() {
    super('/users');
  }

  @route('get', '/:id')
  async show(req: Request) {
    const user = await findUser(req.params.id);
    if (!user) throw new AppError(ERROR_CODES.NOT_FOUND, 'User not found');
    return req.resHandler.ok(user);
  }

  @protectedRoute('post', '/', [validate({ body: createUserSchema })])
  async create(req: Request) {
    return req.resHandler.created(await createUser(req.body));
  }
}
```

Export the class from `src/controllers/index.ts` — that's the whole wiring.

## Quick start

```bash
npm create chassis my-api -- --yes                      # zero prompts: Postgres + JWT + Sentry + Docker
npm create chassis my-app -- --preset fullstack --yes   # the same, plus a Next.js front end
npm create chassis my-api                               # interactive — pick a preset
npm create chassis my-api -- --db postgres --auth jwt --mcp   # à la carte
npm create chassis my-api -- --bare                     # nothing — standalone build
```

Or use the template directly:

```bash
git clone https://github.com/dvd90/chassis.git my-api
cd my-api && npm install && npm run dev
```

That's it — no database, no env file, no accounts needed. Open http://localhost:8000/status.

New here? Follow the **[step-by-step getting-started guide](docs/getting-started.md)** — zero to a tested API in ~10 minutes.

## For AI agents

Every path is non-interactive: `--yes` and `--bare` never prompt, and the CLI
skips prompts automatically whenever stdin isn't a TTY. One command produces a
project that already typechecks, lints and tests green.

- **[llms.txt](https://dvd90.github.io/chassis/llms.txt)** — the project, its
  conventions and its docs index, in one fetch
- **[llms-full.txt](https://dvd90.github.io/chassis/llms-full.txt)** — every
  documentation page, concatenated
- **[AGENTS.md](AGENTS.md)** — the conventions to follow when writing code in a
  Chassis project, and the definition of done

Generated projects carry `AGENTS.md`, `CLAUDE.md`, `llms.txt` and an
`add-resource` skill, so whichever agent opens one writes code that matches the
rest of the codebase rather than fighting it.

## Features

- **TypeScript 6 + Express 5** — strict types, async errors caught automatically
- **Decorator routing** — `@route` / `@protectedRoute` on controller methods, controllers auto-mount
- **Consistent responses** — `req.resHandler.ok() / .notFound() / .validation()` with structured logging
- **Request correlation** — every request gets a `callId` (or propagates `x-call-id`), echoed in responses and logs
- **Typed, validated config** — zod-checked environment via `src/config`; the app refuses to boot on bad config
- **Zod input validation** — `validate({ body, query, params })` middleware with structured 400s
- **Pick-your-stack scaffolder** — presets or à la carte: database + ORM (Mongo/Postgres/SQLite), auth (Auth0/Clerk/local), a Next.js front end, Sentry, MCP, x402 — the CLI prunes everything else so `package.json` carries only what you chose
- **Opt-in integrations** — every module enables by env var, never required
- **Payment-gated routes** — `@paidRoute('get', '/report', '$0.01')` via the x402 protocol (opt-in)
- **Optional Next.js front end** — `--web` adds an App Router app and makes the project an npm-workspaces monorepo (`apps/api` + `apps/web`); the auth provider you picked is wired on both sides
- **MCP server** — expose your API to AI agents as MCP tools (`npm run mcp`, opt-in)
- **Health endpoints** — `/healthz` (liveness) and `/readyz` (readiness, checks enabled integrations)
- **Graceful shutdown** — drains connections and closes integrations on SIGTERM/SIGINT
- **Vitest + supertest** — fast tests against the pure app factory, no server or DB needed
- **DB-aware code generator** — `npm run gen user` scaffolds a controller + test wired to your ORM (Drizzle or Mongoose)
- **Production Docker** — multi-stage build, non-root user, plus docker-compose with your database for dev
- **CI + Renovate** — GitHub Actions verify pipeline and automated dependency updates
- **AI-agent ready** — ships `AGENTS.md`, `CLAUDE.md`, `llms.txt`, and an `add-resource` skill so agents write code that matches the conventions (see below)

## AI-agent ready

Most people scaffolding a backend today have an AI agent in the loop. Chassis is built so that agent-written code reads like hand-written code — because the framework gives agents rails and a verifiable finish line:

- **`AGENTS.md` + `CLAUDE.md`** ship in every project — Claude Code, Cursor, Copilot, and Codex pick them up automatically and follow the conventions (thin controllers, `resHandler` responses, `throw AppError`, config in one place).
- **One obvious place for everything** means agent output converges on the same shape a maintainer would write — that's what keeps it readable.
- **`npm run verify`** (strict TypeScript + ESLint + tests) is a deterministic quality gate agents iterate against until green.
- **`.claude/skills/add-resource`** turns "add a books resource" into one consistent, checklisted operation.
- **`llms.txt`** gives doc-fetching tools a compact map of the conventions.

Nothing to install — it's all in the scaffold. See [AGENTS.md](AGENTS.md).

## Scripts

| Command                           | What it does                                |
| --------------------------------- | ------------------------------------------- |
| `npm run dev`                     | Start with hot reload (tsx watch)           |
| `npm test` / `npm run test:watch` | Run the vitest suite                        |
| `npm run verify`                  | Typecheck + lint + test (CI runs this)      |
| `npm run build` / `npm start`     | Compile to `dist/` and run production build |
| `npm run gen <Name>`              | Generate a controller + test                |
| `npm run lint` / `npm run format` | ESLint / Prettier                           |

## Enabling integrations

Copy `.env.example` to `.env`. Each integration turns on when its variables are set — and stays completely dormant otherwise:

| Integration | Enable by setting                 | What you get                                              |
| ----------- | --------------------------------- | --------------------------------------------------------- |
| MongoDB     | `MONGODB_URI`                     | Mongoose connection, readiness check, graceful disconnect |
| Auth0       | `AUTH0_DOMAIN` + `AUTH0_AUDIENCE` | JWT verification on every `@protectedRoute`               |
| Sentry      | `SENTRY_DSN`                      | Automatic error reporting from the central error handler  |

Using a different IdP? Call `setAuthProvider([...yourMiddleware])` at boot and `@protectedRoute` uses it — see `src/core/auth.ts`.

### Sign in without a third party

Local sign-in ships in three variants — emailed link, the classic credential
form, or both. Run `npm create chassis --help` to see the `--auth` values, or
read [Authentication](docs/guides/authentication.md). Whichever you pick, they
share one session layer.

```
POST /auth/magic/request  {email, returnTo?}   → 202, identical for every address
GET  /auth/magic/:token                        → confirm page — consumes nothing
POST /auth/magic/redeem   {token}              → session + redirect
POST /auth/magic/code     {email, code}        → same, from the other device
POST /auth/refresh | /auth/logout | /auth/revoke-all
```

Four things worth knowing about the emailed-link flow:

- **`GET` never spends a token.** Mail security scanners prefetch links, and a
  single-use token burned by a scanner is how this feature usually breaks in
  production. Redemption is a `POST`, on a click.
- **Every email carries a six-digit code too**, so someone who asks on a laptop
  and reads their mail on a phone can still finish on the laptop.
- **The request endpoint will not tell you who has an account** — same body,
  same timing, every address.
- **Refresh tokens rotate on every use**, and replaying a spent one revokes the
  whole session family. Sliding `SESSION_IDLE`, hard `SESSION_ABSOLUTE` cap.

| Variable                                  | Default                 |
| ----------------------------------------- | ----------------------- |
| `JWT_SECRET`                              | _(required)_            |
| `SESSION_IDLE` / `SESSION_ABSOLUTE`       | `30d` / `90d`           |
| `MAGIC_TOKEN_TTL` / `MAGIC_CODE_ATTEMPTS` | `15m` / `5`             |
| `MAGIC_LINK_BASE_URL`                     | `http://localhost:8000` |
| `SMTP_URL`                                | unset → logs the email  |

Chassis binds no email or SMS provider — bind yours through `setMailTransport()`
or `setSmsTransport()`. Proving an address fires one hook, `setOnVerified()`,
and that is the whole extension surface: consent and onboarding are yours.

Guides: [magic link](docs/guides/magic-link.md) ·
[sessions](docs/guides/sessions.md) ·
[transports](docs/guides/transports.md)

## Project structure

```
src/
├── config/          # zod-validated env → typed config + feature flags
├── core/            # the framework: Routable, decorators, responses, errors, validation
├── middleware/      # callId correlation, dev request logging
├── integrations/    # opt-in modules: mongo, auth0, sentry
├── controllers/     # your endpoints — exported classes auto-mount
├── __tests__/       # vitest + supertest
├── app.ts           # pure app factory (no I/O — trivially testable)
└── server.ts        # boot: integrations → listen → graceful shutdown
```

## Documentation

Read them at **[dvd90.github.io/chassis](https://dvd90.github.io/chassis/)** —
searchable, one page. The source lives in [`docs/`](docs/README.md) and the site
is generated from it, so the two can never disagree:

- **[Getting started](docs/getting-started.md)** — step-by-step tutorial
- **Guides** — [building an API](docs/guides/building-an-api.md) · [authentication](docs/guides/authentication.md) · [deployment](docs/guides/deployment.md)
- **Concepts** — [architecture](docs/architecture.md) · [modules & integrations](docs/modules.md)
- **Reference** — [configuration](docs/reference/configuration.md) · [core API](docs/reference/core-api.md) · [CLI & scripts](docs/reference/cli.md)
- **[Maintainers guide](docs/maintainers.md)** — publishing, releases, keeping the template fresh

## Docker

```bash
docker compose up --build     # API + MongoDB
docker build -t my-api .      # production image only
```

## License

[MIT](LICENSE)