ng-packagr и сборка библиотек

ng-packagr — инструмент для сборки Angular-библиотек в формате, совместимом с Angular Package Format (APF). Он используется внутри Angular CLI и обеспечивает корректную публикацию библиотек для повторного использования.

Назначение и архитектура

Основные задачи ng-packagr:

  • компиляция TypeScript в ES2015+ и ES5
  • генерация .metadata.json
  • сборка деклараций .d.ts
  • корректная упаковка Angular-декораторов
  • поддержка tree-shaking

Результатом является пакет, готовый к установке через npm и использованию в любом Angular-приложении.

Структура библиотеки

Типичная структура проекта библиотеки:

projects/
  my-lib/
    src/
      lib/
        my-lib.module.ts
        my-lib.component.ts
      public-api.ts
    ng-package.json

Файл public-api.ts определяет публичный контракт библиотеки.

Конфигурация ng-package.json

Минимальная конфигурация:

{
  "$schema": "../. ./node_modules/ng-packagr/ng-package.schema.json",
  "dest": "../. ./dist/my-lib",
  "lib": {
    "entryFile": "src/public-api.ts"
  }
}

Через этот файл управляется сборка без прямого вмешательства в webpack.

Процесс сборки

Сборка запускается командой Angular CLI:

ng build my-lib

CLI делегирует выполнение ng-packagr, который:

  1. анализирует публичный API
  2. компилирует код через Angular Compiler
  3. генерирует разные форматы модулей
  4. формирует package.json в dist

Поддержка secondary entry points

Библиотека может иметь дополнительные точки входа:

projects/my-lib/src/button/
  button.module.ts
  public-api.ts

Для них создаётся отдельный ng-package.json. Это позволяет импортировать части библиотеки выборочно:

import { ButtonModule } from 'my-lib/button';

Работа со стилями и ассетами

ng-packagr поддерживает копирование стилей и ресурсов:

"assets": [
  "src/styles",
  "src/icons"
]

CSS и SCSS могут быть включены в сборку и доступны потребителю библиотеки.

Ограничения и требования

  • Библиотеки не должны зависеть от BrowserModule
  • Используется CommonModule
  • Запрещено прямое использование глобальных стилей
  • Весь код должен быть совместим с AOT-компиляцией

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

Интеграция с CI и публикация

После сборки каталог dist/my-lib полностью готов к публикации:

npm publish dist/my-lib

ng-packagr гарантирует, что опубликованный пакет соответствует ожиданиям Angular CLI и экосистемы, включая поддержку Ivy и оптимизации сборки.

Оглавление