Installation, Nest CLI & Project Structure

Introduction

The fastest and most reliable way to start a NestJS project is the official Nest CLI. It creates a complete, working project with TypeScript, a test setup and sensible defaults already configured — and it keeps generating correctly structured code for you as the project grows.

Prerequisites

You need Node.js installed — use a current LTS release (NestJS 12, the current major version, requires Node.js 20 or newer). npm comes bundled with Node.js. Check both from your terminal:

node -v
npm -v

You will also want a code editor with good TypeScript support — Visual Studio Code is the most common choice — and an API client such as Postman, Insomnia or the VS Code REST Client extension for testing endpoints later.

Installing the Nest CLI

Install the CLI globally with npm so the nest command is available everywhere:

npm install -g @nestjs/cli
nest --version

Creating Your First Project

nest new my-first-api

The CLI asks which package manager you want (npm, yarn or pnpm), then creates the folder, writes the starter files and installs all dependencies. When it finishes, move into the project:

cd my-first-api

Project Structure Explained

my-first-api/
├── src/
│   ├── app.controller.spec.ts   # unit test for the controller
│   ├── app.controller.ts        # a basic controller with one route
│   ├── app.module.ts            # the root module
│   ├── app.service.ts           # a basic service (provider)
│   └── main.ts                  # entry point — creates and starts the app
├── test/
│   └── app.e2e-spec.ts          # end-to-end test
├── nest-cli.json                # Nest CLI settings
├── package.json                 # dependencies and npm scripts ("type": "module")
├── tsconfig.json                # TypeScript compiler settings
├── tsconfig.build.json
├── vitest.config.ts             # Vitest config for unit tests
└── vitest.config.e2e.ts         # Vitest config for e2e tests

The root module ties the starter controller and service together:

// src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

// src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service.js';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello(): string {
    return this.appService.getHello();
  }
}

// src/app.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
  getHello(): string {
    return 'Hello World!';
  }
}

The Entry Point: main.ts

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();

NestFactory.create() reads your root module, discovers every controller and provider it (and its imported modules) declares, builds the dependency injection container, and returns an application instance. app.listen() then starts the HTTP server — on the PORT environment variable if set, otherwise port 3000. The last line uses top-level await, so a startup error stops the process with a clear message instead of being silently ignored.

Running the App

npm run start:dev

start:dev runs the app in watch mode — every time you save a file, Nest recompiles and restarts automatically. Open http://localhost:3000 in your browser:

Generating Code with the CLI

Instead of creating files by hand, use nest generate (short form: nest g). The CLI creates the file, a matching test file, and automatically registers the new class in the right module.

nest g module users        # src/users/users.module.ts
nest g controller users    # src/users/users.controller.ts (+ spec)
nest g service users       # src/users/users.service.ts (+ spec)
nest g resource products   # a complete CRUD feature in one command

nest g resource is especially useful: it asks which transport layer you want (REST API, GraphQL, microservice or WebSockets) and whether to generate CRUD entry points, then creates a module, controller, service, DTOs and an entity class in one go.

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

You installed the Nest CLI, created and ran your first project, and walked through every generated file. You also learned how to generate new building blocks with the CLI. Next, you will dig into modules — the organizational backbone of every Nest application.