NestJS — Установка зависимостей, создание и запуск первого проекта
Что такое NestJS и зачем он нужен
NestJS — это фреймворк на Node.js и TypeScript для написания серверных приложений по принципам модульности, инверсии зависимостей и SOLID. Он помогает структурировать код, упрощает тестирование и масштабирование, а также даёт единые подходы к контроллерам, сервисам, фильтрам ошибок, пайпам валидации, интерцепторам и middleware.
Подготовка окружения
Установите Node.js версии LTS (рекомендуется >= 20.x) — это гарантирует поддержку современных возможностей платформы и стабильность.
Пакетный менеджер: подойдёт npm, yarn или pnpm . Для начала можно использовать npm, поставляемый вместе с Node.js.
Проверьте, что ваш терминал видит node и npm:
node -v
npm -v
Установка Nest CLI и создание проекта
Существует два подхода: установить CLI глобально или запускать через npx. Для новичка проще использовать npx — так вы всегда получите актуальную версию генератора.
Вариант 1: через npx (рекомендовано)
npx @nestjs/cli new my-app
# Далее мастер спросит менеджер пакетов — выберите npm для простоты
Команда создаст скелет проекта, настроит TypeScript и добавит базовые скрипты.
Вариант 2: глобальная установка CLI
npm i -g @nestjs/cli
nest new my-app
Структура базового проекта
После генерации вы увидите минимальный каркас с модулем приложения, контроллером и сервисом. Ниже показаны ключевые файлы и их назначение.
src/main.ts — точка входа. Создаёт NestFactory и запускает HTTP-сервер.
src/app.module.ts — корневой модуль. Подключает контроллеры, провайдеры и другие модули.
src/app.controller.ts — пример контроллера с HTTP-эндпоинтом.
src/app.service.ts — пример сервиса с бизнес-логикой.
package.json — скрипты и зависимости проекта.
tsconfig.json — конфигурация TypeScript.
nest-cli.json — конфигурация генератора и сборки Nest.
Первый запуск приложения
Перейдите в каталог проекта и установите зависимости:
cd my-app
npm install
Запустите в режиме разработки с автоматической перезагрузкой:
npm run start:dev
Откройте в браузере адрес:
http://localhost:3000
Минимальные файлы для старта — примеры
src/main.ts
Точка входа в приложение. Здесь включим глобальную валидацию запросов, чтобы сразу получить корректную обработку входных данных.
import {NestFactory} from '@nestjs/core';
import {AppModule} from './app.module';
import {ValidationPipe} from '@nestjs/common';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true
}));
await app.listen(3000);
// Выведем в консоль адрес сервера
// console.log будет показан в терминале
console.log('Server is running on [http://localhost:3000](http://localhost:3000)');
}
bootstrap();
src/app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
@Module({
imports: [],
controllers: [AppController],
providers: [AppService]
})
export class AppModule {}
src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
@Controller()
export class AppController {
constructor(private readonly appService: AppService) {}
@Get()
getRoot() {
return this.appService.getHello();
}
}
src/app.service.ts
import { Injectable } from '@nestjs/common';
@Injectable()
export class AppService {
getHello() {
// Это сообщение увидите в браузере
return { message: 'Hello from NestJS' };
}
}
Правильная структура проекта (пример из реального приложения)
Ниже приводится пример разбиения кода по слоям и доменам. Такая структура облегчает навигацию, поддерживаемость и масштабирование.
Пояснение по слоям и папкам
src/http — слой транспортного интерфейса: контроллеры, декораторы, фильтры ошибок, интерсепторы, middleware, пайпы и типы, связанные с HTTP. Это «край» системы, принимающий запросы и возвращающий ответы.
src/logic — прикладная логика и Use Cases. Здесь нет HTTP-специфики, только бизнес-операции. Такой подход упрощает тестирование и повторное использование.
src/data — доступ к данным: доменные модули, репозитории, ORM-сущности, интеграции с БД и внешними хранилищами (PostgreSQL, MongoDB, Redis, S3).
src/events — события домена, эмиттеры, декораторы для публикации и подписки. Это основа для событийной архитектуры и интеграций.
src/schedule — планировщики задач (cron, интервальные задания), абстракции и реестр задач.
import {Injectable, NestInterceptor, ExecutionContext, CallHandler} from '@nestjs/common';
import {Observable} from 'rxjs';
@Injectable()
export class TracingInterceptor implements NestInterceptor {
intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
return next.handle();
}
}
Сборка и запуск в продакшене
Соберите проект:
npm run build
Запустите собранную версию:
npm run start:prod
Частые проблемы и как их избежать
Несовместимость версий: при ошибках установки удалите node_modules и файл package-lock.json, затем выполните установку заново.
Конфликт портов: измените порт в main.ts методом listen или через переменную окружения.
Ошибки типов: убедитесь, что tsconfig.json настроен корректно, а зависимости @types установлены.
Итоги
Вы установили окружение, сгенерировали каркас проекта NestJS, запустили сервер, включили валидацию и базовую обработку ошибок, а также разобрались с рекомендуемой структурой для масштабируемых приложений. Дальше вы сможете добавлять модули домена, интеграции с БД, события, планировщики задач, телеметрию и выстраивать зрелую архитектуру.