Skip to content

Developing a nest-api

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.

  1. Finish .env. Set SMTP_USER and SMTP_PASSWORD (see SMTP for a local mail catcher) and a real BETTER_AUTH_SECRET (openssl rand -base64 32). Or pull the whole file: yarn secrets.

  2. Start PostgreSQL and Redis:

    Terminal window
    yarn dc:up
    yarn dc:wait # blocks until both accept connections

    With --with temporal, also docker compose up -d temporal (the Temporal UI is then at http://localhost:8233).

  3. Create the schema: yarn db:migrate creates and applies the first migration (it asks for a name).

  4. Seed the superuser: yarn db:seed. Run it once: a second run fails on the existing email.

  5. Run it: yarn start (Nest in watch mode), then open http://localhost:5000/docs and sign in with BASIC_AUTH_USER and BASIC_AUTH_PASS.

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
Terminal window
yarn test # unit tests
yarn test:dc:reinstall && yarn test:e2e # e2e: a separate PostgreSQL and Redis

The 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.

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 in AppModule. Controllers opt into versioning with version: '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 in src/common/types/email.ts, and a method on MailService.
  • A config variable: interface, schema and getVariables in config.service.ts, a line in .env.example, and a note in the docs.

The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:

  • CLAUDE.md at 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 through CustomConfigService), 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.
SkillShips withWhat it does
add-configEvery 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-modelEvery 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-resourceEvery 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-emailmail

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-jobqueue

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-notificationnotifications

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-eventrealtime

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.