@pauldvlp/vp-react-ts-nestjs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pauldvlp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pauldvlp/vp-templates/main/assets/cover.webp" alt="@pauldvlp/vp-templates" width="100%" />
+</p>
+
+# @pauldvlp/vp-react-ts-nestjs
+
+A [Vite+](https://viteplus.dev) **monorepo generator** that scaffolds a full-stack workspace where the
+front-end and the back-end share one toolchain:
+
+- `apps/web` — a minimal React + Vite+ app that proxies `/api` to the server (no CORS)
+- `apps/api` — a NestJS api conformed to Vite+ (no Webpack, no `nest` CLI)
+- `packages/contracts` — shared **Zod** schemas + inferred types, the single source of truth for both ends
+
+The api rides Vite+'s native **Oxc** transform, which emits `emitDecoratorMetadata` from `tsconfig.json`
+— so Nest's dependency injection works with **no transform plugin**. Dev runs on `vite-node --watch`,
+the production build is a Vite SSR bundle (`dist/main.js`), and a single `vp check` / `vp test` /
+`vp run -r build` covers the whole workspace.
+
+It's a [Bingo](https://create.bingo) template, so options can be passed on the `vp create` command line
+(anything after `--`).
+
+## Usage
+
+Published under the [`@pauldvlp/create`](../create) manifest:
+
+```bash
+# Interactive (prompts for anything you don't pass)
+vp create @pauldvlp:vp-react-ts-nestjs
+
+# Non-interactive, fully specified
+vp create @pauldvlp:vp-react-ts-nestjs -- \
+  --name my-app --scope @acme --apiPort 3000 --webPort 5173
+```
+
+> Only **string** options parse reliably as `vp create -- --flag value`. **Boolean** options
+> (`--swagger`, `--serveWeb`, `--docker`, `--install`) are best left to the interactive prompt — Bingo's
+> CLI does not accept `--no-x` / `--x=false` cleanly. Omit them and answer the prompt.
+
+## Options
+
+| Option       | Type / values | Default   | Notes                                                                                          |
+| ------------ | ------------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `--name`     | string        | `my-app`  | Root project / package name.                                                                   |
+| `--scope`    | string        | `@<name>` | npm scope for workspace packages → `@scope/web`, `@scope/api`, `@scope/contracts`. Defaults to the project name prefixed with `@` (e.g. `--name acme` → `@acme`); falls back to `@app`. |
+| `--apiPort`  | string        | `3000`    | Port the NestJS api listens on (substituted into the env default + the web proxy).             |
+| `--webPort`  | string        | `5173`    | Port the web dev server listens on.                                                            |
+| `--swagger`  | boolean       | `false`   | Expose Swagger UI at `/docs` and the OpenAPI JSON at `/docs.json` (adds `@nestjs/swagger`).     |
+| `--serveWeb` | boolean       | `false`   | Have the api serve the built web app for a single deployable (adds `@nestjs/serve-static`).     |
+| `--docker`   | boolean       | `false`   | Emit a multi-stage `apps/api/Dockerfile` (+ root `.dockerignore`).                              |
+| `--install`  | boolean       | `true`    | Run `pnpm install` after scaffolding. `false` = files only.                                     |
+
+## What it scaffolds
+
+`produce()` reads the static monorepo skeleton under `template/`, rewriting the `@app` scope, project
+name and ports, then conditionally wires the optional features via marker comments:
+
+- **`--swagger`** swaps the `// __SWAGGER_*__` markers in `apps/api/src/main.ts` for a `DocumentBuilder` +
+  `SwaggerModule.setup('docs', …, { jsonDocumentUrl: 'docs.json' })`; otherwise the markers are stripped.
+- **`--serveWeb`** swaps the `// __SERVEWEB_*__` markers in `apps/api/src/app.module.ts` for a
+  `ServeStaticModule.forRoot` pointing at `apps/web/dist` (excluding `/api/*`); otherwise stripped.
+- **`--docker`** keeps `apps/api/Dockerfile` + the root `.dockerignore`; otherwise both are dropped.
+
+The optional Nest deps (`@nestjs/swagger`, `@nestjs/serve-static`) are added to `apps/api/package.json`
+only when their flag is on, and the README's `<!-- SWAGGER/SERVEWEB/DOCKER -->` doc blocks are kept or
+dropped to match. With `--install`, `pnpm install` runs as a post-scaffold step.
+
+## Develop the generator
+
+```bash
+pnpm install
+node bin/index.ts --help            # list options
+node bin/index.ts --directory /tmp/demo --name demo --scope @demo --apiPort 3000 --webPort 5173
+```

package/dist/index.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+// bin/index.ts
+import { runTemplateCLI } from "bingo";
+
+// src/template.ts
+import path2 from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../template-kit/src/index.ts
+import fs from "node:fs";
+import path from "node:path";
+var RENAME = {
+  _gitignore: ".gitignore",
+  _dockerignore: ".dockerignore",
+  "_env.example": ".env.example"
+};
+function toScope(name) {
+  const n = name.trim();
+  return n.startsWith("@") ? n : `@${n}`;
+}
+function readTree(dir, transform, base = dir) {
+  const out = {};
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    const name = RENAME[entry.name] ?? entry.name;
+    if (entry.isDirectory()) {
+      out[name] = readTree(abs, transform, base);
+    } else {
+      const rel = path.relative(base, abs);
+      out[name] = transform(rel, fs.readFileSync(abs, "utf8"));
+    }
+  }
+  return out;
+}
+function patchJson(tree, relPath, mutate) {
+  const parts = relPath.split("/");
+  let node = tree;
+  for (let i = 0; i < parts.length - 1; i++) node = node[parts[i]];
+  const key = parts[parts.length - 1];
+  const json = JSON.parse(node[key]);
+  mutate(json);
+  node[key] = `${JSON.stringify(json, null, 2)}
+`;
+}
+
+// src/template.ts
+import { createTemplate } from "bingo";
+import { z } from "zod";
+
+// package.json
+var package_default = {
+  name: "@pauldvlp/vp-react-ts-nestjs",
+  version: "0.1.0",
+  description: "Vite+ monorepo template: a React web app + a NestJS api (conformed to the Vite+ toolchain) sharing Zod contracts.",
+  author: "pauldvlp (https://github.com/pauldvlp/vp-templates)",
+  license: "MIT",
+  homepage: "https://github.com/pauldvlp/vp-templates",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/pauldvlp/vp-templates.git",
+    directory: "packages/vp-react-ts-nestjs"
+  },
+  bugs: "https://github.com/pauldvlp/vp-templates/issues",
+  keywords: [
+    "vite-plus-generator",
+    "vite-plus",
+    "nestjs",
+    "react",
+    "template"
+  ],
+  bin: "./dist/index.js",
+  type: "module",
+  files: [
+    "dist",
+    "template"
+  ],
+  scripts: {
+    build: "esbuild bin/index.ts --bundle --outfile=dist/index.js --format=esm --platform=node --target=node22 --packages=external",
+    dev: "node bin/index.ts",
+    prepack: "pnpm run build"
+  },
+  dependencies: {
+    bingo: "^0.9.3",
+    zod: "^3.25.76"
+  },
+  devDependencies: {
+    "@pauldvlp/template-kit": "workspace:*",
+    "@types/node": "^24",
+    esbuild: "^0.25.0",
+    typescript: "^5"
+  },
+  engines: {
+    node: ">=22.18.0"
+  }
+};
+
+// src/template.ts
+var TEMPLATE_DIR = path2.join(path2.dirname(fileURLToPath(import.meta.url)), "..", "template");
+var MAIN_TS = path2.join("apps", "api", "src", "main.ts");
+var SWAGGER_IMPORT = "import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'";
+var APP_MODULE = path2.join("apps", "api", "src", "app.module.ts");
+var SERVEWEB_MODULE = [
+  "    ServeStaticModule.forRoot({",
+  "      // Serve the built web app. `import.meta.dirname` resolves the same for src/main.ts (dev) and",
+  "      // dist/main.js (prod) \u2014 both sit two levels under apps/api, so ../../web/dist is apps/web/dist.",
+  "      rootPath: join(import.meta.dirname, '..', '..', 'web', 'dist'),",
+  "      exclude: ['/api/*path']",
+  "    }),"
+].join("\n");
+function applyDocBlock(text, tag, keep) {
+  return keep ? text.replace(new RegExp(`^<!-- ${tag}:(START|END) -->\\n`, "gm"), "") : text.replace(new RegExp(`<!-- ${tag}:START -->\\n[\\s\\S]*?<!-- ${tag}:END -->\\n`, "g"), "");
+}
+var template_default = createTemplate({
+  about: {
+    name: package_default.name,
+    description: package_default.description
+  },
+  options: {
+    name: z.string().describe("Root project / package name").default("my-app"),
+    scope: z.string().describe("npm scope for workspace packages, e.g. @acme (defaults to @<name>)"),
+    // Ports are strings, not z.number(): Bingo's clack prompt renders an option's default as a text
+    // placeholder and calls `.slice` on it, which throws for non-string defaults. They're only ever
+    // substituted into config files as text anyway.
+    apiPort: z.string().describe("Port the NestJS api listens on").default("3000"),
+    webPort: z.string().describe("Port the web dev server listens on").default("5173"),
+    swagger: z.boolean().describe("Expose Swagger UI at /docs on the api").default(false),
+    serveWeb: z.boolean().describe("Have the api serve the built web app (single deployable)").default(false),
+    docker: z.boolean().describe("Add a multi-stage Dockerfile for the api").default(false),
+    install: z.boolean().describe("Install deps after scaffolding").default(true)
+  },
+  // Lazily default the package scope to `@<name>` (prefixing `@` unless the name already has one),
+  // so it tracks the project name instead of a fixed value. Falls back to `@app` when no name is set.
+  prepare({ options }) {
+    return {
+      scope: () => options.name ? toScope(options.name) : "@app"
+    };
+  },
+  async produce({ options }) {
+    const scope = toScope(options.scope || options.name || "app");
+    const swaggerSetup = [
+      `const swaggerConfig = new DocumentBuilder().setTitle('${options.name} API').setVersion('1.0').build()`,
+      `SwaggerModule.setup('docs', app, SwaggerModule.createDocument(app, swaggerConfig), { jsonDocumentUrl: 'docs.json' })`
+    ].join("\n  ");
+    const files = readTree(TEMPLATE_DIR, (rel, content) => {
+      let out = content.split("@app").join(scope).split("__PROJECT_NAME__").join(options.name).split("__API_PORT__").join(options.apiPort).split("__WEB_PORT__").join(options.webPort);
+      if (rel === MAIN_TS) {
+        out = options.swagger ? out.replace("// __SWAGGER_IMPORT__", SWAGGER_IMPORT).replace("// __SWAGGER_SETUP__", swaggerSetup) : out.replace(/^[ \t]*\/\/ __SWAGGER_(IMPORT|SETUP)__\n/gm, "");
+      }
+      if (rel === APP_MODULE) {
+        out = options.serveWeb ? out.replace("// __SERVEWEB_PATH_IMPORT__", "import { join } from 'node:path'\n").replace("// __SERVEWEB_MODULE_IMPORT__", "import { ServeStaticModule } from '@nestjs/serve-static'").replace("    // __SERVEWEB_MODULE__", SERVEWEB_MODULE) : out.replace(/^[ \t]*\/\/ __SERVEWEB_[A-Z_]+__\n/gm, "");
+      }
+      if (rel === "README.md") {
+        out = applyDocBlock(out, "SWAGGER", options.swagger);
+        out = applyDocBlock(out, "SERVEWEB", options.serveWeb);
+        out = applyDocBlock(out, "DOCKER", options.docker);
+      }
+      return out;
+    });
+    if (options.swagger || options.serveWeb) {
+      patchJson(files, "apps/api/package.json", (pkg) => {
+        const deps = { ...pkg.dependencies };
+        if (options.swagger) deps["@nestjs/swagger"] = "^11";
+        if (options.serveWeb) deps["@nestjs/serve-static"] = "^5";
+        pkg.dependencies = Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)));
+      });
+    }
+    if (!options.docker) {
+      delete files[".dockerignore"];
+      delete files.apps.api["Dockerfile"];
+    }
+    const scripts = options.install ? [{ commands: ["pnpm install --silent"], phase: 0 }] : [];
+    return {
+      files,
+      scripts,
+      suggestions: [
+        `cd into the project and run \`vp run -r dev\` to start web + api together.`,
+        `The web app proxies \`/api\` to the NestJS server on port ${options.apiPort}.`,
+        ...options.swagger ? [`Swagger UI: http://localhost:${options.apiPort}/docs (OpenAPI JSON at /docs.json).`] : [],
+        ...options.serveWeb ? [`--serveWeb is on: after \`vp run -r build\`, \`node apps/api/dist/main.js\` serves the web app from the api.`] : [],
+        options.install ? `Run \`vp check\` to lint, format and type-check the whole workspace.` : `Skipped install. Run \`vp install\`, then \`vp run -r dev\`.`
+      ]
+    };
+  }
+});
+
+// bin/index.ts
+process.exitCode = await runTemplateCLI(template_default);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@pauldvlp/vp-react-ts-nestjs",
+  "version": "0.1.0",
+  "description": "Vite+ monorepo template: a React web app + a NestJS api (conformed to the Vite+ toolchain) sharing Zod contracts.",
+  "author": "pauldvlp (https://github.com/pauldvlp/vp-templates)",
+  "license": "MIT",
+  "homepage": "https://github.com/pauldvlp/vp-templates",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pauldvlp/vp-templates.git",
+    "directory": "packages/vp-react-ts-nestjs"
+  },
+  "bugs": "https://github.com/pauldvlp/vp-templates/issues",
+  "keywords": [
+    "vite-plus-generator",
+    "vite-plus",
+    "nestjs",
+    "react",
+    "template"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "template"
+  ],
+  "dependencies": {
+    "bingo": "^0.9.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "esbuild": "^0.25.0",
+    "typescript": "^5",
+    "@pauldvlp/template-kit": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "esbuild bin/index.ts --bundle --outfile=dist/index.js --format=esm --platform=node --target=node22 --packages=external",
+    "dev": "node bin/index.ts"
+  },
+  "bin": {
+    "vp-react-ts-nestjs": "./dist/index.js"
+  }
+}

package/template/README.md

@@ -0,0 +1,122 @@
+# __PROJECT_NAME__
+
+Monorepo full-stack basado en [Vite+](https://viteplus.dev): **una app web (React)** + un **api (NestJS)** que comparten **contratos Zod**.
+
+```
+.
+├── apps/
+│   ├── web        # @app/web — React + Vite+, proxea /api al backend
+│   └── api        # @app/api — NestJS, conformado a la toolchain de Vite+
+└── packages/
+    └── contracts  # @app/contracts — schemas Zod + tipos compartidos (única fuente de verdad)
+```
+
+## Requisitos
+
+- Node `>=22.18.0`
+- pnpm `11.9.0` (se descarga solo vía `devEngines`)
+- CLI `vp` (Vite+) instalado globalmente
+
+## Empezar
+
+```bash
+vp install          # si aún no se instaló al crear el proyecto
+vp run -r dev       # levanta web + api juntos
+```
+
+- Web: <http://localhost:__WEB_PORT__>
+- API: <http://localhost:__API_PORT__/api> (p.ej. `/api/health`, `/api/items`)
+
+El front llama a `/api/*` y Vite+ lo **proxea** al api en dev (mismo origen, sin CORS).
+
+## Scripts (raíz)
+
+| Script            | Qué hace                                          |
+| ----------------- | ------------------------------------------------- |
+| `vp run -r dev`   | Levanta web + api a la vez                        |
+| `vp check`        | Formatea, lintea y type-checkea todo el workspace |
+| `vp run -r build` | Buildea todos los paquetes                        |
+| `vp test`         | Corre los tests (vite-plus/test) de todo el workspace |
+| `pnpm ready`      | `vp check` + build (pensado para CI)              |
+
+## Cómo está cableado el `api` (NestJS sobre Vite+)
+
+NestJS necesita `emitDecoratorMetadata` para su inyección de dependencias. El transform **Oxc** de
+vite-plus lo emite de forma nativa (a partir de `experimentalDecorators` + `emitDecoratorMetadata`
+en `tsconfig.json`), así que el `api` es un paquete vite-plus normal, sin plugins de transform:
+
+- **`vp run @app/api#dev`** → `vite-node --watch src/main.ts` (reinicio limpio en cada cambio: el
+  bloque `import.meta.hot.dispose` en `main.ts` cierra el server antes de re-ejecutar).
+- **`vp build`** → build **SSR** de Vite que externaliza `node_modules` y emite `dist/main.js`
+  (arráncalo con `node dist/main.js` o `vp run @app/api#start`).
+- **`vp check` / `vp test`** → incluyen el `api` automáticamente; los specs (`*.spec.ts`) corren por
+  el mismo pipeline, así que la DI de Nest funciona en los tests (ver `items.service.spec.ts`).
+
+## Contratos compartidos (`@app/contracts`)
+
+Los schemas Zod viven en `packages/contracts` y se importan desde ambos lados:
+
+- El **api** valida los bodies con un `ZodValidationPipe` propio y mínimo (`apps/api/src/common`).
+- La **web** tipa sus `fetch` con los tipos inferidos (`Item`, `CreateItem`).
+
+## Configuración y logs
+
+- **Env**: `apps/api/src/config/env.ts` valida `process.env` con Zod al arrancar (falla rápido).
+  Copia `apps/api/.env.example` a `.env`.
+- **Logs**: [`nestjs-pino`](https://github.com/iamolegga/nestjs-pino). En dev se imprimen legibles
+  (vía `pino-pretty`, una línea) en la misma terminal que la web; en producción salen como JSON.
+
+<!-- SWAGGER:START -->
+## Swagger
+
+La documentación interactiva (Swagger UI) se sirve en <http://localhost:__API_PORT__/docs> y el
+documento OpenAPI en crudo en `/docs.json`. Con el api levantado (`vp run -r dev`), compruébalo:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" http://localhost:__API_PORT__/docs       # 200
+curl -s http://localhost:__API_PORT__/docs.json | head -c 200                     # JSON OpenAPI
+```
+
+La configuración vive en `apps/api/src/main.ts` (`DocumentBuilder` + `SwaggerModule.setup`). Para
+que un endpoint aparezca documentado con su esquema, anótalo con los decoradores de `@nestjs/swagger`
+(`@ApiTags`, `@ApiResponse`, …).
+
+<!-- SWAGGER:END -->
+<!-- SERVEWEB:START -->
+## El api sirve el web (single deployable)
+
+Con `--serveWeb`, el api monta `apps/web/dist` con `@nestjs/serve-static` (excluyendo `/api/*`), así
+que un solo proceso sirve front + API. Es para **producción** (en dev se usa el proxy). Compruébalo:
+
+```bash
+vp run -r build                 # genera apps/web/dist y apps/api/dist
+node apps/api/dist/main.js      # o: vp run @app/api#start
+# el api sirve el front y la API en el mismo puerto:
+curl -s -o /dev/null -w "%{http_code}\n" http://localhost:__API_PORT__/            # 200 (index.html)
+curl -s http://localhost:__API_PORT__/api/health                                  # {"status":"ok"}
+```
+
+La ruta del estático se resuelve en `apps/api/src/app.module.ts` (`ServeStaticModule.forRoot`).
+
+<!-- SERVEWEB:END -->
+<!-- DOCKER:START -->
+## Docker
+
+El `api` trae un `Dockerfile` multi-stage (`apps/api/Dockerfile`). El **contexto de build debe ser la
+raíz del monorepo** (el api se construye desde todo el workspace):
+
+```bash
+docker build -f apps/api/Dockerfile -t __PROJECT_NAME__-api .
+docker run --rm -p __API_PORT__:__API_PORT__ -e PORT=__API_PORT__ __PROJECT_NAME__-api
+# en otra terminal, comprueba:
+curl -s http://localhost:__API_PORT__/api/health                                  # {"status":"ok"}
+```
+
+Es un punto de partida (la imagen incluye el workspace completo). Para una imagen más liviana, parte
+de `pnpm deploy --filter @app/api --prod`.
+
+<!-- DOCKER:END -->
+## Añadir un recurso
+
+Mira `apps/api/src/items` (controller + service + module en memoria) y `health` como plantillas, y
+declara su contrato en `packages/contracts`.

package/template/_dockerignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+**/node_modules
+**/dist
+.git
+*.log
+.env
+.env.*

package/template/_gitignore

@@ -0,0 +1,30 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+build
+*.local
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/template/apps/api/Dockerfile

@@ -0,0 +1,32 @@
+# Multi-stage image for @app/api. The build context must be the MONOREPO ROOT (the api is built from
+# the whole workspace), e.g. from the repo root:
+#
+#   docker build -f apps/api/Dockerfile -t app-api .
+#
+# This is a pragmatic starting point — it ships the full installed workspace. For a slimmer image,
+# look at `pnpm deploy --filter @app/api --prod`.
+FROM node:22-slim AS build
+# CI=true: pnpm purges a stale modules dir non-interactively instead of aborting (no TTY in a build).
+# The prompt-disable lets corepack fetch pnpm without asking.
+ENV CI=true
+ENV COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+# vite-plus's native core initializes an HTTPS client on startup and panics without system CA certs,
+# which the -slim image omits.
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
+RUN corepack enable
+WORKDIR /repo
+COPY . .
+# --ignore-scripts skips the `prepare` git-hooks lifecycle script (added when you opt into pre-commit
+# hooks at `vp create`), which needs git/a repo and is pointless in an image. The build needs no
+# install scripts.
+RUN pnpm install --frozen-lockfile --ignore-scripts
+# Build the whole workspace so apps/web/dist exists too (needed when the api serves the web app).
+RUN pnpm -r run build
+
+FROM node:22-slim AS runtime
+ENV NODE_ENV=production
+WORKDIR /repo
+# The api externalizes its dependencies in the SSR build, so node_modules must be present at runtime.
+COPY --from=build /repo ./
+EXPOSE __API_PORT__
+CMD ["node", "apps/api/dist/main.js"]

package/template/apps/api/_env.example

@@ -0,0 +1,3 @@
+# Copy to .env and adjust. Validated by src/config/env.ts at boot.
+NODE_ENV=development
+PORT=__API_PORT__

package/template/apps/api/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+*.log
+
+# Env
+.env
+.env.*
+!.env.example

package/template/apps/api/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@app/api",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite-node --watch src/main.ts",
+    "build": "vp build",
+    "start": "node dist/main.js",
+    "lint": "vp lint",
+    "check": "vp check"
+  },
+  "dependencies": {
+    "@app/contracts": "workspace:*",
+    "@nestjs/common": "^11",
+    "@nestjs/core": "^11",
+    "@nestjs/platform-express": "^11",
+    "nestjs-pino": "^4",
+    "pino-http": "^10",
+    "reflect-metadata": "^0.2",
+    "rxjs": "^7.8",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@nestjs/testing": "^11",
+    "@types/node": "catalog:",
+    "pino-pretty": "^13",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-node": "^6",
+    "vite-plus": "catalog:"
+  }
+}

package/template/apps/api/src/app.module.ts

@@ -0,0 +1,33 @@
+// __SERVEWEB_PATH_IMPORT__
+import { Module } from '@nestjs/common'
+// __SERVEWEB_MODULE_IMPORT__
+import { LoggerModule } from 'nestjs-pino'
+
+import { ConfigModule } from './config/config.module'
+import { ENV, type Env } from './config/env'
+import { HealthModule } from './health/health.module'
+import { ItemsModule } from './items/items.module'
+
+@Module({
+  imports: [
+    // __SERVEWEB_MODULE__
+    ConfigModule,
+    LoggerModule.forRootAsync({
+      // Read NODE_ENV from the Zod-validated env (the global ConfigModule) instead of raw process.env.
+      inject: [ENV],
+      useFactory: (env: Env) => ({
+        pinoHttp: {
+          // pino emits JSON by default. In dev, pretty-print it (single line, colored) so the logs are
+          // readable in the same terminal as the web dev server. In production, emit raw JSON to stdout.
+          transport: env.NODE_ENV === 'production' ? undefined : { target: 'pino-pretty', options: { singleLine: true } }
+        },
+        // Named wildcard (`*path`) instead of the legacy `*`: with `setGlobalPrefix('api')` this middleware
+        // route becomes `/api/*path`, which Express 5 / path-to-regexp 8 accepts without a deprecation warning.
+        forRoutes: ['*path']
+      })
+    }),
+    HealthModule,
+    ItemsModule
+  ]
+})
+export class AppModule {}

package/template/apps/api/src/common/zod-validation.pipe.ts

@@ -0,0 +1,16 @@
+import { BadRequestException, type PipeTransform } from '@nestjs/common'
+import type { ZodSchema } from 'zod'
+
+/**
+ * Minimal, zero-dependency bridge between Zod and Nest's pipe system. Use it per-route against a
+ * schema from `@app/contracts`, e.g. `@Body(new ZodValidationPipe(createItemSchema)) body: CreateItem`.
+ */
+export class ZodValidationPipe<T> implements PipeTransform {
+  constructor(private readonly schema: ZodSchema<T>) {}
+
+  transform(value: unknown): T {
+    const result = this.schema.safeParse(value)
+    if (!result.success) throw new BadRequestException(result.error.flatten())
+    return result.data
+  }
+}

package/template/apps/api/src/config/config.module.ts

@@ -0,0 +1,11 @@
+import { Global, Module } from '@nestjs/common'
+
+import { ENV, loadEnv } from './env'
+
+// Global so any provider can inject the validated env via `@Inject(ENV)`.
+@Global()
+@Module({
+  providers: [{ provide: ENV, useFactory: loadEnv }],
+  exports: [ENV]
+})
+export class ConfigModule {}

package/template/apps/api/src/config/env.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+/** Validate `process.env` at boot — the app fails fast with a clear error if something is missing. */
+export const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(__API_PORT__)
+})
+
+export type Env = z.infer<typeof envSchema>
+
+/** DI token for the parsed, validated environment. */
+export const ENV = Symbol('ENV')
+
+export const loadEnv = (): Env => envSchema.parse(process.env)

package/template/apps/api/src/health/health.controller.ts

@@ -0,0 +1,9 @@
+import { Controller, Get } from '@nestjs/common'
+
+@Controller('health')
+export class HealthController {
+  @Get()
+  check(): { status: string } {
+    return { status: 'ok' }
+  }
+}