Getting Started
On this page
Dads is a TypeScript backend framework and package suite built around three guarantees: every HTTP route declares an access rule before it can compile, relationship permissions run inside your PostgreSQL transactions, and domain boundaries are enforced in CI.
Choose your starting point
| If you want to... | Start with |
|---|---|
| Build a new TypeScript backend with auth, workspaces, Postgres ReBAC, OpenAPI 3.1, and enforced boundaries wired from day one | Follow the walkthrough below (npm create dads@latest) |
| Add Zanzibar permissions to an existing Postgres app without running a separate authz database or outbox | Permissions in Postgres & SpiceDB |
Replace hand-written SpiceDB .zed files with type-checked TypeScript and generated .zed output |
Adopt One Package at a Time |
Prerequisites
- Node.js 24 and npm
- Docker (used by
npm startto boot local PostgreSQL and the API stack)
1. Create a project
Choose the minimal template for a clean backend without demo features, or the example template for a full runnable app with notes, attachments, exports, and a permissions UI.
Minimal template (clean start):
npm create dads@latest my-app -- --template minimal
cd my-app
Example template (full runnable workbench):
npm create dads@latest my-app
cd my-app
2. Start the local stack
Run npm start from my-app:
npm start
npm start boots PostgreSQL in Docker, applies migrations, starts both API entrypoints (customer and staff), and prints the local URLs.
- Open the browser URL printed by
npm startand select Create an account. - In a second terminal, run
npm run dev:mailto read the local verification link (no SMTP setup required). - Open the verification link, sign in, and create your first workspace.
Useful local commands:
| Command | What it does |
|---|---|
npm run dev:status |
Prints the running URLs and ports |
npm run dev:mail |
Shows local verification and invite emails |
npm run dev:down |
Stops the local Docker stack |
3. Where your code goes
Every Dads app splits code into four areas. npx dad check boundaries enforces these import rules in CI so features stay isolated as your team (or your coding agents) adds routes.
| Path | What lives here | Can import |
|---|---|---|
domains/<name>/ |
Your business features: routes, Zod wire contracts, access rules, database tables, and typed clients. Ships with domains/tenants/ for built-in auth, users, workspaces, and invites. |
Framework packages and libraries/*. Never another domain. |
apps/<api>/app.ts |
Short manifests that pick which domain plugins and background jobs each HTTP server mounts (customer/app.ts for your users, staff/app.ts for internal tools). |
Any domains/*, libraries/*, and assembly/*. |
assembly/ |
Shared server startup, environment config, PostgreSQL pool, composed access model, migrations, and local dev scripts that boot the entrypoints in apps/. |
Any domains/*, apps/*, and libraries/*. |
libraries/ |
Shared runtime types and base entity handles (such as libraries/app-runtime/index.ts) that multiple domains need without importing each other. |
Framework packages only. |
dads.project.json |
The boundary manifest read by npx dad check boundaries to verify every import rule. |
Config file. |
Why is
assembly/separate fromapps/?apps/customer/app.tsandapps/staff/app.tsare short manifests that choose which routes exist on each server.assembly/is the shared host that boots either entrypoint using the same PostgreSQL pool, auth setup, health checks, and migrations.
4. Add your first feature
Generate a relationship-guarded domain and mount it on the customer API:
npx dad add resource products --api customer
Pass --dry-run first to preview the generated files before writing them.
This creates domains/products/ with its own contract, access rule, routes, and database table, registers the plugin in apps/customer/app.ts, and leaves apps/staff/app.ts untouched.
5. Verify boundaries, types, and tests
Run the full verification gate from your project root:
npm run verify
npm run verify runs four checks in order:
dad check boundariesconfirms no domain imports another domain's internals.- TypeScript type-checking verifies every route declares an
accessrule and matching request/response schemas. - The web client builds against your updated contracts.
- Vitest runs your unit and integration tests (with Docker running).
You can also run npx dad doctor --gate to check repo-wide rules such as zero any, zero unsafe casts, and denial test coverage.
Next steps
- Model and enforce permissions: Permissions in Postgres & SpiceDB
- Define endpoints, Zod schemas, and clients: Routes, Contracts & Clients
- Split customer/staff APIs and enforce CI gates: Multi-API Composition & CI Gates
- Use packages in an existing codebase: Adopt One Package at a Time
- Why Dads enforces these rules:
DAD.mdandWho let Gary back in?