Quick Start¶

This guide walks you through scaffolding your first NestJS project with spoonfeed.

Prerequisites¶

Node.js 22 or later
pnpm 9 or later (recommended) or npm

Installation¶

No global install required. Run spoonfeed directly:

pnpmnpx

pnpm dlx spoonfeed

npx spoonfeed

CLI Walkthrough¶

The CLI prompts you through four steps:

1. Project Name¶

Enter a name for your project. This becomes the directory name and the name field in package.json.

 Project name: my-api

2. Project Type¶

Select one of the seven project archetypes. Each type comes with a tailored main.ts, directory structure, and compatible recipe set.

 Project type:
   HTTP REST API (Fastify)
   AWS Lambda
   Microservice
   CLI Application
   Scheduled Worker
   Monorepo
   Full-Stack

See Project Types for details on each option.

3. Cloud Provider¶

Choose your target cloud platform. This filters the recipe list to show relevant cloud-specific recipes and pre-selects smart defaults.

 Cloud provider:
   AWS
   GCP
   Azure
   None

4. Recipe Selection¶

Browse and select from 112 recipes across categories like Database, Auth, Security, API Patterns, Observability, and more.

Recipes declare conflicts and requirements explicitly. The CLI validates your selection and rejects incompatible combinations before generating anything.

 Recipes:
   TypeORM + PostgreSQL
   JWT Authentication
   Swagger / OpenAPI
   Pino Logging
   Health Checks
   ...

What Gets Generated¶

After confirming your selections, spoonfeed generates a complete project:

my-api/
  src/
    main.ts                   # Bootstrap, configured for your project type
    app.module.ts             # Root module with recipe imports
    config/                   # Configuration factories
    shared/                   # Cross-cutting concerns
      constants/
      decorators/
      filters/                # GlobalExceptionFilter (RFC 9457)
      guards/
      interceptors/           # ResponseInterceptor
      pipes/
      utils/
    infrastructure/           # External integrations (per recipes)
    app/
      modules/                # Feature modules
  tests/
    unit/                     # Unit tests
    integration/              # Integration tests (Testcontainers)
    e2e/                      # End-to-end tests
    factories/                # Shared test data factories
  .env.example                # Environment variable template
  .env.development            # Dev environment defaults
  .env.staging                # Staging environment defaults
  .env.production             # Production environment template
  docker-compose.yml          # Dev container setup
  CLAUDE.md                   # AI context (Claude)
  .cursor/rules/project.mdc  # AI context (Cursor)
  .github/
    copilot-instructions.md   # AI context (Copilot)
    workflows/                # CI/CD pipelines
  package.json                # Exact dependency versions
  tsconfig.json

What Just Happened?¶

Here is what each part of the generated project does:

Directory / File	Purpose
`src/main.ts`	Application entry point. Pre-configured for your chosen project type (Fastify HTTP server, Lambda handler, microservice transport, etc.).
`src/app.module.ts`	Root NestJS module. All selected recipes are already imported and registered here.
`src/config/`	Typed configuration factories using `@nestjs/config`. Each recipe that needs configuration adds its own config file here.
`src/shared/errors/`	Typed error hierarchy (`ApplicationError`, `NotFoundError`, `ValidationError`, etc.) with trace codes for searchable error identification.
`src/shared/filters/`	`GlobalExceptionFilter` that converts all errors into RFC 9457 Problem Details responses automatically.
`src/shared/interceptors/`	`ResponseInterceptor` that wraps successful responses in a uniform envelope.
`src/infrastructure/`	External integration code generated by recipes (database connections, auth providers, cloud SDK wrappers).
`src/app/modules/`	Where your feature modules live. This is where you write your application code.
`tests/unit/`	Unit test files mirroring the `src/` directory structure. One `.spec.ts` per source file.
`tests/integration/`	Integration tests using Testcontainers for real database and service dependencies.
`tests/e2e/`	End-to-end HTTP tests that exercise the full request/response cycle.
`tests/factories/`	Shared test data builders for creating consistent test fixtures.
`.env.*`	Environment files for development, staging, and production. `.env.example` documents all variables.
`docker-compose.yml`	Dev containers for infrastructure dependencies (PostgreSQL, Redis, RabbitMQ, etc.) based on your selected recipes.
`CLAUDE.md` / `.cursor/rules/project.mdc` / `.github/copilot-instructions.md`	AI assistant context files tailored to your project's stack, conventions, and directory structure.
`.github/workflows/`	CI/CD pipeline definitions for your chosen cloud provider.
`package.json`	All dependencies pinned to exact versions (no `^` or `~`).

Everything is wired together

Selected recipes are not just installed as dependencies. Their modules are imported in app.module.ts, their configuration files are generated in config/, their environment variables are documented in .env.example, and their dev containers are added to docker-compose.yml. The project compiles and starts without any manual wiring.

Verify the Generated Project¶

After scaffolding, confirm the project works end to end:

cd my-api
pnpm install
pnpm start:dev

The development server starts with file watching on port 3000 by default. In a second terminal, verify the server is responding:

curl http://localhost:3000

You should see a response from the application. If you selected the Health Checks recipe, you can also hit:

curl http://localhost:3000/health

Run the test suite

The generated project includes pre-written tests. Run them to confirm everything is wired correctly:

# Unit tests
pnpm test

# Integration tests (requires Docker for Testcontainers)
pnpm test:integration

# End-to-end tests
pnpm test:e2e

Useful commands

Command	Description
`pnpm start:dev`	Start with file watching
`pnpm build`	Compile to `dist/`
`pnpm test`	Run unit tests
`pnpm test:integration`	Run integration tests
`pnpm test:e2e`	Run end-to-end tests
`pnpm lint`	Lint and auto-fix

No runtime dependency

The generated project has no dependency on spoonfeed. It is a standard NestJS application that you own entirely.