Репозиторий для NPM

Типичная ситуация, когда в проекте существует некий модуль который развивается, становится самостоятельным элементом и копируется в другой проект. В каждом проекте модуль обновляется и улучшается, в какой-то момент, становится не понятно, где актуальная версия. Вполне возможно, что в каждом проекте у модуля будут свои модификации, в которые будет достаточно сложно привести в порядок для использования в следующем проекте. Вполне можно ограничиться созданием отдельного репозитория в Гите для модуля, но можно пойти дальше и создать на основе такого модуля npm-пакет. Работать с такими пакетами очень просто, установить и обновить npm-пакет можно с помощью команды.

Инициализация нового проекта

Используйте npm для инициализации нового проекта, команда создаст файл package.json, который будет содержать метаданные о вашем проекте и его зависимостях. Для инициализации, выполните команду:

npm init

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

name реальное название пакета, а не название приложения. Если лень искать адекватное название в общем пространстве имен, можно использовать пространство имен своего аккаунта @hmarketing/test но оно платное
version версия проекта
description описание проекта
main точка входа для пользователей CommonJS, подключение идет за счет команды require("validate-npm-pc"), папку в проекте лучше сделать логически правильную ./cjs/mask.js
module точка входа для пользователей ES, подключение идет за счет команды import from "validate-npm-pc", папку в проекте лучше сделать логически правильную ./esm/mask.js
type определяет тип пакета и то, как Node.js должен интерпретировать файлы с расширением .js. Если файл package.json не содержит этого поля, файлы .js рассматриваются как CommonJS. Значение module указывает Node.js интерпретировать файлы с расширением .js внутри пакета как использующие синтаксис ES
files массив, указывающий какие файлы должны быть включены, когда наш пакет опубликован
keywords список ключевых слов для улучшения поиска нашего пакета на веб сайте NPM
author автор
license тип лицензии
scripts определите команды для создания, выпуска и тестирования проекта
- build этот скрипт компилирует файлы TypeScript в JavaScript, используя tsc запускает две отдельные сборки, используя файлы конфигурации TypeScript, которые мы будем создавать tsconfig.json и tsconfig.cjs.json
- release сценарий сначала запускает build, в случае успеха, публикует изменения, используя changeset publish
- test: запускает наши тесты, используя Jest
devDependencies зависимости, которые нужны для работы нашего модуля в режиме разработки
dependencies зависимости, которые нужны для работы нашего модуля в режиме продакшина, эти зависимости будут установлены при скачивание пакета из NPM хранилищя
peerDependencies зависимости, которые должны быть установлены разработчиком совместно с вашим пакетом

Пример файла package.json:

package.json{
  "name": "название_модуля",
  "version": "1.0.0",
  "description": "описание_модуля",
  "main": "./cjs/mask.js",
  "module": "./esm/mask.js",
  "type": "module",
  "files": [
    "/dist"
  ],
  "scripts": {
    "build": "tsc --project tsconfig.json && tsc --project tsconfig.cjs.json",
    "release": "npm run build && changeset publish",
    "test": "jest"
  },
  "keywords": [
    "ключевые_слова"
  ],
  "author": "hmarketing",
  "license": "ISC",
  "devDependencies": {
    "ts-jest": "^29.1.2",
    "typescript": "^5.4.5"
  },
  "dependencies": {
    "test_hmarketing": "^1.0.0"
  },
  "peerDependencies": {
    "jquery": "^3.7.0"
  }
}

Зависимости

В файле package.json присутствуют две секции dependencies и devDependencies. В первом перечислены зависимости, которые требуются для работы пакета в продакшене, во втором только во время разработки.

Это все прекрасно пока мы создаем приложение, но когда мы пишем библиотеку, мы должны учитывать что она будет помещена в целевой проект. В нем скорее всего уже будут установлены зависимости, которые мы тоже используем. Если мы оставим эти зависимости внутри своего dependencies, могут возникнуть всякие неприятности типа использования двух библиотек в одном приложении. Поэтому я переношу все зависимости из dependencies в devDependencies, а которые нам нужны для продакшена в peerDependencies.

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

Для начала нужно пройти регистрацию на npmjs.com, сделать это можно из терминала командой:

npm adduser

Если же учетная запись у вас уже есть, то нужно авторизироваться в терминале:

npm login

Проверить под какой учетной записью вы находитесь можно с помощью команды:

npm whoami

Теперь можно публиковать NPM-пакет, после введения команды, ваш пакет отправиться на сервера NPM и будет доступен для подключения к проектам:

npm publish

Обновление NPM-пакета

Без обновлений модулей никуда. Для того чтобы правильно обновить пакет, вам нужно:

Внести изменения в код
Обновить версию пакета командой npm version [ major | minor | patch ]
Опубликовать новую версию пакета командой npm publish

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

Команда npm version patch, увеличит версию пакета например, с 1.0.0 до 1.0.1. Незначительные исправления мелких ошибок:

npm version patch

Команда npm version minor, увеличит версию пакета например, с 1.0.0 до 1.1.0. Добавления нового функционала, который не влияет на уже существующий функционал:

npm version minor

Команда npm version major, увеличит версию пакета например, с 1.0.0 до 2.0.0. Модификация пакета без обратной совместимости с предыдущей версией. Разработчик поймет что простое обновление пакета может что-то сломать и изучит вопрос правильного обновления на новую мажорную версию:

npm version major

Удаление NPM-пакета

Удаление NPM-пакетов является очень плохим тоном, от пакетов могут зависеть проекты других пользователей. Однако, если после публикации пакета командой npm publish прошло менее 24 часов, публикацию можно отменить командой npm unpublish:

npm unpublish название_пакета@веосия_пакета

Удалить пакет полностью, можно из интерфейса личного кабинета на сайте NPM.

Если необходимо удалить пакет с момента публикации которого прошло более 24 часов, напишите в поддержку, указав причину удаления пакета. Пакет будет помечен как @deprecated и исчезнет из вашего профиля.