Установка локального модуля через npm: пошаговый гайд

Быстрый ответ

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

npm link

После этого привяжите модуль к вашему проекту с помощью:

npm link <название-модуля>

Название модуля в package.json должно быть уникальным, чтобы избежать конфликтов. Эта процедура схожа с глобальной установкой модуля, но использует символические ссылки.

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

npm install /путь/к/модулю

В этом случае модуль будет добавлен в node_modules и будет доступен только в пределах вашего проекта.

Инновационные решения и свободомыслия

Peer-зависимости: друг или враг?

Если в локальном модуле имеются peer-зависимости, применение npm link может вызвать трудности при разрешении этих зависимостей. Ссылка может побудить Node.js искать зависимости там, куда не следует.

В этой ситуации локальный модуль лучше указывать напрямую в package.json через file::

"dependencies": {
  "<название-модуля>": "file:../путь/к/модулю"
}

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

Непреклонные и непримиримые

Подробнее об этом расскажет наш спикер на видео

Жизнь локального модуля в мире непрерывных изменений

Если локальный модуль часто обновляется, npm link может облегчить процесс разработки. Однако нужно тщательно отслеживать состояние peer-зависимостей.

Безопасное использование npm link: руководство

Перед тем как использовать npm link, выполните npm install в модуле, чтобы подтянуть все его зависимости, затем выполните эту же команду в проекте, чтобы устранить возможные конфликты версий библиотек.

Когда npm link уже слишком

При работе с большим числом локальных модулей действительно целесообразно использовать инструменты для работы с многомодульными репозиториями (Monorepo), такие как Lerna или Yarn Workspaces.

Как Node.js разрешает модули?

Понимание механизма разрешения модулей в Node.js с помощью таких инструментов, как npm ls, помогает избежать ошибок при работе с локальными модулями.

Визуализация

Визуализируйте ваш проект как склад, а локальные модули – как некий товар.

Добавление "товара" к "ассортименту":

// Мы добавляем в наш проект "необычный товар"
const specialProduct = require('./путь/к/локальному/модулю');

Перед использованием этого "товара" наш проект был как 🍲, а теперь – как 🍲🍄.

Приятного "потребления"!

Лучшие практики и скрытые подводные камни

Контроль версий: Защита кода

При работе с локальными модулями используйте .gitignore для исключения символических ссылок из репозитория.

Переключение между npm и yarn

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

Continuous Integration: Бдительные стражи

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

Полезные материалы

1. npm-link | npm Docs — основы создания ссылок для локальной разработки.
2. Modules: CommonJS modules | Node.js v21.6.1 Documentation — описание модульной системы Node.js.
3. node.js – Local dependency in package.json – Stack Overflow — обсуждение управления локальными зависимостями в package.json.
4. Creating Node.js modules | npm Docs — руководство по созданию и управлению модулями Node.js с помощью npm.
5. How to Use npm as a Build Tool – Keith Cirkel — о применении npm как инструмента для сборки проектов.
6. Documentation | Lerna — инструмент для управления многомодульными репозиториями.
7. Workspaces | Yarn — об особенностях работы с многомодульными репозиториями при использовании Yarn.