Публикация в npm

Для публикации пакета на npm необходимо корректно подготовить проект. Первым шагом является создание файла package.json, который содержит метаданные проекта: имя пакета, версию, описание, ключевые зависимости и скрипты сборки. В Quasar проекты создаются через CLI командой quasar create <project-name>, после чего можно адаптировать package.json под npm-публикацию.

Основные поля для публикации:

  • name – уникальное имя пакета в npm. Не должно содержать пробелов, использовать только строчные буквы, дефисы или символы подчеркивания.
  • version – версия пакета по семантическому версионированию.
  • main – точка входа для CommonJS, обычно dist/index.cjs.js.
  • module – точка входа для ES-модулей, например dist/index.esm.js.
  • files – массив файлов или папок, которые будут включены в публикацию. Рекомендуется указывать только необходимые файлы, исключая исходники тестов и конфигурации.
  • scripts – скрипты сборки и подготовки пакета, например:
"scripts": {
  "build": "quasar build",
  "prepublishOnly": "npm run build"
}

Сборка библиотеки Quasar для npm

Quasar по умолчанию ориентирован на создание приложений, но поддерживает создание библиотек. Важно подготовить сборку так, чтобы она была совместима с различными системами модулей:

  1. Настройка quasar.conf.js В quasar.conf.js указывается экспортируемая библиотека:
build: {
  vueRouterMode: 'hash',
  extendWebpack(cfg) {
    cfg.output.libraryTarget = 'umd';
  },
  env: {
    NODE_ENV: JSON.stringify(process.env.NODE_ENV)
  }
}

  1. Выбор формата сборки Для npm рекомендуется использовать UMD (универсальный модуль) или ESM (ES Modules). UMD позволяет подключать библиотеку в браузере через тег <script> или через Node.js, а ESM облегчает интеграцию с современными сборщиками вроде Webpack или Vite.

  2. Подготовка файлов для публикации Обычно в dist/ попадает уже минифицированная версия библиотеки. Следует включить в package.json только необходимые файлы через поле "files":

"files": [
  "dist/",
  "README.md",
  "LICENSE"
]

Тестирование пакета перед публикацией

Перед загрузкой на npm важно убедиться, что пакет работает корректно:

  • Использовать локальную установку через npm pack для создания .tgz архива.
  • Установить локально в тестовом проекте: npm install ../<package-name>-<version>.tgz.
  • Проверить доступность всех экспортируемых модулей и компонентов Quasar.

Дополнительно рекомендуется проверять работу с разными версиями Vue, если библиотека зависит от конкретной версии Quasar.

Публикация на npm

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

npm publish --access public

Особенности:

  • Поле "private": true в package.json запрещает публикацию, необходимо его удалить или установить false.
  • Для scoped-пакетов (@scope/package-name) требуется использовать --access public.
  • Публикуется только текущая версия; для обновления нужно увеличить версию в package.json и повторить публикацию.

Управление версиями и обновлениями

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

  • Major – несовместимые изменения API.
  • Minor – добавление функционала без нарушения совместимости.
  • Patch – исправления багов.

Для автоматизации можно использовать npm version <major|minor|patch>, что одновременно обновляет package.json и создает Git-тег.

Документация и описание пакета

Поле README.md должно содержать:

  • Описание функционала библиотеки.
  • Примеры использования компонентов Quasar.
  • Инструкции по установке:
npm install <package-name>
  • Подробности по конфигурации и доступным методам.

Дополнительно можно указать поле "keywords" для улучшения поиска пакета на npm и "license" для корректного указания лицензии.

Поддержка Quasar компонентов и плагинов

Если библиотека включает компоненты Quasar, следует обеспечить:

  • Импорт необходимых CSS и JS ресурсов через Quasar import в библиотеке.
  • Возможность Tree-shaking, чтобы потребители могли подключать только используемые модули.
  • Совместимость с Vue 3, так как Quasar 2.x основан на Vue 3.

Корректная организация структуры модулей позволяет интегрировать библиотеку в приложения без конфликтов и избыточного кода.

Настройка CI/CD для публикации

Для автоматизации публикации пакета можно использовать GitHub Actions или другие CI/CD системы:

  • Проверка сборки через quasar build.
  • Тестирование на локальном проекте.
  • Автоматическое увеличение версии и публикация на npm при push в основную ветку.

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

Итоговая структура проекта для npm

Пример рекомендуемой структуры:

my-quasar-lib/
├─ src/
│  ├─ components/
│  └─ index.js
├─ dist/
├─ package.json
├─ quasar.conf.js
├─ README.md
└─ LICENSE

Эта структура обеспечивает ясность, поддерживает модульность и соответствует стандартам npm для библиотек на базе Quasar.

Оглавление