Экосистема Parcel строится не только вокруг самого сборщика, но и вокруг расширений, позволяющих изменять практически любой этап обработки проекта. Плагины используются для трансформации файлов, оптимизации ресурсов, генерации артефактов сборки, настройки упаковки и интеграции сторонних инструментов.
Публикация собственного плагина в npm превращает локальное решение в полноценный повторно используемый пакет, который может устанавливаться в любых проектах через стандартные механизмы Node.js. Грамотно опубликованный пакет обеспечивает:
Перед публикацией рекомендуется организовать проект по общепринятым правилам npm-пакетов.
Типичная структура:
parcel-transformer-example/
├── src/
│ └── Transformer.js
├── package.json
├── README.md
├── LICENSE
├── CHANGELOG.md
└── .gitignoreДля более крупных плагинов структура может быть расширена:
parcel-transformer-example/
├── src/
├── tests/
├── examples/
├── docs/
├── package.json
├── README.md
└── LICENSEНаличие понятной структуры существенно упрощает поддержку и развитие проекта.
Файл package.json является основным источником
информации о пакете.
Пример конфигурации:
{
"name": "parcel-transformer-example",
"version": "1.0.0",
"description": "Example Parcel transformer plugin",
"main": "src/Transformer.js",
"keywords": [
"parcel",
"parcel-plugin",
"transformer"
],
"author": "Developer Name",
"license": "MIT"
}Особое значение имеют следующие поля:
Имя публикуемого пакета.
{
"name": "parcel-transformer-example"
}Имя должно быть уникальным в реестре npm.
Текущая версия пакета.
{
"version": "1.0.0"
}Используется семантическое версионирование (SemVer).
Краткое описание назначения плагина.
{
"description": "Transformer for custom file format"
}Ключевые слова помогают находить пакет через поиск npm.
{
"keywords": [
"parcel",
"plugin",
"transformer"
]
}Указывает лицензию распространения.
{
"license": "MIT"
}Сообщество Parcel придерживается определённых правил именования.
parcel-transformer-*Примеры:
parcel-transformer-sass
parcel-transformer-svg
parcel-transformer-customparcel-resolver-*Примеры:
parcel-resolver-alias
parcel-resolver-customparcel-optimizer-*Примеры:
parcel-optimizer-images
parcel-optimizer-cssparcel-reporter-*Примеры:
parcel-reporter-build-stats
parcel-reporter-logsСледование этим соглашениям облегчает поиск и понимание назначения пакета.
Плагин должен явно указывать совместимость с Parcel.
Чаще всего используется раздел peerDependencies.
{
"peerDependencies": {
"@parcel/core": "^2.0.0"
}
}Такой подход позволяет использовать версию Parcel, установленную в проекте пользователя.
Дополнительно можно добавить зависимость для разработки:
{
"devDependencies": {
"@parcel/core": "^2.15.0"
}
}Плагин должен экспортировать объект соответствующего типа.
Пример Transformer:
const { Transformer } = require('@parcel/plugin');
module.exports = new Transformer({
async transform({ asset }) {
return [asset];
}
});Точка входа должна быть указана в package.json.
{
"main": "src/Transformer.js"
}README является основной документацией пакета.
Минимальный набор разделов:
# parcel-transformer-example
## Installation
npm install parcel-transformer-example
## Usage
...
## Options
...
## LicenseКачественный README обычно включает:
Большинство открытых проектов используют лицензию MIT.
Пример:
MIT License
Copyright (c) 2025
...Отсутствие лицензии создаёт юридическую неопределённость относительно использования пакета.
Не все файлы проекта должны попадать в npm.
Для ограничения содержимого используется поле files.
{
"files": [
"src",
"README.md",
"LICENSE"
]
}В пакет не будут включены:
tests/
examples/
.git/
.github/Такой подход уменьшает размер публикуемого архива.
Перед отправкой пакета рекомендуется проверить итоговый набор файлов.
Команда:
npm packБудет создан архив:
parcel-transformer-example-1.0.0.tgzСодержимое можно проверить:
tar -tf parcel-transformer-example-1.0.0.tgzЭто позволяет обнаружить случайно включённые конфиденциальные файлы или отсутствующие ресурсы.
Перед публикацией требуется учётная запись npm.
Проверка авторизации:
npm whoamiЕсли пользователь не авторизован:
npm loginПосле выполнения команды потребуется указать:
Username
Password
EmailУспешная авторизация сохраняется локально.
После подготовки проекта выполняется публикация:
npm publishЕсли имя свободно, пакет будет опубликован в общем реестре npm.
После завершения публикации пакет становится доступным для установки:
npm install parcel-transformer-exampleМногие разработчики используют пространство имён.
Пример имени:
@company/parcel-transformer-exampleКонфигурация:
{
"name": "@company/parcel-transformer-example"
}Для публичной публикации требуется указать:
npm publish --access publicИначе пакет будет считаться приватным.
Версии публикуются согласно SemVer.
Формат:
MAJOR.MINOR.PATCHПример:
1.4.2Исправления ошибок.
1.0.0 → 1.0.1Новый функционал без нарушения совместимости.
1.0.0 → 1.1.0Несовместимые изменения API.
1.0.0 → 2.0.0npm предоставляет встроенные команды изменения версии.
Патч-релиз:
npm version patchМинорный релиз:
npm version minorМажорный релиз:
npm version majorПосле выполнения изменяются:
После изменения версии выполняется повторная публикация:
npm publishКаждая версия публикуется только один раз.
Например:
1.0.0Нельзя заменить повторной публикацией.
Вместо этого публикуется новая версия:
1.0.1npm поддерживает каналы распространения.
Публикация бета-версии:
npm publish --tag betaУстановка:
npm install package-name@betaПример версий:
2.0.0-beta.1
2.0.0-beta.2
2.0.0-beta.3После стабилизации выпускается:
2.0.0Получение информации:
npm view parcel-transformer-exampleПроверка версии:
npm view parcel-transformer-example versionПросмотр зависимостей:
npm view parcel-transformer-example dependenciesЭти команды позволяют убедиться в корректности публикации.
При развитии плагина необходимо учитывать существующих пользователей.
Нежелательные изменения:
Для устаревающих возможностей рекомендуется использовать предупреждения:
console.warn(
'Option "legacyMode" is deprecated'
);С последующим удалением в следующей мажорной версии.
История изменений помогает пользователям отслеживать развитие пакета.
Пример:
# Changelog
## 1.2.0
### Added
- New transformer API
### Fixed
- Asset cache issue
## 1.1.0
### Added
- Source map supportПоддержание актуального журнала изменений считается хорошей практикой для всех публичных плагинов.
Публикация может выполняться автоматически после создания релиза.
Пример workflow:
name: Publish
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
registry-url: https://registry.npmjs.org
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}Такой подход исключает ручные действия и снижает вероятность ошибок.
Ошибка:
{
"main": "index.js"
}При отсутствии файла:
index.jsпакет становится неработоспособным.
Ошибка приводит к конфликтам версий Parcel.
Неправильно:
{
"dependencies": {
"@parcel/core": "^2.0.0"
}
}Предпочтительно:
{
"peerDependencies": {
"@parcel/core": "^2.0.0"
}
}Часто случайно публикуются:
node_modules/
.env
coverage/Для предотвращения используются:
{
"files": [
"src"
]
}или файл:
.npmignoreДаже технически качественный плагин редко используется без примеров настройки и описания возможностей.
Качественный npm-пакет обычно обладает следующими характеристиками:
Соблюдение этих принципов позволяет превратить локальный плагин Parcel в полноценный инструмент, пригодный для использования в реальных проектах и распространения через экосистему npm.