Опубликуйте компонент VueJS на NPM (это не страшно)

В этом руководстве описаны шаги по упаковке, публикации и версии компонента Vue с использованием vue-cli 3 в NPM и unpkg (для использования непосредственно в браузере).

Примечание: это руководство было написано после публикации моего первого (простого) компонента. Он может не подходить для более сложных случаев, или вы можете найти лучшее руководство. Я обнаружил, что другие руководства экономят на управлении версиями и интеграции с Github или не используют в полной мере vue-cli. В будущем я намерен расширить это руководство, чтобы охватить более сложные случаи.

Шаг 0 - Ваш проект Vue

Этот шаг касается базовой настройки проекта. Не стесняйтесь пропустить шаги, связанные с упаковкой.

Создайте пустой репозиторий на Github.com, установите Vue CLI и запустите свой проект.

npm install -g @vue/cli
vue create my-project
# use default options
cd my-project
git remote add origin https://github.com/username/my-project.git
git push -u origin master
npm run serve

Создавайте свой компонент так же, как и в противном случае. Вы можете добавить ЛИЦЕНЗИОННЫЙ файл, и мы примем следующую файловую структуру.

package.json
readme.md
LICENSE
src/
  App.vue
  MyComponent.vue
  main.js
dist/
.gitignore

Шаг 1. Настройте файл package.json

Издание библиотеки ближе к бухгалтерии, чем к ракетостроению. Правильная настройка и документирование вашей библиотеки окупается. Какой в этом смысл, если другие не могут его найти или не могут понять? Или если вы не исправляете ошибки из-за слишком больших накладных расходов на обновление пакета?

Отредактируйте свой package.json, чтобы он выглядел так:

{
"name": "my-component",
"version": "0.1.0",
"description": "Describes my component",
"author": {
  "name": "My Name",
  "email": "[email protected]"
},
"repository": "https://github.com/username/project",
"bugs": "https://github.com/username/vproject/issues",
"keywords": ["words", "go", "here"],
"license": "MIT",
"private": false,
"files": ["dist"],
"scripts": {
  "serve": "vue-cli-service serve",
  "build": "vue-cli-service build",
  "build:npm": "vue-cli-service build --target lib --name myComponent src/MyComponent.vue",
},
"main": "dist/myComponent.umd.js",
"unpkg": "dist/myComponent.umd.min.js",
...
}

Быстрый просмотр свойств:

name - имя пакета, которое будет отображаться в NPM.
версия - семантическая версия. Мы доберемся до этого на шаге 3.
описание, автор, репозиторий, ошибки, ключевые слова, лицензия - Дополнительная информация для использования в NPM.
частный - true или false. NPM попытается опубликовать публично, и это не удастся, если у вас установлен частный пакет.
файлы - определяет, какие файлы и папки будут опубликованы NPM. Если этот параметр не установлен, он будет искать вдохновение в файле .gitignore (или .npmignore, но у нас его нет). Это приведет к публикации вашего исходного кода, а не собранных пакетов. Ровно противоположное тому, что мы хотим.
scripts.build:npm - это сценарий сборки для пакета, работающий на vue-cli-service: --target lib устанавливает цель сборки для библиотеки, а --name myComponent устанавливает базовое имя файла.

Попытка не повредит, так что поехали:

npm run build:npm
  # Building for production as library (commonjs,umd,umd-min)...

В папке dist теперь должны быть следующие файлы:

myComponent.common.js
myComponent.common.js.map
myComponent.umd.js
myComponent.umd.js.map
myComponent.umd.min.js
myComponent.umd.min.js.map

Вы можете опубликовать это в NPM и перейти к следующему испытанию в своей жизни. Однако нам нужно сделать еще несколько шагов, чтобы сделать это правильно.

Ссылки для шага 1:

Шаг 2 - Добавьте правильный файл readme

Правильный readme очень важен. Исследования показывают, что 65% потенциальных пользователей будут строить свое мнение о библиотеке на основе readme, а 90% расстроятся, если не смогут найти инструкции по ее установке и использованию [я полностью это придумал].

Файл readme будет опубликован вместе с вашим пакетом на npmjs.com и на вашей странице Github и должен, для библиотеки, отвечать как минимум на следующие вопросы:

Можете ли вы сказать мне, какую проблему он решает в двух предложениях?
Как мне его установить?
Как мне использовать / взаимодействовать с ним?
Какая лицензия применяется?

И по желанию:

Вы можете показать мне примеры работы?
Как это работает под капотом?
Статус проекта: сборки / тесты?
Как я могу внести свой вклад?
Какие технологии были использованы?

Не увлекайтесь большим количеством контента или иллюстраций. Есть ценность в наличии «сканируемого» документа, и что-либо, кроме краткого readme, вероятно, лучше использовать в реальной документации.

Шаг 3 - Управление версиями

Это то, что я все откладывал ради собственных проектов, но он оказался действительно удобным и легким. NPM даже автоматически интегрируется с тегами Git, поэтому вам не нужно дублировать усилия или даже рисковать рассинхронизацией номеров версий.

# Make sure the working directory is clean
git add -A
git commit -m "Changes"
# Increment semantic version with npm
npm version patch -m "Bump the version number"

Команда npm version незаметно выполняет два действия:

Вставьте version в package.json согласно правилам семантического версионирования.
Создайте аннотированный тег в Git.

Используйте следующую команду, чтобы подтвердить, что тег был создан, и отправить все коммиты, включая аннотированные теги, в ваш репозиторий.

git tag
# v0.1.1
git push --follow-tags

Шаг 4 - Опубликуйте и используйте

Для публикации на npmjs.com вам понадобится бесплатная учетная запись npm. Создайте его из командной строки:

npm adduser

Войдите и подтвердите свой адрес электронной почты, чтобы настроить

npm login

Публикация теперь проста:

npm run build:npm
npm publish

Он должен быть там (почти мгновенно), чтобы его мог использовать весь мир: npmjs.com/package/<my-component> Поиск на npmjs.com также должен немедленно найти его.

Более того, он доступен в CDN, поэтому его можно включать в веб-сайты. Это должен быть основной URL: unpkg.com/<my-component>. Это перенаправит вас в более конкретное место с номером версии. Подстановочный знак latest предоставит вам самую последнюю версию.

Теперь все, что вам нужно сделать, это либо:

npm install my-component

или в браузере:

<script src=”https://unpkg.com/my-component@latest/dist/myComponent.umd.min.js"></script>

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

Я видел библиотеки, которые отправляют в NPM весь исходный код, демонстрационные файлы и т. Д. Пожалуйста, не делайте этого, вы даете NPM дурную репутацию.

Библиотеки предназначены для скомпилированного кода, оптимизированного для производства.
Системы контроля версий (такие как Github) предназначены для базового исходного кода.

Все будет хорошо, если вы настроили “files”: [“dist”] в package.json. Дела идут плохо с плохо настроенным .npmignore или с .gitignore.

Но доступ к исходному коду - это хорошо, правда? Да, но есть способы получше, например, установить "repository" в package.json. Ссылка будет на npmjs.com, и вы сможете увидеть ее в своей системе:

npm show vue repository

Замените vue на любой другой пакет, который хотите проверить. Если они вели бухгалтерию, вы найдете все репозитории.

Реплика: вещи, которые укусили меня в браузере

Названия собственности с заглавной буквы

Самозакрывающиеся теги