📦компонент vue, публикующий лучшие практики npm

предисловие

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

Во-первых, публикацию компонента vue в npm можно разделить на две части:

Опубликовать пакет на npm
Компоненты пакета vue

Если вы считаете, что статья «слишком длинная для чтения», вы можете напрямую использовать инструменты разработки:vue-sfc-cli, интегрируйте travis ci, быстро опубликуйте npm.

npm отправить пакет

Некоторые люди говорят, что отправка пакета — это не однострочная команда, верно?

npm publish

Да, но также игнорируйте следующие пункты:

Сначала вы должныnpmjsЗарегистрируйте аккаунт на
просмотреть свой.npmrcнастройки, убедитесь, что ваш реестрwww.npmjs.com/, а не источник Taobao
в терминалеnpm login, Войдите в свой аккаунт

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

Полная основная информация

Следующие поля package.json требуют внимания

name
version
description
keywords
author
license
repository
main
unpkg
module
scripts
engines

nameЭто имя пакета, опубликованного на npm, то есть имя, которое вводят другие при установке.yarn add ${name}, имя пакета должно бытьkebab-case, то есть все английские слова в нижнем регистре, разделенные тире (строчные и разделенные тире)

versionявляется семантическим,major.minor.patch. еслиmajorизменение, как правило, означает несовместимую модификацию; если этоminor, означает добавление новой функции для обратной совместимости, если онаpatch, означает исправление ошибок. Подробнее см.semver.org

descriptionэто описание пакета, вnpmjs.comОтображается при поиске на , чтобы помочь пользователям фильтровать при поиске

keywordsЭто также помогает пользователям найти ваш пакет

authorФормат, как правило,${your name} ${email}, конечно, это также может быть адрес github

licenseМногие могут проигнорировать, лучше написать. Что касается того, какой из них использовать, все официальные проекты vue принадлежат MIT, поэтому я тоже MIT, поэтому мне все равно.

repositoryСсылка на формат выглядит следующим образом:

"repository": {
  "type": "git",
  "url": "https://github.com/FEMessage/el-data-table.git"
}

так встраница пакета npmБудет вход на гитхаб

mainОпределяет входной файл пакета, в среде NodeJs операторimport pkg from 'package-name'Когда, по сути, импортmainфайл определения, это может бытьCommonJsформат илиumdФормат

Обратите внимание, что когда вы публикуете пакет в npm, он также доступен наunpkgполучено выше. То есть ваш код может выполняться как в среде NodeJ, так и в среде браузера. Для этого нужно использоватьumdФормат упакован и определен в package.json.unpkgполе, как правило, в этот момент оно называетсяname.min.js

Наконец, не забудьте определитьmoduleилиjsnext:mainполе, представляющее упаковку в формате модуля ES6, для работы с расширенными инструментами сборки, такими как Webpack 2+ или Rollup.

Давайте рассмотрим пример с тремя полями:

"main": "dist/el-data-table.js",
"unpkg": "dist/el-data-table.min.js",
"module": "dist/el-data-table.esm.js"

scriptsЧтобы предотвратить событие Улун, которое вы забудете создать перед отправкой пакета, определите сценарий перед выпуском, чтобы каждое выполнениеnpm publishбудет выполнен раньшеnpm run build

"prepublishOnly": "npm run build"

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

определить зависимости

Когда вы разрабатываете проект, например статический веб-сайт или одностороннее приложение,dependenciesиdevDependenciesНет большой разницы, потому что выnpm installилиyarn, эти зависимости будут загружены, потому что вы разрабатываете.

Но для пакетов, опубликованных в npm, все по-другому:

dependenciesэто зависимость, которая должна быть установлена для запуска вашего пакета, т.е. когда пользовательyarn add my-awesome-package, эти зависимости также загружаются.

devDependenciesэто зависимость, которую необходимо установить при разработке пакета, напримерeslint, jestи другие средства разработки, когда пользовательyarn add my-awesome-package, эти зависимости не скачиваются!

peerDependenciesОбычно он используется в сценарии разработки плагинов, который требует, чтобы у пользователей были заранее установлены определенные зависимости. такие как разработкаwebpackплагин, если поставить правильныйwebpackЗависимости определяются какdependencies, если пользователь установилwebpackиdependenciesвнутреннийminorЕсли версия несовместима, пользовательyarn add my-webpack-pluginбудетdependenciesОпределенныйwebpackТакже скачивается, то есть пользователь установит дваmajorта же версияwebpack, что нецелесообразно.

Таким образом, определение зависимостей вашего пакета может сделать установку и использование вашего пакета менее запутанной и более приятной для пользователей.

игнорировать файлы

Если есть.gitignoreфайл, он будет проигнорирован при публикации.gitignoreфайлы, определенные в , то есть эти файлы не нужно.npmignoreпереопределить. Если вы используете.gitignoreигнорируетсяdistкаталог, но его необходимо освободить при выпуске пакетаdistКаталог, который можно определить в package.json на данный момент.filesполе, это белый список, и файлы в нем будут опубликованы

"files": [
  "dist"
]

Обратите внимание, что вложенные папки.gitignoreили.npmignoreработает так же хорошо, пока они перезаписываютfilesполе

Кроме того, некоторые файлы никогда не публикуются независимо от того, как они настроены:

node_modules
.git(включают.gitignore)

README.md

Не забудьте этот файл, запишите более конкретную информацию, связанную с пакетом, расскажите пользователю, какие функции есть у этого пакета и как его использовать. Важно, чтобы пользователи не использовали недокументированный пакет!

выпуск

Версия может быть выпущена только один раз, чтобы каждый раз не вносить изменения вручную.package.json, можно использоватьnpm version [major | minor | patch]команда для обновленияpackage.jsonверсия в

тег

Предполагая, что последняя версия вашего пакета1.0.0, когда пользовательyarn add my-awesome-packageилиyarn add my-awesome-package@1.0.0, на самом деле эквивалентноyarn add my-awesome-package@latest, то есть когда метка не указана, установка по умолчаниюlatestВерсия.

Предположим, вы разрабатываете2.0.0версия, она еще не стабильна, вы хотите выпустить ее для пользовательского тестирования, но не можете сделать это вlatestверсии, иначе пользовательyarn add my-awesome-packageустановлен, когда2.0.0, это приведет к сбою пользователя. Что нам делать тогда? Этикетка используется.

можно публиковать так

npm publish --tag beta

затем пользовательyarn add my-awesome-packageустановлен1.0.0Версия,yarn add my-awesome-package@beta, установленный2.0.0Версия, не затрагивающая старых пользователей, отличная! 🎉

Помните, что вы можете пометить версию только тегомnpm dist-tag lsВы можете увидеть, сколько тегов имеет пакет npm.

Упаковка

строительные леса

После некоторого метания вVue ConfНайдите упаковочный каркас для компонентов vue на (В официальной документации Vue также есть инструкции.), после модификации и улучшения «локализации» он был открыт на github:GitHub.com/Fe сообщение/V…

инструкция

Мы используем компоненты с открытым исходным кодомel-data-tableВ качестве примера объясните структуру каталогов и файлов

├── README.md
├── build
│   └── rollup.config.js
├── dist
│   ├── el-data-table.esm.js
│   ├── el-data-table.min.js
│   └── el-data-table.umd.js
├── docs
│   ├── build
│   └── index.html
├── package.json
├── src
│   ├── el-data-table.vue
│   └── index.js
├── styleguide.config.js
├── test
│   └── index.test.js
└── yarn.lock

Давайте сначала посмотрим на три файла:

README.md
package.json
yarn.lock

README.mdиpackage.jsonВсе знают, естьyarn.lockПотому что мы призываем всех использоватьyarn, это большеnpmБыстрее. Несмотря на то чтоnpmЗаявлено, что 6.0 в 17 раз быстрее (можете себе представить, насколько медленным он был до 6), но после тестирования он все еще не так хорош, какyarn

см. далееbuild, dist, srcсодержание

├── build
│   └── rollup.config.js
├── dist
│   ├── el-data-table.esm.js
│   ├── el-data-table.min.js
│   └── el-data-table.umd.js
├── src
│   ├── el-data-table.vue
│   └── index.js

buildФайл конфигурации во время компиляции помещается в каталог, за которым следуетvue-cli 2.xСгенерированный каталог сборки шаблона имеет ту же функцию, за исключением того, что здесь находитсяrollup.config.js. Что касается того, почему используется Rollup, во-первых, потому что конфигурация проще, а во-вторых, потому, что она больше подходит для упаковки библиотек классов.import lib from 'awesome-lib'Аналогичный код, роллап не поставлюawesome-libСвязанный вывод, который именно то, что вам нужно для разработки библиотеки или компонента

distэто выходной каталог, также называемыйlibДа, я долго боролся. Прочитав несколько отличных проектов с открытым исходным кодом, я обнаружил, что он называетсяdistбольше, покаwebpack4Выходной каталог по умолчанию такжеdist, поэтому решил использоватьdist. Что касаетсяdistВ каталоге будет три файла, и причины были указаны выше. А почему бы и не назватьcamelcase, ноkebab-case, далее в руководстве по стилю

srcявляется входным каталогом. Пучокindex.jsставитьsrcКаталог также после некоторого рассмотрения. также хочуindex.jsиpackage.jsonТот же уровень, последняя ссылкаwebpack4, его ввод по умолчаниюsrc/index.js, что соответствует мейнстриму. Основная задача этого файла состоит в том, чтобы поместитьsrcФайл vue в каталоге установлен как плагин vue. Точно так же за названием файла vue будет следовать руководство по стилю.

├── test
│   └── index.test.js

testкаталог основан наjestиvue/test-utilsФайл модульного теста , на который может ссылаться конкретный учебникофициальная документация

├── docs
│   ├── build
│   └── index.html
├── styleguide.config.js

docsХранит API-документ компонента, включаяprops, slot, eventи т.д. Описание контента с использованиемvue-styleguidistКак инструмент для создания документации по компонентам vue. почему это называетсяdocsНу, потому чтоGithub PagesПоддержка отmasterразветвленныйdocsКаталог для чтения файлов в репозиторииSettingsВыбратьGithub PagesизSourceОК, подробнее см.официальная документация

гид по стилю

Компонент vue помещает шаблон/скрипт/стиль в файл vue, который называется однофайловым компонентом.Single File Component, сокращенно SFC, т.vue-sfc-cliЗначение sfc

прочитатьофициальное руководство по стилю vue, так как мыkebab-caseявляется активным пользователем , поэтому мы больше заботимся о соблюдении одних и тех же правил использования заглавных букв в нескольких проектах. Вот выдержка из рекомендаций, которые применяются к привычкам совместной работы нашей команды:

Имя компонента должно состоять из более чем одного слова

Это позволяет избежать необходимости иметь дело с существующими и будущими элементами HTML.конфликт, поскольку все имена элементов HTML состоят из одного слова.

Имена файлов для однофайловых компонентов всегда должны начинаться с заглавной буквы (PascalCase) или всегда должны быть разделены дефисом (кебаб-регистр).

мы решили использоватьkebab-case

Хороший пример:

components/
|- my-component.vue

Всегда kebab-case в шаблонах DOM

Хороший пример:

<!-- template -->
<my-component></my-component>

Имена компонентов в JS/JSX всегда должны быть PascalCase, хотя строки kebab-case могут использоваться в более простых приложениях, когда используется только Vue.component для глобальной регистрации компонентов.

Здесь мы решили использоватьPascalCase, потому что в языках программированияkebab-caseНе лучшая практика. То есть в рамках неязыков программирования мы можем использоватьkebab-caseзатем применить

Хороший пример:

Vue.component('MyComponent', {
  // ...
})

import MyComponent from './my-component.vue'

export default {
  name: 'MyComponent',
  // ...
}

Подводя итог, вы можете понять, что стиль именования файлов el-data-table в предыдущей статьеkebab-caseпричина

Ознакомьтесь с другими статьямимой блог