Angular CLI за пределами ng serve: генераторы, цели, кэш и статистика сборки

Большинство разработчиков Angular с самого начала ограничиваются четырьмя командами — ng serve, ng build, ng generate и ng test — и не ищут ничего другого. Это подходит для небольших приложений, но по мере роста рабочего пространства время, тратимое на написание шаблонного кода, поиск версий, оценку размера пакетов и устранение проблем с кэшем, становится все больше. CLI уже содержит решения для большинства этих задач. В этом руководстве рассматриваются опции, которые стоит использовать регулярно, объясняется, когда каждая из них полезна, и приводится компактный ежедневный рабочий процесс, который можно применить без изменений.

Если вы все еще находитесь на этапе создания самого рабочего пространства, инструкция по настройке современного проекта Angular охватывает эту часть; все, что написано ниже, предполагает наличие уже существующего проекта.

Используйте ng generate в полной мере

Генератор — это команда, известная всем в своей полной форме:

ng generate component user-profile

У каждого генератора есть краткое сокращение: generate превращается в g, а component — в c:

ng g c user-profile

Настоящая экономия ресурсов достигается с помощью флагов. Когда небольшой представительский компонент не требует файла спецификации, параметр --skip-tests предотвращает создание такого файла через CLI:

ng g c user-profile --skip-tests

По умолчанию каждый компонент сохраняется в отдельной папке. Параметр --flat позволяет записывать файлы непосредственно в текущую директорию, что удобно для крошечных компонентов, находящихся рядом со своим родителем:

ng g c user-profile --flat

Флаги можно комбинировать, поэтому вы можете запросить их оба одновременно:

ng g c user-profile --flat --skip-tests

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

Спрашивайте CLI вместо поиска в интернете

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

ng generate --help

Псевдоним работает аналогичным образом:

ng g --help

Добавление --help после конкретной схемы выводит все её опции с краткими описаниями:

ng g component --help

Опции меняются между версиями, а ответы на форумах часто описывают более старые параметры; вывод помощи всегда соответствует CLI, установленному в вашем проекте.

Чтение и изменение настроек с помощью ng config

Конфигурация рабочей среды хранится в файле angular.json, и бывает соблазн изменять этот файл напрямую. CLI предоставляет команду для чтения и записи этих значений:

ng config

При вызове в одиночку она выводит конфигурацию, чтобы вы могли увидеть, что установлено:

ng config

Вы также можете передать путь к JSON для чтения определенного значения или путь с последующим значением для его изменения, например, чтобы изменить параметр CLI для всей рабочей среды. В скриптах использование повторяемого вызова ng config предпочтительнее хрупких ручных изменений JSON: когда файл находится под управлением CLI, используйте CLI для его изменения.

Сообщите информацию о своей среде с помощью версии ng

Когда что-то ломается, важны точные версии. Вместо того чтобы открывать package.json и собирать информацию вручную, выполните:

ng version

или его сокращенную форму:

ng v

В результатах отображается версия Angular CLI, установленные пакеты Angular, Node.js, менеджер пакетов и операционная система в одном блоке. Именно это и нужно коллеге или администратору, когда вы просите о помощи. Отчет, в котором указано лишь то, что проект перестал работать, не даёт им никаких подсказок, тогда как копирование вывода следующей команды сразу отвечает на первые пять вопросов:

ng version

Измеряйте размер готового бандла вместо того, чтобы догадываться

Этот флаг сборки заслуживает гораздо более широкого использования, чем им пользуются на самом деле:

ng build --stats-json

Он создаёт файл статистики, описывающий содержимое каждого фрагмента вывода. Подав этот файл в анализатор пакетов, вы получите визуальный разбор того, откуда берутся байты. Имейте в виду, что формат файла зависит от инструмента сборки: старые версии, основанные на webpack, генерируют статистику в формате webpack, тогда как новые инструменты сборки на основе esbuild выдают метаданные в формате esbuild, поэтому выбирайте анализатор, понимающий формат вывода вашего инструмента сборки, и ознакомьтесь с документацией Angular для вашей версии.

К типичным проблемам, из-за которых приложение работает медленно, относятся:

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

Ничто из этого невидимо только из исходного кода. Сравнение статистики до и после обновления зависимостей — это простой способ выявить регрессии.

Очистите кэш сборки перед повторной установкой всего

CLI хранит постоянный дисковой кэш, чтобы повторные сборки проходили быстрее. Команда ng cache управляет им; команда ng cache info показывает, где находится кэш и включен ли он:

ng cache

Когда сборки начинают вести себя странно, очистка этого кэша часто является решением проблемы:

ng cache clean

Устаревшие записи кэша обычно появляются после изменения зависимостей, обновления Angular или смены веток с разными версиями пакетов. Очистка кэша занимает секунды, поэтому попробуйте это сделать перед более медленным способом — удалением папки node_modules и повторной установкой.

Проверка кода локально и в CI

Если у вашего проекта настроен инструмент проверки кода, запустите его с помощью:

ng lint

В новых версиях Angular по умолчанию не включен инструмент проверки кода, поэтому команда ng lint будет работать только после его установки, обычно с помощью интеграции Angular ESLint. После настройки он выявляет проблемы до того, как ревизору придётся:

• используемые переменные и импорты
• несоответствия в форматировании
• вероятные ошибки
• нежелательные паттерны
• общие проблемы качества кода

Запуск той же команды в CI-пайплайне позволяет отмечать проблемный код до того, как он попадёт в основную ветку, и никому не нужно помнить о её запуске.

Однократный запуск тестов в автоматизации

Локально тесты обычно работают в режиме наблюдения и запускаются заново при каждом сохранении:

ng test

В CI-задании нет смысла использовать процесс, ожидающий изменений файлов. Отключение режима наблюдения заставляет команду запустить всю серию тестов один раз и завершиться:

ng test --watch=false

Код выхода отражает результат выполнения тестов, и именно он используется системой для обозначения статуса задачи как «зеленый» или «красный». Система в режиме наблюдения просто остается в таком состоянии до истечения времени ожидания. Локальная разработка и CI имеют разные требования, поэтому одна команда строки не обязательно должна удовлетворять их оба.

Выбор одного проекта в рабочем пространстве с несколькими проектами

Более крупные репозитории Angular часто содержат несколько приложений и библиотек в одном рабочем пространстве. Большинство команд принимают имя проекта, поэтому вы можете собрать только одно приложение:

ng build my-app

или протестировать только одно:

ng test my-app

В рабочем пространстве в стиле монорепозитория это становится обычной практикой:

ng build admin
ng build customer
ng test shared-ui

Работа над общей библиотекой UI не должна означать пересборку каждого приложения; использование команд с узким охватом сокращает циклы обратной связи.

Вызов любой целевой архитектуры с помощью ng run

За знакомыми командами скрывается более общая команда, которую напрямую используют лишь немногие разработчики:

ng run

Она выполняет указанную цель архитектора из конфигурации рабочего пространства с использованием формата project:target, при необходимости с указанием имени конфигурации:

ng run my-app:build

Стандартные команды на самом деле являются сокращениями для распространённых целей. Команда ng run становится полезной, когда рабочее пространство определяет собственные цели — например, инструмент для генерации кода, развертывания превью или запуска специализированной схемы тестирования. Можно представить её как «запустить именно эту цель данного проекта», без каких-либо дополнительных выводов.

Открытие документации из терминала

Когда вам нужно быстро проверить API, CLI может начать поиск за вас:

ng doc

Укажите ключевое слово, и система найдёт соответствующую информацию в официальной документации Angular:

ng doc signals

Обратите внимание, что результаты открываются в вашем браузере, а не выводятся в терминале, поэтому это скорее переход на соответствующую страницу, чем офлайн-справочник.

Пусть помощь заменит запоминание

Возможно, самой полезной привычкой из всех является использование этой команды:

ng help

Она перечисляет все команды верхнего уровня. Чтобы узнать опции конкретной команды, добавьте --help:

ng build --help

То же самое работает и с генераторами, даже для простейших схем:

ng generate service --help

Никому не нужно запоминать все флаги. Эффективные разработчики — это не те, кто помнит всё, а те, кто знает, где искать информацию в момент забывчивости.

Ежедневный рабочий процесс, объединяющий всё это

Практическая рутина может выглядеть следующим образом. Запустите сервер разработки:

ng serve

При разработке функций генерируйте необходимое с использованием соответствующих флагов:

ng g c profile --skip-tests

Перед коммитом пройдите проверку кода и запустите тесты один раз:

ng lint
ng test --watch=false

Для производственной сборки явно используйте конфигурацию для производства:

ng build --configuration production

Если возникают вопросы к размеру пакета, сгенерируйте статистику:

ng build --stats-json

Если сборка начинает вести себя некорректно, сначала очистите кэш:

ng cache clean

А если вы забыли какой-то параметр, спросите у самой команды:

ng <command> --help

Заключение

Angular CLI представляет собой инструмент для повышения производительности на всем этапе разработки, и наибольшая польза приносит небольшое количество опций, устраняющих повторную работу:

• генерация кода с использованием флагов вместо ручного написания шаблонных элементов
• ограничение команд одним проектом в многопроектных рабочих пространствах

используйте статистику для оценки производительности пакетов вместо догадок

очистите кэш перед полной переустановкой

проводите тесты без режима наблюдения в CI и проверяйте код при каждой изменении

опирайтесь на параметр --help, который всегда соответствует установленной версии

В следующий раз, когда откроете терминал в проекте Angular, помните, что за командой ng скрывается гораздо больше:

ng serve