Публикация плагина в npm

После разработки и тестирования плагина следующим этапом становится его публикация в реестре npm. Размещение пакета в npm позволяет использовать его в любых проектах через стандартные инструменты экосистемы JavaScript, обеспечивая удобную установку, обновление и управление зависимостями.

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

Подготовка структуры проекта

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

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

rollup-plugin-example/
├── src/
│   └── index.js
├── dist/
│   └── index.js
├── test/
├── package.json
├── README.md
├── LICENSE
└── rollup.config.js

Наиболее важными файлами являются:

Файл Назначение
package.json Метаданные пакета
README.md Документация
LICENSE Лицензия
dist/index.js Готовая сборка
package-lock.json Зафиксированные версии зависимостей

Проверка package.json

Основная информация о публикуемом пакете хранится в package.json.

Пример:

{
  "name": "rollup-plugin-example",
  "version": "1.0.0",
  "description": "Example Rollup plugin",
  "main": "dist/index.js",
  "type": "module",
  "keywords": [
    "rollup",
    "rollup-plugin"
  ],
  "author": "John Doe",
  "license": "MIT"
}

Особое внимание следует уделить следующим полям.

name

Имя пакета должно быть уникальным внутри npm.

Примеры:

{
  "name": "rollup-plugin-svg-optimizer"
}

или

{
  "name": "@company/rollup-plugin-svg-optimizer"
}

Scoped-пакеты позволяют публиковать пакеты внутри пространства имён организации или пользователя.

version

Версия должна соответствовать правилам SemVer.

Примеры:

1.0.0
1.2.5
2.0.0

Структура:

MAJOR.MINOR.PATCH

Где:

  • MAJOR — несовместимые изменения;
  • MINOR — новая функциональность;
  • PATCH — исправления ошибок.

description

Краткое описание помогает пользователям понять назначение пакета.

{
  "description": "Rollup plugin for replacing environment variables"
}

keywords

Ключевые слова улучшают поиск пакета в каталоге npm.

{
  "keywords": [
    "rollup",
    "plugin",
    "build",
    "bundler"
  ]
}

Для плагинов Rollup рекомендуется обязательно указывать:

{
  "keywords": [
    "rollup",
    "rollup-plugin"
  ]
}

repository

Полезно указывать адрес репозитория.

{
  "repository": {
    "type": "git",
    "url": "https://github.com/user/rollup-plugin-example.git"
  }
}

Это позволяет пользователям быстро находить исходный код.

homepage

Ссылка на домашнюю страницу проекта.

{
  "homepage": "https://github.com/user/rollup-plugin-example"
}

bugs

Секция для отправки сообщений об ошибках.

{
  "bugs": {
    "url": "https://github.com/user/rollup-plugin-example/issues"
  }
}

Указание экспортов

Современные пакеты всё чаще используют поле exports.

Пример:

{
  "exports": {
    ".": "./dist/index.js"
  }
}

Если предусмотрены дополнительные точки входа:

{
  "exports": {
    ".": "./dist/index.js",
    "./utils": "./dist/utils.js"
  }
}

Поле exports позволяет явно контролировать публичное API пакета.

Настройка типов TypeScript

Если плагин предоставляет декларации типов, необходимо указать их расположение.

{
  "types": "dist/index.d.ts"
}

Пользователи TypeScript получат автодополнение и проверку типов автоматически.

Ограничение публикуемых файлов

По умолчанию npm публикует практически всё содержимое каталога.

Чтобы избежать публикации лишних файлов, используется поле files.

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

После этого npm включит только перечисленные файлы.

Использование .npmignore

Альтернативный вариант — файл .npmignore.

Пример:

test/
coverage/
.vscode/
.github/

Однако поле files считается более надёжным и предсказуемым способом контроля содержимого пакета.

Подготовка README.md

README является главным источником информации о плагине.

Качественная документация обычно содержит:

Назначение

# rollup-plugin-example

Plugin for transforming custom assets.

Установка

npm install rollup-plugin-example

Использование

import example from 'rollup-plugin-example';

export default {
    plugins: [
        example()
    ]
};

Опции

example({
    minify: true
});

Примеры

example({
    include: '**/*.txt'
});

Лицензия

MIT

Хорошая документация часто влияет на популярность пакета не меньше, чем качество кода.

Добавление лицензии

Без лицензии пользователи не всегда понимают условия использования пакета.

Наиболее популярный вариант:

MIT License

Файл:

LICENSE

Поле в package.json:

{
  "license": "MIT"
}

Проверка содержимого публикации

Перед отправкой пакета в реестр полезно проверить, что именно попадёт в архив.

Для этого используется команда:

npm pack

Будет создан архив:

rollup-plugin-example-1.0.0.tgz

Одновременно npm покажет список файлов, которые войдут в пакет.

Локальная проверка архива

Полученный архив можно установить локально.

npm install ./rollup-plugin-example-1.0.0.tgz

Такой подход помогает убедиться, что пакет будет работать после публикации.

Создание аккаунта npm

Для публикации необходим аккаунт npm.

После регистрации выполняется авторизация:

npm login

Консоль запросит:

Username:
Password:
Email:

После успешной авторизации данные будут сохранены локально.

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

npm whoami

Первая публикация

После завершения подготовки выполняется команда:

npm publish

Если имя пакета свободно, публикация будет успешно завершена.

Для scoped-пакетов может потребоваться:

npm publish --access public

Например:

npm publish --access public

для пакета:

{
  "name": "@mycompany/rollup-plugin-example"
}

Проверка опубликованного пакета

Информация о пакете доступна через:

npm view rollup-plugin-example

Также можно проверить установку:

npm install rollup-plugin-example

Если пакет устанавливается без ошибок, публикация выполнена корректно.

Обновление версии

npm запрещает публиковать одну и ту же версию повторно.

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

Автоматическое увеличение PATCH:

npm version patch

Результат:

1.0.0 → 1.0.1

Увеличение MINOR:

npm version minor

Результат:

1.0.0 → 1.1.0

Увеличение MAJOR:

npm version major

Результат:

1.0.0 → 2.0.0

После изменения версии выполняется:

npm publish

Использование prepublishOnly

Перед публикацией часто требуется выполнить сборку проекта.

Для этого используется скрипт:

{
  "scripts": {
    "build": "rollup -c",
    "prepublishOnly": "npm run build"
  }
}

При запуске:

npm publish

npm автоматически выполнит:

npm run build

и только затем опубликует пакет.

Автоматическая проверка тестов

Дополнительно можно запускать тесты.

{
  "scripts": {
    "test": "vitest",
    "prepublishOnly": "npm test && npm run build"
  }
}

Если тесты завершатся ошибкой, публикация будет отменена.

Публикация через CI/CD

Во многих проектах публикация выполняется автоматически после создания тега.

Пример последовательности:

  1. Изменение версии.
  2. Создание Git-тега.
  3. Отправка изменений в репозиторий.
  4. Запуск CI.
  5. Сборка проекта.
  6. Выполнение тестов.
  7. Публикация в npm.

Пример тега:

git tag v1.2.0
git push origin v1.2.0

После появления тега система непрерывной интеграции может автоматически выпустить новую версию пакета.

Публикация бета-версий

Для тестирования новых функций используются теги npm.

Публикация:

npm publish --tag beta

Установка:

npm install rollup-plugin-example@beta

Это позволяет распространять экспериментальные версии без влияния на стабильный релиз.

Управление тегами

Просмотр тегов:

npm dist-tag ls rollup-plugin-example

Добавление нового тега:

npm dist-tag add rollup-plugin-example@2.0.0 next

Результат:

latest -> 1.5.0
next -> 2.0.0

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

Полное удаление опубликованных пакетов сильно ограничено политикой npm.

Для устаревших пакетов чаще используется пометка:

npm deprecate rollup-plugin-example "Use rollup-plugin-new instead"

При установке пользователи увидят предупреждение.

Рекомендации по именованию Rollup-плагинов

Для публичных плагинов распространён формат:

rollup-plugin-*

Примеры:

rollup-plugin-svg
rollup-plugin-assets
rollup-plugin-config

Для официальных или корпоративных решений часто используются scoped-пакеты:

@company/rollup-plugin-assets
@company/rollup-plugin-images

Такой подход снижает вероятность конфликтов имён и упрощает управление экосистемой пакетов внутри организации.

Типичный процесс выпуска новой версии

Последовательность действий обычно выглядит следующим образом:

npm test
npm run build
npm version patch
git push
git push --tags
npm publish

Либо при автоматизированном релизе:

npm test
npm run build
git tag v1.3.0
git push origin v1.3.0

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

Оглавление