0. Введение
В этом руководстве я собираюсь поделиться своим опытом создания библиотеки UMD JavaScript, которую можно использовать везде, библиотека совместима с экосистемами AMD (определение асинхронного модуля) и CommonJS, а также может быть загружена в тег <script>
.
Для получения дополнительной информации о AMD, CommonJS и UMD Дэвид Калхун написал отличный блог, в котором сравнил их, его настоятельно рекомендуется прочитать.
Хорошо, приступим!
1. Создайте библиотеку JavaScript.
Мы собираемся создать супер простой калькулятор :)
Создать новый репозиторий
Перейдите в Github и создайте новый проект с именем calculator
, инициализируйте репозиторий с помощью README, .gitignore
и выберите лицензию.
Клонируйте только что созданный репозиторий и войдите в папку:
> git clone [email protected]:<GH_USERNAME>/calculator.git && \ cd calculator
Инициализировать пакет NPM и установить зависимости Node.js.
Мы будем использовать Webpack, чтобы объединить библиотеку для распространения, и использовать babel, чтобы помочь перенести синтаксис ES6, чтобы наша библиотека работала в большинстве браузеров.
> npm init -y > npm i -D webpack webpack-cli babel-loader @babel/core \ @babel/preset-env
Строим библиотеку
В Webpack есть отличное руководство по созданию библиотек, давайте возьмем его структуру папок.
> mkdir -p {src,dist,examples/browser,examples/node} > touch src/index.js examples/browser/index.html \ examples/node/example.js
Теперь структура папок должна выглядеть так:
. ├── dist ├── examples │ ├── browser │ │ └── index.html │ └── node │ └── example.js └── src └── index.js
Реализуйте библиотеку
Пора реализовать библиотеку!
src / index.js
module.exports = { add: (num1, num2) => num1 + num2, sub: (num1, num2) => num1 - num2, };
Как видите, наш калькулятор очень простой.
examples / node / example.js
const {add, sub} = require('./calculator.js'); console.log('1 + 2 = ' + add(1, 2)); console.log('2 - 1 = ' + sub(2, 1));
examples / browser / index.html
<html> <head> <title>Test Calculator</title> </head> <body> <script src='./calculator.js'></script> <script> const {add, sub} = calculator; console.log('1 + 2 = ' + add(1, 2)); console.log('2 - 1 = ' + sub(2, 1)); </script> </body> </html>
Вышеупомянутые два файла в основном используются для локального тестирования.
Объедините библиотеку
Нам нужно настроить Webpack и Babel, чтобы они работали на нас.
> touch webpack.config.js .babelrc
webpack.config.js
const path = require('path'); module.exports = { mode: 'production', entry: './src/index.js', output: { path: path.resolve(__dirname, './dist'), filename: 'calculator.js', library: 'calculator', libraryTarget: 'umd', globalObject: 'this', }, module: { rules: [{ test: /\.js$/, exclude: /(node_modules)/, use: 'babel-loader', }], }, };
.babelrc
{ "presets": ["@babel/preset-env"] }
И нам нужно обновить package.json. Самая важная часть здесь - изменить свойство main
, чтобы оно указывало на dist/calculator.js
.
package.json
"main": "dist/calculator.js", "scripts": { "build:browser": "webpack && cp dist/calculator.js examples/browser", "build:node": "webpack && cp dist/calculator.js examples/node/ && node examples/node/example.js", "build": "webpack" }
О, убедитесь, что папка dist
включена в окончательный дистрибутив, просто раскомментируйте строку dist
, если вы ее видите.
.gitignore
... # Nuxt.js build / generate output .nuxt # dist
Протестируйте библиотеку
Давайте проведем небольшое локальное тестирование вручную, чтобы убедиться, что библиотека может работать с Node.js и браузером.
> npm run build:node 1 + 2 = 3 2 - 1 = 1 > npm run build:browser
Отлично! Мы только что завершили наш первый этап, пора выпускать релиз!
2. Автоматизируйте релизы.
Раньше я использовал release-it, чтобы вручную выпустить библиотеку, и мне нужно решить, будет ли это патч, второстепенный или основной выпуск.
Semantic-release использует сообщения фиксации для определения типа выпуска, пока сообщения фиксации следуют стилю обычных фиксаций. А в semantic-release есть несколько подключаемых модулей для создания журнала изменений, публикации в Github и NPM с примечанием к выпуску, так что давайте воспользуемся этим.
Установите зависимости Node.js
> npm i -D husky @semantic-release/{changelog,git,github,npm,commit-analyzer,release-notes-generator} @commitlint/{cli,config-conventional}
Мы используем husky
для подключения к командам git, в основном нам нужно убедиться, что сообщения коммитов соответствуют обычному стилю коммитов, вы увидите, как он настроен позже.
Локальные конфигурации
Нам нужно настроить несколько вещей.
> touch commitlint.config.js .releaserc
commitlint.config.js
module.exports = { extends: [ '@commitlint/config-conventional' ] };
Это используется для линтинга наших сообщений о фиксации.
.releaserc
{ "plugins": [ "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", ["@semantic-release/changelog", { "changelogFile": "docs/CHANGELOG.md", }], "@semantic-release/npm", ["@semantic-release/git", { "assets": ["dist/**/*.{js,css}", "docs", "package.json"], "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}" }], "@semantic-release/github" ] }
Это конфигурация семантического релиза. Очень важно знать, что все плагины выполняются в определенном порядке!
Обновите package.json, мы собираемся называть наш пакет, следуя стилю именования пакетов NPM в области видимости. Сбросьте номер версии на 0.0.0
, настройте husky
, добавив сценарий для семантического выпуска позже.
Обратите внимание, что у нас также есть publishConfig
и для свойства access
установлено значение «public», это используется, потому что мы принимаем имя пакета области действия.
"name": "@jeantimex/calculator", "version": "0.0.0", "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" } }, "publishConfig": { "access": "public" }, "scripts": { ... "semantic-release": "semantic-release" }
Хорошо, локальная настройка завершена, перейдем к удаленной стороне.
Мы собираемся использовать Travis CI для автоматизации выпуска.
Удаленные настройки: настройка Travis
Сначала активируйте репозиторий, нажмите кнопку Sync account
, чтобы Трэвис получил новый репозиторий из Github.
Нажмите кнопку «Настройки» рядом с зеленой кнопкой активации. Мы собираемся создать две переменные среды.
Поскольку мы собираемся опубликовать библиотеку в NPM, нам нужно создать токен NPM для предоставления разрешений для Travis.
> npm login > npm profile enable-2fa auth-only > npm token create ┌────────────────┬──────────────────────────────────────┐ │ token │ 01234567-8901-2345-6789-012345678901 │ ├────────────────┼──────────────────────────────────────┤ │ cidr_whitelist │ │ ├────────────────┼──────────────────────────────────────┤ │ readonly │ false │ ├────────────────┼──────────────────────────────────────┤ │ created │ 2020-05-11T01:53:11.292Z │ └────────────────┴──────────────────────────────────────┘
Затем нам также необходимо предоставить разрешения для Трэвиса на чтение и запись (публикацию) в Github. Подробнее см. Здесь.
Ниже приведен снимок экрана с разрешениями Github для токена:
Когда у нас появятся токены, добавьте их на странице настроек Трэвиса.
Теперь давайте настроим Трэвиса.
> touch .travis.yml
.travis.yml
language: node_js node_js: - 12 jobs: include: # Define the release stage that runs semantic-release - stage: release node_js: lts/* script: skip deploy: provider: script skip_cleanup: true script: - npx semantic-release
По сути, мы просим Трэвиса запустить семантический релиз :)
Освободить библиотеку
Наконец-то пора выпускать релиз!
> git add . > git commit -m "feat: introduce calculator" > git push
Вы увидите, как Трэвис создает и развертывает библиотеку.
После его завершения наша библиотека будет опубликована в NPM.
И Github показывает, что новый выпуск будет красивой примечанием к выпуску.
Также автоматически создается журнал изменений!
🎉 Наш калькулятор работает! Поздравляю, у вас получилось!
3. Проверьте библиотеку.
Теперь посмотрим, может ли библиотека работать везде.
Observable работает с библиотеками AMD, поэтому мы можем require
наш калькулятор там и посмотреть, работает ли он, да, работает!
Затем давайте проверим, работает ли наша библиотека с CommonJS на repl.
Наконец, наша библиотека должна нормально работать через тег скрипта.
<script src="//unpkg.com/@jeantimex/[email protected]/dist/calculator.js"></script> <script> const {add, sub} = calculator; console.log('1 + 2 = ' + add(1, 2)); console.log('2 - 1 = ' + sub(2, 1)); </script>
Вот и все, надеюсь, вам понравится и эта статья окажется полезной.
Исходный код: https://github.com/jeantimex/calculator