Публикация в npm и семантическое версионирование

Перед публикацией всегда выполняйте npm publish --dry-run. Эта команда имитирует публикацию, фактически ничего не загружая, и показывает, какие именно файлы будут включены, их размеры и содержимое архива пакета. Это помогает выявить распространённые ошибки, например случайное включение исходных файлов или отсутствие каталога dist.

Управляйте публикуемым содержимым с помощью поля files в package.json: "files": ["dist", "README.md"]. Такой подход с белым списком безопаснее, чем .npmignore (это чёрный список, и конфиденциальные файлы могут случайно попасть в пакет, если вы забудете добавить их в исключения). Всегда включайте dist, объявления типов и документацию. Никогда не включайте src, тесты или node_modules.

Пакеты npm используют семантическое версионирование (semver): MAJOR.MINOR.PATCH. Увеличивайте MAJOR при несовместимых изменениях (удалении свойств, изменении сигнатур API). Увеличивайте MINOR при добавлении обратно совместимых возможностей (новых компонентов, новых необязательных свойств). Увеличивайте PATCH при исправлении обратно совместимых ошибок. Версия 0.x.x считается нестабильной: при ней может сломаться что угодно.

Идентификаторы предрелиза показывают, что версия ещё не готова для использования в рабочей среде: 1.0.0-alpha.1 — ранние экспериментальные сборки, 1.0.0-beta.2 — версии с полной функциональностью, но возможными ошибками, а 1.0.0-rc.1 (кандидат на выпуск) — версии, готовые к финальному тестированию. Публикуйте предрелизы с помощью npm publish --tag beta, чтобы они не стали версией, устанавливаемой по умолчанию.

Changesets — стандартный инструмент для управления версиями пакетов и журналами изменений в библиотеках компонентов. Рабочий процесс выглядит так: участники проекта выполняют yarn changeset add, чтобы зафиксировать изменения и их тип (мажорный, минорный или исправляющий). Система непрерывной интеграции выполняет yarn changeset version, чтобы обновить версии пакетов. При публикации выполняется yarn changeset publish, отправляющая пакеты в npm.

Changesets автоматически создаёт и поддерживает CHANGELOG.md на основе файлов с описанием изменений, добавленных участниками проекта. Каждая запись содержит номер версии, дату выпуска и описание изменений. В результате формируется понятная человеку история каждой версии без необходимости вручную поддерживать журнал изменений.

semantic-release — полностью автоматизированный инструмент управления версиями, который определяет следующую версию по сообщениям коммитов, оформленным по соглашению (feat: → minor, fix: → patch, BREAKING CHANGE: → major). Он обновляет номер версии, создаёт журнал изменений и публикует пакет в npm — всё это запускается системой непрерывной интеграции после слияния в ветку main. Ручное управление версиями не требуется.

Пакеты без области имён (my-component) всегда являются публичными. Пакеты с областью имён (@myorg/my-component) по умолчанию имеют ограниченный (частный) доступ — опубликуйте их как публичные с помощью npm publish --access public. Для ограниченных пакетов требуется платная учётная запись npm или организация. Перед первой публикацией проверьте параметры доступа.

Подтверждение происхождения в npm связывает опубликованный пакет с конкретным git-коммитом проверяемым способом. Включите эту возможность с помощью npm publish --provenance в GitHub Actions. Пользователи могут проверить, что установленный ими пакет был собран именно из исходного коммита, указанного на странице реестра npm. Это значительно повышает безопасность цепочки поставок.

Если версия содержит критическую ошибку или несовместимое изменение, пометьте её как устаревшую: npm deprecate your-package@1.2.3 "Security vulnerability, upgrade to 1.2.4". npm показывает предупреждение об устаревшей версии всем, кто устанавливает эту версию. Версия не удаляется (npm по умолчанию не удаляет опубликованные версии), но пользователям предлагается обновиться.

Пакеты с областью имён используют формат @scope/package-name. Область имён обычно соответствует вашему имени пользователя в npm или названию организации. Такие пакеты показывают, кто их сопровождает, и предотвращают конфликты имён с пакетами без области имён. Используйте их для частных пакетов и пакетов с открытым исходным кодом, связанных с вашей организацией.

Согласно семантическому версионированию, в каких случаях следует увеличивать номер версии MAJOR?

Используйте npm publish --dry-run для предварительного просмотра, а поле files — для управления публикуемым содержимым. Семантическое версионирование: MAJOR — для несовместимых изменений, MINOR — для новых возможностей, PATCH — для исправлений. В предрелизах используются теги -alpha/-beta/-rc. Changesets автоматизирует управление версиями и создание CHANGELOG для библиотек, разрабатываемых совместно. semantic-release автоматизирует выпуск на основе согласованных сообщений коммитов. Включайте --provenance для повышения безопасности цепочки поставок. Помечайте версии с ошибками как устаревшие с помощью npm deprecate.