Как создавать библиотеки Angular и публиковать их (с примером)

Отдача сообществу

Отдача сообществу — идея, которая мне очень нравится. Я считаю очень важным делиться своими знаниями и результатами, я сам многому научился у других разработчиков.

В этой статье я делюсь своим процессом публикации библиотек Angular и демонстрационным приложением, которое использует эти библиотеки. Я настоятельно рекомендую вам выработать привычку делиться своей работой (например, кодом, результатами и идеями). Это может быть повторно используемый компонент, такой как компонент пользовательского интерфейса, или инструмент, подобный тому, который я использую в качестве примера для этой статьи, или просто какой-нибудь изящный маленький трюк. Вот статья, в которой более подробно рассказывается о преимуществах публикации пакетов npm:

Почему публикация собственных пакетов npm может сделать вас лучшим разработчиком
Существует множество отличных ресурсов о том, как публиковать собственные пакеты npm, но я хочу поделиться некоторыми мыслями о почему…dev.to

Недавно я создал несколько декораторов для отладки @ngrx/component-stores и опубликовал их в виде библиотеки Angular на npmjs.org, чтобы другим разработчикам было проще их использовать.

В этом пошаговом руководстве я объясню, как я создал библиотеку, а также демо-приложение для нее, и как я опубликовал библиотеку на npmjs.org и демо-приложение на StackBlitz.

Вы можете найти полный исходный код библиотеки и демо-приложение на моем Github. Вы также можете попробовать демо-приложение на StackBlitz.

📋Оглавление

Мое руководство охватывает следующие темы:

Как создать многопроектное рабочее пространство
Как сгенерировать библиотеку и скелеты демонстрационного приложения в рабочей области
Детали реализации библиотеки
Зависимости и одноранговые зависимости
Внедрение демо-приложения
Как собрать библиотеку и запустить демо-приложение
Как опубликовать библиотеку на npmjs.org
Как запустить демо-приложение на StackBlitz

Создание многопроектного рабочего пространства

В качестве первого шага мы создаем многопроектное рабочее пространство для нашей библиотеки и демонстрационного приложения. Создайте рабочее пространство:

ng new ngx-ngrx-component-store-debug-tools --no-create-application

Создайте библиотеку ngx-ngrx-component-store-debug-tools в рабочей области:

cd ngx-ngrx-component-store-debug-tools
ng generate library ngx-ngrx-component-store-debug-tools

Затем сгенерируйте приложение demo в рабочей области:

ng generate application demo

Генератор задает следующие вопросы:

Хотите добавить маршрутизацию Angular? Н
Какой формат таблицы стилей вы хотели бы использовать? СКСС

По завершении команды ng generate мы находим в нашей рабочей области два новых каталога проекта: каталогprojects/demo для приложения и каталог projects/ngx-ngrx-component-store-debug-tools для библиотеки. Генератор также устанавливает несколько дополнительных пакетов.

Реализация нашей библиотеки

У нас есть module, component и service в каталоге src/lib библиотеки. Эти файлы полезны для созданиякомпонента или службы многократного использования. Поскольку наша цель — поделиться несколькими декораторами и служебными функциями, удалите эти файлы и создайте файл src/lib/ngx-ngrx-component-store-debug-tools.ts:

Публичный API библиотеки экспортируется через файл src/public-api.ts, так что давайте его обновим. Мы удаляем существующие экспорты и экспортируем только файл, созданный на предыдущем шаге:

Мы также расширяем файл projects/ngx-ngrx-component-store-debug-tools/package.json, добавляя атрибуты description, repository, keywords, author, license и bugs:

Зависимости и одноранговые зависимости

Наша библиотека имеет следующие зависимости:

tslib — добавляется генератором, так как это необходимо для работы библиотеки Angular
recursive-diff и rxjs

Как правило, мы должны добавлять наши зависимости как одноранговые зависимости. Однако два менеджера пакетов, npm и yarn, по-разному обрабатывают одноранговые зависимости: npm устанавливает их по умолчанию, а yarn — нет.

Поскольку крайне маловероятно, что кто-то использует recursive-diff в приложении Angular, я добавил его в качестве зависимости к package.json, поэтому и npm, и yarn установят этот пакет автоматически.

Если мы хотим добавить пакет recursive-diff в качестве одноранговой зависимости, приложения, использующие нашу библиотеку, должны включить пакет recursive-diff в свой файл packages.json, чтобы наша библиотека работала.

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

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

ng-packagr/dependencies.md в main · ng-packagr/ng-packagr
На практике считается, что зависимости вашей библиотеки объявлены как peerDependencies. В большинстве случаев это…github.com

Зависимости одноранговых узлов
npm — отличный менеджер пакетов. В частности, он очень хорошо обрабатывает подзависимости: если мой пакет зависит от…blog.domenic.me

Внедрение демо-приложения

В каталоге /projects/demo/src/app/card создаем простой компонент карточки с хранилищем компонентов, и используем декораторы из библиотеки. Мы можем просто импортировать нашу библиотеку, а затем использовать ее декораторы:

Файл /tsconfig.json содержит следующие path:

"paths": {      
  "ngx-ngrx-component-store-debug-tools": [        
    "dist/ngx-ngrx-component-store-debug-tools"      
  ]    
},

Таким образом, по умолчанию import { LogUpdater, LogEffect } from "ngx-ngrx-component-store-debug-tools" импортирует встроенную версию библиотеки из каталога dist/ngx-ngrx-component-store-debug-tools.

Я предлагаю изменить путь к файлу projects/ngx-ngrx-component-store-debug-tools/src/public-api.ts, чтобы нам не пришлось собирать библиотеку перед запуском демо-приложения:

"paths": {      
  "ngx-ngrx-component-store-debug-tools": [        
    "projects/ngx-ngrx-component-store-debug-tools/src/public-api.ts"      
  ]    
},

Применяя этот параметр, если мы изменим исходный код библиотеки, демонстрационное приложение автоматически перекомпилируется.

Сборка библиотеки и запуск демо-приложения

Мы создаем нашу библиотеку с помощью команды ng build ngx-ngrx-component-store-debug-tools, она создает библиотеку в каталоге dist/ngx-ngrx-component-store-debug-tools.

Если путь ngx-ngrx-component-store-debug-tools в файле tsconfig.json указывает на собранную библиотеку, мы должны пересобирать библиотеку после каждого изменения исходного кода. Однако мы можем автоматизировать этот процесс, применив команду ng build ngx-ngrx-component-store-debug-tools --watch, она автоматически перестраивает нашу библиотеку при изменении исходного кода.

Используйте команду ng serve demo для запуска демонстрационного приложения.

Публикация библиотеки

Прежде чем опубликовать библиотеку, я создал учетную запись npmjs.org здесь. Я настроил двухфакторную аутентификацию и вошел в командную строку с помощью команды npm login.

Затем я перешел в каталог dist/ngx-ngrx-component-store-debug-tools и опубликовал библиотеку с помощью команды npm publish.

Если я хочу обновить свою уже опубликованную библиотеку, я обновляю номер версии пакета в файле projects/ngx-ngrx-component-store-debug-tools/package.json, затем собираю и публикую пакет.

Запуск демо-приложения на StackBlitz

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

StackBlitz плохо справляется с многопроектными рабочими пространствами Angular.
демо содержит TailwindCSS, но компоненты внутри приложения были показаны без каких-либо стилейна StackBlitz

Чтобы обойти первую проблему (многопроектные рабочие пространства), я создал однопроектное рабочее пространство, применив команду ng new ngx-ngrx-component-store-debug-tools-demo, и скопировал в него демонстрационное приложение из каталога project/demo/src. Вы можете найти его полный исходный код здесь.

Файл проекта package.json ссылается на библиотеку как на простую зависимость:

{  
  "name": "ngx-ngrx-component-store-debug-tools-demo",
...
  "dependencies": {
...
    "ngx-ngrx-component-store-debug-tools": "^0.0.6",
...
  },
...
}

Что касается второй проблемы, то для того, чтобы TailwindCSS работал на StackBlitz, я добавил в файл index.html следующий тег <script>:

<!doctype html>
<html lang="en">
  <head>
...
    <!-- We need this on StackBlitz -->
    <script src="https://cdn.tailwindcss.com"></script>
...
  </head>
  <body>
...
  </body>
</html>

🎉Ура!

Итак, теперь у нас есть полностью работающая, опубликованная библиотека Angular, неплохо, не правда ли? Я призываю вас повторить мой процесс, показанный выше! Дайте мне знать, если вы столкнулись с какими-либо проблемами или знаете какие-либо хитрости, было бы здорово дополнить эту статью дополнительными советами и советами!

👨‍💻Об авторе

Меня зовут Gergely Szerovay, я работаю руководителем отдела фронтенд-разработки. Преподавание (и изучение) Angular — одна из моих страстей. Я ежедневно просматриваю контент, связанный с Angular — статьи, подкасты, выступления на конференциях и так далее.

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

И если вы недавно видели хорошую статью, твит или другой ресурс, связанный с Angular, сообщите мне об этом здесь, в комментариях, или отправьте мне сообщение в Twitter! Возможно, я расскажу об этом в следующем выпуске Angular Addicts!

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