Nest CLI руководство- 1.1

kirilljs

Для удобной работы с Nest есть дополнительный инструмент — Nest CLI. Это приложение для командной строки, которое упрощает использование фреймворка и помогает автоматизировать часто выполняемые задачи. Например, с его помощью вы можете:

Сгенерировать основу для проекта.
Подготовить шаблоны для контроллеров, моделей и других компонентов.

Проще говоря, Nest CLI создаёт необходимые файлы и, в некоторых случаях, подключает их к модулю приложения.

Установка

Nest CLI — это обычный npm-пакет. Чтобы начать его использовать, нужно его установить. Есть несколько способов это сделать, но самый простой — установить пакет глобально. Для этого выполните команду:

npm install -g @nestjs/cli

После выполнения этой команды Nest CLI будет доступен для использования. Чтобы проверить, что установка прошла успешно, введите в терминале:

nest --help

Если всё установлено правильно, вы увидите список доступных команд:

Помимо глобальной установки, вы можете использовать утилиту npx. Например, вы можете установить @nestjs/cli как dev-зависимость и запускать его с помощью npx. Этот способ часто предпочтительнее, так как позволяет контролировать версию Nest CLI и обновлять её только для конкретного проекта.

Основные команды Nest CLI

new [options] [name] — генерирует каркас для нового приложения на Nest.
build [options] [app] — выполняет сборку приложения.
start [options] [app] — запускает приложение.
info — выводит информацию о проекте.
add [options] <library> — добавляет внешнюю библиотеку к проекту.
generate [options] <schematic> [name] [path] — формирует заготовку для нового элемента Nest.

Список команд будет расширяться по мере развития утилиты, поэтому не забывайте периодически обновлять её. Обратите внимание на вертикальную черту в некоторых командах, например, в команде new. После вертикальной черты указан псевдоним — дополнительное имя команды.

Некоторые команды используются особенно часто. Чтобы сэкономить время на ввод полного имени команды, вы можете использовать псевдонимы. Обычно они состоят из одного или нескольких символов, что делает их быстрее для набора на клавиатуре.

Давайте рассмотрим, как создать заготовку нового приложения, используя команду new:

nest new my-awesome-project

Эта команда создаст новую директорию с именем my-awesome-project и сгенерирует все необходимые файлы для вашего нового проекта.

Чтобы сделать процесс еще проще, команда new имеет псевдоним — n. Это значит, что вместо того, чтобы вводить new, вы можете просто ввести n. Удобно, правда?

Кроме команды new, есть и другие полезные псевдонимы для часто используемых команд:

new — n
info — i
generate — g

На практике, команды new и generate используются чаще всего, поэтому обязательно запомните их псевдонимы!

nest n my-awesome-project

Обратите внимание на то, что описание команд содержит секцию [options]. Это означает, что существуют дополнительные параметры, которые вы можете использовать, но они не обязательны. Если вы видите квадратные скобки, знайте — это опции, которые можно пропустить.

С другой стороны, всё, что заключено в угловые скобки, обязательно для ввода. Не забудьте об этом!

Создание нового проекта с помощью Nest

Команда new позволяет сгенерировать основу для нового проекта на Nest. Что именно включает в себя “основа”? Это начальная файловая структура проекта, установка основных зависимостей, подготовка конфигурационных файлов, инициализация git-репозитория и многое другое. Nest CLI делает все это за вас, чтобы вы могли сосредоточиться на разработке. Если вам нужно, вы всегда можете внести изменения и настроить отдельные части проекта по своему усмотрению.

Команда new поддерживает два режима работы: стандартный (для самостоятельных проектов) и монорепозиторий (для проектов, использующих монорепозитории). В этом руководстве мы сосредоточимся на первом варианте, а позже обсудим, как работать с монорепозиториями.

Практически все команды поддерживают параметр --dry-run (-d). Это невероятно полезный параметр, который позволяет вам увидеть, какие изменения будут внесены в файловую систему после выполнения команды без параметра --dry-run. Например, команда nest n my-awesome-project --dry-run выведет список файлов, которые будут созданы с помощью команды new. Этот параметр особенно полезен, когда вы изучаете Nest CLI.

Не забывайте, что любые команды Nest CLI поддерживают параметр --dry-run (см. врезку). Давайте воспользуемся им с командой new, чтобы увидеть список файлов, которые будут сгенерированы после выполнения команды:

nest new my-awesome-project --dry-run

После выполнения команды будет создан список файлов, которые появятся, если запустить команду без параметра --dry-run:

Параметр --dry-run позволяет вам увидеть список файлов, которые будут созданы в результате выполнения команды. На втором рисунке вы можете заметить, что при создании проекта будут подготовлены файлы конфигурации для таких инструментов, как ESLint, Prettier и другие. Теперь давайте попробуем сгенерировать новый проект, повторив команду, но без параметра --dry-run:

nest new my-awesome-project

Когда вы запускаете команду без дополнительных параметров, активируется «мастер» подготовки нового проекта. На первом шаге вам будет предложено ответить на вопрос: “Какой менеджер пакетов вы будете использовать?” Доступны три варианта: npm, yarn и pnpm. В рамках серии статей мы будем использовать npm.

После выбора менеджера пакетов начнётся процесс подготовки проекта: создадутся необходимые файлы, инициализируется git-репозиторий, установятся зависимости и многое другое. Это позволит вам быстро приступить к разработке вашего нового проекта!

После создания основы проекта перейдите в папку с проектом. Чтобы запустить проект, используйте npm-скрипт start или start:dev (эти сценарии рассматриваются в отдельной статье).

# Перейдём в папку с проектом
cd my-awesome-project

# Запустим проект в dev-режиме
npm run start:dev

На четвёртом рисунке представлен пример запущенного проекта. Обратите внимание, что в проекте уже реализована поддержка логирования, создан тестовый маршрут и настроен watch-режим. Это значит, что при изменении файлов проект автоматически перезапускается, что значительно упрощает процесс разработки.

Параметры для команды `new`

Команда new поддерживает различные параметры (options). Мы уже рассмотрели один из них — --dry-run, но это не единственный доступный параметр. Вот список поддерживаемых опций:

--dry-run, -d: Выводит информацию о файлах, которые будут созданы в результате выполнения команды.
--skip-git, -g: Пропускает инициализацию git-репозитория.
--skip-install, -s: Пропускает установку зависимостей.
--package-manager: Позволяет определить менеджер пакетов. Доступные варианты: npm, yarn или pnpm.
--language: Устанавливает язык разработки: TS (TypeScript) или JS (JavaScript).
--strict: Включает строгий режим для TypeScript. В конфигурации ts активируются флаги: strictNullChecks, noImplicitAny, strictBindCallApply, forceConsistentCasingInFileNames, noFallthroughCasesInSwitch.

С помощью этих параметров вы можете легко создавать дополнительные сценарии автоматизации. Например, если вам часто приходится создавать проекты с одинаковой конфигурацией, вы можете подготовить сценарий с перечислением необходимых опций. Таким образом, Nest CLI сформирует основу для проекта без лишних вопросов, что значительно сэкономит ваше время!

Информация о проекте с помощью команды `info`

Команда info выводит в терминал сводную информацию о проекте. Эта информация особенно полезна, когда вы присоединяетесь к существующему проекту, так как позволяет понять, какие версии компонентов Nest используются.

Чтобы получить информацию о проекте, просто выполните команду nest info в терминале, находясь в директории вашего проекта. Вот пример выполнения команды для проекта, который мы подготовили в предыдущем разделе:

Такой вывод поможет вам быстро ознакомиться с основными компонентами и их версиями, что облегчит дальнейшую работу с проектом.

Генератор заготовок файлов с помощью команды `generate`

Команда generate — это инструмент, с которым вам предстоит взаимодействовать особенно часто. Она позволяет создавать заготовки различных файлов, которые служат компонентами при разработке проекта на Nest. Например, Nest-модуль является одним из таких компонентов. Вы можете создать новый модуль вручную в редакторе, но команда generate сделает это за вас, подготовив все необходимые файлы (модуль, файл для тестирования и так далее) и выполнив начальное подключение. Это особенно удобно на начальном этапе разработки.

Синтаксис команды

Синтаксис команды выглядит следующим образом:

nest generate <schematic> <name> [options]
Или с использованием псевдонима `g`:
nest g <schematic> <name> [options]

Команда generate ожидает два обязательных аргумента:

<schematic> — схема, для которой будет сгенерирована заготовка. Вы можете рассматривать схему как компонент для разработки приложения. Например, class (для формирования заготовки класса), controller (для формирования контроллера) и так далее. Список поддерживаемых схем представлен ниже.
<name> — имя компонента. В качестве имени компонента может использоваться любое валидное имя для директории или файла в файловой системе.

Теперь давайте разберёмся с видами схем, для которых команда generate умеет создавать заготовки. Список поддерживаемых схем приведён в таблице.

Схема	Псевдоним	Описание
`app`	Нет	Создаёт новое Nest-приложение в монорепозитории.
`library`	`lib`	Создаёт заготовку для новой библиотеки в монорепозитории.
`class`	`cl`	Создаёт заготовку для нового класса.
`controller`	`co`	Создаёт заготовку для контроллера.
`decorator`	`d`	Создаёт заготовку для пользовательского декоратора.
`filter`	`f`	Создаёт заготовку для `filter`.
`gateway`	`ga`	Создаёт заготовку для `gateway`.
`guard`	`gu`	Создаёт заготовку для `guard`.
`interface`	`itf`	Создаёт заготовку для описания интерфейса.
`interceptor`	`itc`	Создаёт заготовку для описания `interceptor`.
`middleware`	`mi`	Создаёт заготовку для `middleware`.
`module`	`mo`	Создаёт заготовку для нового модуля.
`pipe`	`pi`	Создаёт новый `pipe`.
`provider`	`pr`	Создаёт заготовку для `provider`.
`resolver`	`r`	Создаёт заготовку для `resolver`.
`resource`	`res`	Заготовка для CRUD (Create Read Update Delete) ресурса.
`service`	`s`	Создаёт заготовку для сервиса.

Как вы можете заметить, в Nest имеется множество готовых компонентов (абстракций). Мы будем знакомиться с ними по мере выхода статей по NestJs и по мере необходимости. А сейчас давайте посмотрим на пример выполнения команды generate. Обратите внимание, что команду следует выполнять в директории с вашим Nest-проектом:

nest generate controller user

В приведенной выше команде мы применили её к новому проекту на Nest. В результате была создана новая директория user, а в ней — два файла: user.controller.ts (заготовка для контроллера) и user.controller.spec.ts (заготовка для тестов контроллера).

Теперь давайте заглянем внутрь файла контроллера:

import { Controller } from '@nestjs/common';

@Controller('user')
export class UserController {}

В этом файле был сформирован класс для будущего контроллера, к которому уже применён одноимённый декоратор (с деталями мы познакомимся позже). Кроме того, помимо создания новых файлов, был изменён основной модуль приложения (app.module.ts), в который добавлено подключение нового контроллера.

Заготовки для других компонентов создаются аналогичным образом. Может показаться, что Nest CLI не приносит особой пользы, так как перечисленные файлы и изменения легко можно сделать вручную. Однако Nest CLI открывает большие перспективы для автоматизации разработки. Рассмотрим ещё один пример: на этот раз мы сформируем заготовку сервиса user. Для краткости воспользуемся псевдонимами:

Вместо длинных слов generate и service мы используем псевдонимы g и s. Эту команду мы снова выполнили на стартовом проекте, где в прошлый раз создавали контроллер. Результатом выполнения стали новые файлы: user.service.ts и user.service.spec.ts. Модуль приложения также обновился, и в него было добавлено подключение сервиса user.

Важно отметить, что при запуске команды мы не указываем, где именно создать сервис. Выбор пути происходит на основании имени компонента. В нашем случае мы указали имя user, и заготовка сервиса автоматически была создана в директории users, рядом с ранее созданным контроллером.

Параметры для команды `generate`

Команда generate поддерживает различные параметры. Обратите внимание на параметр --dry-run, который особенно полезен в связке с командой generate:

--dry-run, -d: Выводит информацию о файлах, которые будут созданы в результате выполнения команды.
--project [project], -p: Указывает проект, в который следует добавить компонент.
--flat: Не создаёт директории для компонентов.
--spec: Генерирует заготовки для тестов. Эта опция применяется по умолчанию.
--no-spec: Не создаёт заготовки для тестов.

Заключение

Nest CLI — это мощный инструмент для командной строки, который упрощает работу с фреймворком Nest и позволяет автоматизировать некоторые типовые сценарии. Среди таких сценариев можно выделить: автоматическое формирование заготовок для различных компонентов, подготовку фундамента для проекта, управление проектами в монорепозитории и многое другое.

В этом разделе мы познакомились с основными командами: new, generate, info. Эти команды являются наиболее часто используемыми при работе с Nest CLI. С другими командами мы познакомимся позднее.