Chapter 4 — Setting Up a New Project

The why

Most backend projects fail in their first month — not because the code is bad, but because the setup was rushed.

You've seen it before: a repo with a vague npm install && npm start in the README. The database URL is hardcoded in a file called config.js. There's no way to tell if the app actually started correctly. And the first time you try to run it, you spend 45 minutes figuring out what's missing.

This chapter gives you a day-1 checklist — a repeatable process you follow for every new service you create. Do it once, do it right, and never waste time debugging startup again.

The Day-1 Checklist

Every new NestJS project needs these 7 things before you write a single business feature:

1. ✅ Scaffold with nest new
2. ✅ Folder structure — know what goes where
3. ✅ Environment validation — crash loudly on missing config
4. ✅ Health endpoints — /healthz and /readyz
5. ✅ Global validation pipe — reject bad input automatically
6. ✅ Naming conventions — pick once, never break
7. ✅ .gitignore and README.md — the basics

Let's go through each one.

Step 1: Scaffold with nest new

npm install -g @nestjs/cli
nest new quickbite-api

Choose npm as the package manager. NestJS generates this structure:

quickbite-api/
├── src/
│   ├── app.controller.spec.ts
│   ├── app.controller.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── test/
│   └── app.e2e-spec.ts
├── .eslintrc.js
├── .prettierrc
├── nest-cli.json
├── package.json
├── tsconfig.build.json
└── tsconfig.json

Step 2: Folder Structure — What Goes Where

Here's the folder layout you'll use for QuickBite:

src/
├── modules/           # Feature modules (orders, restaurants, users, payments)
│   ├── orders/
│   │   ├── dto/           # Request/response shapes
│   │   ├── entities/       # Database models
│   │   ├── orders.module.ts
│   │   ├── orders.controller.ts
│   │   ├── orders.service.ts
│   │   └── orders.repository.ts
│   └── ...
├── common/            # Shared code across all modules
│   ├── guards/        # Auth guards (JwtGuard, RolesGuard)
│   ├── decorators/    # Custom decorators (CurrentUser, Public)
│   ├── filters/       # Exception filters
│   ├── pipes/         # Validation pipes
│   ├── interceptors/  # Logging, timing interceptors
│   └── dto/           # Shared DTOs (PaginationDto, ApiResponse)
├── config/            # Configuration module
├── database/          # Migrations, seeds, database config
│   ├── migrations/
│   └── seeds/
└── main.ts            # Entry point

The rule: If a file doesn't belong to a specific feature, it goes in common/. If it's database-related but not a model, it goes in database/.

Step 3: Environment Validation — Crash Loudly

The number one cause of confusing startup failures: a missing environment variable that only gets read when a certain endpoint is hit. By then, you've already deployed.

Fix it with a configuration module that validates all env vars at boot:

npm install @nestjs/config joi

// src/config/env.config.ts
import * as Joi from 'joi';
 
export const envValidationSchema = Joi.object({
  NODE_ENV: Joi.string().valid('development', 'production', 'test

// src/app.module.ts
import { ConfigModule } from '@nestjs/config';
import { envValidationSchema } from './config/env.config';
 
@Module({
  imports: [
    ConfigModule.forRoot({
      validationSchema: envValidationSchema,

const dbUrl = process.env.DATABASE_URL; // undefined if missing — crashes later
process.env.API_KEY || 'default-key';   // defaults silently hide config errors

Now when you forget to set DATABASE_URL, the app refuses to start with a clear error message:

[ConfigModule] Error: "DATABASE_URL" is required

This is what you want. Fail fast, fail early.

Step 4: Health Endpoints

Kubernetes (and your deployment platform) needs two endpoints to know your app is healthy:

// src/common/controllers/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import { HealthCheckService, TypeOrmHealthIndicator } from '@nestjs/terminus';
 
@Controller('health')
export class HealthController {
  constructor(

npm install @nestjs/terminus @nestjs/axios

/healthz = "Is the process running?" — always returns 200. /readyz = "Can this pod handle traffic?" — returns 200 only if the database is reachable.

Step 5: Global Validation Pipe

NestJS has a built-in ValidationPipe that automatically validates incoming request bodies against your DTO classes:

// src/main.ts
import { ValidationPipe } from '@nestjs/common';
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
 
  app.useGlobalPipes(new ValidationPipe({

With this single line, every POST and PATCH endpoint gets automatic body validation. No manual if-checks needed.

Step 6: Naming Conventions

Pick these once, enforce them in code reviews, and never break them:

The rule: If you see a file called orderController.ts in a PR, send it back. Consistency is free — inconsistency costs hours of confusion.

Step 7: .gitignore and README.md

Minimal .gitignore for a NestJS project:

node_modules/
dist/
.env
.env.local
*.log
coverage/

Minimal README.md template:

# QuickBite API
 
Food delivery backend built with NestJS + PostgreSQL.
 
## Prerequisites
 
- Node.js v20+
- PostgreSQL 14+
- Redis 7+
 
## Setup
 
1. Clone the repo
2. `cp .env.example .env` and fill in values
3. `npm install`
4. `npm run db:migrate`
5. `npm run start:dev`

Putting It All Together

Here's what the main.ts looks like when you've completed the checklist:

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';
 
async function bootstrap() {
  const app = await NestFactory.create

Common Mistakes

One Thing to Remember