NestJS Project Scaffold Skill

Purpose

You are a specialized assistant for bootstrapping and reshaping NestJS projects so they follow consistent, production-ready conventions.

Use this skill to:

•Scaffold a new NestJS project (standalone or part of a monorepo)
•Restructure an existing NestJS project to match preferred folder & module layout
•
Wire up base tooling:
- •TypeScript strict mode
- •ESLint + Prettier
- •Environment/config management
- •Basic logging & health check
•Make the project TypeORM-ready, testing-ready, and deployment-ready without fully implementing domain logic (other NestJS skills can do that).

Do not use this skill for:

•Implementing business logic (use modules/services/controllers skills)
•Advanced auth, caching, or microservices concerns
•Non-NestJS backend frameworks (Hono, Express-only, etc.)

If CLAUDE.md exists in the repo, treat it as authoritative for project layout, naming, and tooling preferences.

When To Apply This Skill

Trigger this skill when the user says things like:

•“Create a new NestJS API project.”
•“Set up a clean NestJS backend skeleton with TypeORM and testing.”
•“Restructure this NestJS project to follow a standard layout.”
•“Prepare this repo for NestJS with good defaults and configs.”
•“Add NestJS to this monorepo in a consistent way.”

Avoid this skill when the task is clearly about:

•Adding a specific module/feature (e.g. users, auth) → use feature/module-oriented skills.
•Only touching TypeORM entities/migrations → use TypeORM skills.

Project Assumptions

Unless the user or CLAUDE.md says otherwise, assume:

•Language: TypeScript
•
Package manager preference:
1. •pnpm if pnpm-lock.yaml exists
2. •yarn if yarn.lock exists
3. •otherwise npm
•Framework: NestJS (latest stable @ the time), CLI-based
•Testing: Jest by default (can later swap or complement with other tools)
•ORM: TypeORM will be used, but concrete entities & config belong to the nestjs-typeorm-integration skill.
•Env management: .env files + Nest ConfigModule or equivalent.

Target Project Structure

This skill aims to create or converge towards a structure like:

text

project-root/
  src/
    app.module.ts
    main.ts
    config/
      app.config.ts
      database.config.ts   # optional, for TypeORM later
    common/
      filters/
      guards/
      interceptors/
      decorators/
      dto/
    modules/
      health/
        health.module.ts
        health.controller.ts
    infrastructure/
      # optional: cross-cutting infra, e.g. database, messaging
  test/
    app.e2e-spec.ts
    jest-e2e.json
  .env.example
  nest-cli.json
  tsconfig.json
  tsconfig.build.json
  package.json
  README.md

For monorepos, adapt to a apps/api or similar convention, but maintain the same internal NestJS structure.

High-Level Workflow

When this skill is active, follow this process:

•
Detect or create NestJS project
- •
  If no NestJS project exists:
  - •Use CLI-equivalent steps to create a new Nest project in the desired folder.
  - •Set language to TypeScript.
- •
  If a NestJS project exists:
  - •Inspect its structure (main.ts, app.module.ts, src/ layout, nest-cli.json).
  - •Plan restructuring to align with the target structure above.
•
Set up config & environment management
- •Install and configure @nestjs/config (or follow project’s preferences in CLAUDE.md).
- •Create src/config directory with at least app.config.ts and (optionally) database.config.ts.
- •Wire ConfigModule.forRoot({ isGlobal: true, ... }) in app.module.ts.
•
Create base common infrastructure
- •
  Create src/common with subfolders for:
  - •filters (e.g. http-exception.filter.ts)
  - •guards (e.g. auth guards to be filled later)
  - •interceptors (e.g. logging/transform interceptors)
  - •decorators (custom decorators go here)
  - •dto (shared DTOs)
- •Provide at least one example (like a basic logging interceptor or global exception filter) if it fits the project direction.
•
Add a health module
- •
  Create HealthModule in src/modules/health or src/health:
  - •health.module.ts
  - •health.controller.ts with a simple GET /health endpoint.
- •Optionally integrate with Nest’s health checks later (e.g. Terminus) via another skill.
•
Configure main bootstrap
- •
  In main.ts, configure:
  - •NestFactory.create(AppModule)
  - •Global prefix if desired (e.g. /api)
  - •Validation pipe (can be added here or in a future validation skill)
  - •Basic logging
Example outline (pseudocode-level, adjusted per project):
ts
```
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api");
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
```
Maintain flexibility; actual details may depend on other skills (auth, validation).
•
Prepare TypeORM integration points (without full config)
- •
  Ensure structure allows adding database modules later:
  - •src/config/database.config.ts placeholder
  - •src/infrastructure/database placeholder directory if desired
- •Do not fully wire TypeORM here; leave detailed config to nestjs-typeorm-integration skill.
•
Tooling & quality gates
- •
  Ensure tsconfig.json and tsconfig.build.json are present and sane:
  - •Strict type checking preferred (unless CLAUDE.md says otherwise).
- •Ensure ESLint is set up (via Nest CLI defaults or project conventions).
- •Ensure basic lint, build, start, start:dev, test, test:e2e scripts in package.json are present or corrected.
•
Testing scaffold
- •Ensure Jest config exists (default from Nest CLI).
- •Make sure test/app.e2e-spec.ts and jest-e2e.json exist or create them if missing.
- •Don’t add detailed tests here (that’s for nestjs-testing-skill), but confirm scaffolding is ready.
•
Monorepo awareness (if applicable)
- •
  If the project is part of a monorepo (e.g. apps/api):
  - •Respect workspace structure (PNPM/Yarn/Nx/Turbo).
  - •Place Nest app under correct folder (apps/api or similar).
  - •Ensure scripts work from root (pnpm dev:api, etc.) if conventions exist.
•
Documentation
- •
  Update or create README.md with:
  - •How to run the project (install, start:dev, test)
  - •Basic architecture overview (where modules live)
  - •Where to add new modules (src/modules)
  - •Where config and env files live

Safe Defaults & Conventions

When making decisions:

•
Use convention over configuration:
- •src/modules/... for feature modules
- •src/common/... for shared utilities
- •Config modules in src/config/...
•
Don’t enforce a specific hexagonal/onion architecture unless CLAUDE.md says so, but do:
- •Separate pure domain modules from infrastructure when it’s clearly beneficial.
- •Be consistent across the project.
•
Keep bootstrapping minimal and extensible:
- •Don’t hardcode features that belong to dedicated skills (auth, caching, microservices).
- •Provide hooks/placeholders so those skills can plug in cleanly.

Example Prompts That Should Use This Skill

•“Create a new NestJS API service in apps/api with our usual setup.”
•“Reshape this messy NestJS codebase into a clean structure with modules and common utilities.”
•“Scaffold a NestJS project that we can later plug TypeORM and auth into.”
•“Set up a standard NestJS backend with config, health check, and testing ready.”

For these prompts, this skill should:

•Either create the NestJS app from scratch or refactor the existing project.
•Leave clear, well-structured hooks for other NestJS skills (auth, TypeORM integration, testing, microservices) to extend the backend cleanly.