Developing a nest-api
After generating
Section titled “After generating”Generation already copied .env.example to .env (and .env.test), ran
yarn install, formatted the code, generated the Prisma client and made the
first commit.
-
Finish
.env. SetSMTP_USERandSMTP_PASSWORD(see SMTP for a local mail catcher) and a realBETTER_AUTH_SECRET(openssl rand -base64 32). Or pull the whole file:yarn secrets. -
Start PostgreSQL and Redis:
Terminal window yarn dc:upyarn dc:wait # blocks until both accept connectionsWith
--with temporal, alsodocker compose up -d temporal(the Temporal UI is then at http://localhost:8233). -
Create the schema:
yarn db:migratecreates and applies the first migration (it asks for a name). -
Seed the superuser:
yarn db:seed. Run it once: a second run fails on the existing email. -
Run it:
yarn start(Nest in watch mode), then openhttp://localhost:5000/docsand sign in withBASIC_AUTH_USERandBASIC_AUTH_PASS.
Scripts
Section titled “Scripts”| Script | Does |
|---|---|
yarn start |
Nest in watch mode (--no-watch, --debug) |
yarn build, yarn start:prod |
Compile to dist/, run it |
yarn lint, yarn format |
ESLint (with fixes), Prettier |
yarn db:generate |
Generate the Prisma client |
yarn db:migrate, yarn db:migrate:create |
Create and apply migrations (:create writes without applying) |
yarn db:migrate:prod |
Apply migrations in production (prisma migrate deploy) |
yarn db:push |
Push the schema without a migration (prototyping) |
yarn db:seed, yarn db:reset, yarn db:studio |
Seed; reset the dev database; Prisma Studio on port 5025 |
yarn dc:up, dc:wait, dc:down, dc:recreate |
The development PostgreSQL and Redis |
yarn dc:reinstall |
Recreate, generate, migrate and seed in one go |
yarn email:dev |
Preview the email templates on port 5003 |
yarn secrets [-e env] |
Pull .env files from Infisical |
yarn test # unit testsyarn test:dc:reinstall && yarn test:e2e # e2e: a separate PostgreSQL and RedisThe e2e suite boots the real AppModule against the test stack (PostgreSQL
5499, Redis 6399, from compose.test.yml), with mail, media and feature flags
replaced by fakes. Specs run strictly one at a time: they share one database,
truncated and reseeded between specs. test/factory has the fixtures and a
signIn() helper that returns a session cookie.
Adding things
Section titled “Adding things”The project’s own task skills carry the full steps for each of these.
- A module:
yarn gen module <name>(Nest schematics), then register it inAppModule. Controllers opt into versioning withversion: '1'. - A route that’s public:
@AllowAnonymous(). Everything else requires a session. - Validation: pass a Zod schema,
@Body({ schema }), and declare the response with@Returns(schema). - A queue:
QueueModule.register('<name>')in the module that produces to it; the dashboard picks it up. - An email: a React Email template in
emails/, a job name insrc/common/types/email.ts, and a method onMailService. - A config variable: interface, schema and
getVariablesinconfig.service.ts, a line in.env.example, and a note in the docs.
Building with Claude Code
Section titled “Building with Claude Code”The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:
CLAUDE.mdat the root: the API’s commands, layout and the rules the template relies on (a session on every route, Zod in and out, 404 rather than 403, config only throughCustomConfigService), with a short note for each feature the project has. Claude Code loads it in every session in the project.- Task skills in
.claude/skills/<name>/SKILL.md: step-by-step recipes that point at the template’s own example code. Ask for the task in plain words (“add an endpoint for invoices”) and the matching skill loads.
| Skill | Ships with | What it does |
|---|---|---|
add-config | Every project | Add an environment variable to this API end to end — validated by the Zod config schema, mapped into the typed config, exposed through CustomConfigService, and documented in .env.example. |
add-model | Every project | Add or change a Prisma model in this API — the schema file, relations, enums, the migration, seed data — following the template's naming conventions. |
add-resource | Every project | Add a resource to this API — a Nest module with its controller, service, Zod DTOs and response entities, permission checks and tests — following the users module. |
add-email | mail | Add a transactional email to this API — the job type, its data, a React Email template, the render step in the mail processor, the MailService method and its test double. |
add-job | queue | Add background work to this API with BullMQ — register a queue, produce jobs with retries, and consume them in a processor here or in a separate worker. |
add-notification | notifications | Add a new kind of in-app notification to this API — the NotificationType, its data shape, and dispatching it from the action that causes it. |
add-realtime-event | realtime | Add a Socket.IO event to this API — pushing a change to connected clients (a user, a room, a channel, everyone) or handling a message from them, with the right rooms and permissions. |
A skill that belongs to a feature arrives with it: adding the feature later
with stack add brings its skill and its
CLAUDE.md sections too. Both are yours to edit as the project grows its own
conventions. See Building with Claude Code for
the whole workflow, from a design to a backlog.