Start a safe NestJS API

At a glanceCopy Anchor Link

• Who: Backend developers shipping a first HTTP API with validation, logging, rate limits, and stable error JSON.
• What: End-to-end tutorial: boot with createNestApp, validate DTOs, return prefixed ids, and exercise the documented error shape with curl.
• Use when: When you want one walkthrough that wires nest, core ids, and the global error filter together.
• Avoid when: When you only need a single piece — use the focused needs (Bootstrap a Nest app, Return uniform error bodies) instead.
• See also: Bootstrap a Nest app, Return uniform error bodies, Generate prefixed unique IDs

InstallCopy Anchor Link

pnpm add @zedtech/zedkit-nest

Latest: 0.1.2 (via changesets).

ExampleCopy Anchor Link

import { createNestApp } from "@zedtech/zedkit-nest";
import { newPrefixedId } from "@zedtech/zedkit-core";
const app = await createNestApp({ module: AppModule, envSchema: AppEnv });
await app.listen(3000);
// Walkthrough sources: packages/nest/examples/safe-api (compiled in @zedtech/zedkit-nest tests).

Wraps: @nestjs/platform-fastify, nestjs-pino, @nestjs/throttler, class-validator

PrerequisitesCopy Anchor Link

• Node.js 22+ and pnpm 9+ (same as the repo root engines).
• @zedtech/zedkit-nest and @zedtech/zedkit-core in your app (see Install above).
• A TUTORIAL_TOKEN env var (any non-empty string for local dev).

WalkthroughCopy Anchor Link

The runnable tutorial lives in the monorepo at packages/nest/examples/safe-api/. CI type-checks those files and boots the app in tutorial-safe-api.test.ts.

1. Env — TutorialEnv validates TUTORIAL_TOKEN and optional PORT (tutorial.env.ts).
2. DTO — CreateItemDto uses class-validator so empty names fail before your handler runs (create-item.dto.ts).
3. Ids — ItemsService assigns newPrefixedId("item") from @zedtech/zedkit-core (items.service.ts).
4. Bootstrap — call createNestApp({ module: TutorialModule, envSchema: TutorialEnv, … }) (see tutorial-safe-api.test.ts) with validation, structured logging (auth headers redacted by default), throttling, OpenAPI, and the global ErrorBody filter from Return uniform error bodies.

Final resultCopy Anchor Link

With the app listening on port 3000:

curl -sS -X POST http://127.0.0.1:3000/items \
  -H 'content-type: application/json' \
  -d '{"name":"bolt","quantity":2}'

You should get 201 JSON with an id like item_01J….

Malformed body (empty name):

curl -sS -X POST http://127.0.0.1:3000/items \
  -H 'content-type: application/json' \
  -d '{"name":"","quantity":1}'

Expect 400 with { "code": "invalid_input", "message": "…", "requestId": "…" }. That shape is documented once on the error-bodies need page; this tutorial only exercises it.

TroubleshootingCopy Anchor Link

Boot fails on TUTORIAL_TOKEN — Export a non-empty value: export TUTORIAL_TOKEN=local-dev.

400 but you expected 201 — Check DTO rules: name must be 1–80 chars, quantity must be an integer ≥ 0.

429 after many requests — the tutorial test enables throttling (30 requests per minute). Slow down or raise limits in your own bootstrap options.

Ids fail isPrefixedId — Use the same prefix (item) when validating ids from clients; see Generate prefixed unique IDs.

Next stepsCopy Anchor Link

• Ship request logs without leaking credentials
• Rate limit calls per key when you outgrow global throttling
• Bootstrap a Nest app for every factory option in one place