name: "nestjs-project-scaffold" description: "Use this skill whenever the user wants to create, restructure, or standardize a NestJS backend project in TypeScript, including folder layout, config, environment setup, tooling, and initial integrations (TypeORM-ready, testing-ready, and deployment-friendly)."

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:

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):
```
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.

nestjs-project-scaffold

SKILL.md