Создание пакета npm может оказаться удивительно запутанным, а в официальных ресурсах указывается только минимум, необходимый для публикации пакета. Эта статья представляет собой пошаговое руководство о том, как создать пакет с использованием технологий ESlint, Prettier, Rollup, Babel и Jest. Это может показаться сложным, но это отличные инструменты, которые помогают вам писать код, который могут использовать другие.
Этому я научился, работая над своим пакетом @xcorejs/ui. В этой статье я буду использовать yarn, но это не обязательно.
Установка пакета
Первое, что вам нужно сделать, это создать новый каталог и настроить пакет npm с помощью:
yarn init
Затем создайте папку src, куда вы поместите свой код. Кроме того, это действительно хорошая идея — настроить репозиторий git.
git init
Добавить .gitignoreфайл:
node_modules yarn.lock # package builds lib dist
При желании вы можете добавить информацию о пакете в свой package.json, чтобы он выглядел так:
{ "name": "@alfonz/random", // your package can be scoped to your account name "private": false, "version": "0.0.1", // use semantic versioning "author": "Denis Homolik", "license": "MIT", "description": "Simple package of random related utilities" }
Код Lint с Prettier и ESlint
Прежде чем приступить к программированию, вам необходимо настроить линтер и средство форматирования кода. На момент написания этой статьи наиболее широко используемым линтером является ESlint, а наиболее используемым средством форматирования кода — Prettier.
Установите ESlint и Prettier следующим образом:
yarn add -D eslint eslint-config-prettier eslint-plugin-prettier prettier
Затем создайте файл eslint.config.js для настройки ESlint:
{ "plugins": ["prettier"], "extends": [ "eslint:recommended", "prettier" ], "parserOptions": { "sourceType": "module" }, "env": { "browser": true, "jest": true, "es6": true, "node": true }, "rules": { "prettier/prettier": "warn" } }
Наконец, вставьте это в свой package.json, чтобы создать команду lint, которая запускает ESlint.
"scripts": { "lint": "eslint src/**/*.js" }
При желании вы можете создать файл .prettierrc для настройки параметров Prettier. Я предпочитаю эту установку:
{ "quotes": "single", "quoteProps": "consistent" }
Теперь, если вы запустите yarn lint
, это должно выглядеть так:
Исходный код
Моя библиотека будет набором утилит для генерации случайных значений. Во-первых, давайте установим зависимости, которые нам понадобятся:
(polished — это набор инструментов для написания стилей на javascript, мы будем использовать их функции затемнения и осветления)
yarn add polished
Мы собираемся поместить все наши исходные файлы в папку src. Начнем с простого целого числа и генератора с плавающей запятой:
Затем добавьте генераторы случайных цветов:
Наконец, создайте файл index.js, чтобы экспортировать все, что вы хотите сделать доступным во внешний мир.
Связывание кода с Rollup.js
Вам следует объединить свой код в один файл, чтобы удалить ненужный код, скрыть внутренние API и сделать ваш код совместимым с ES5.
Также рекомендуется скомпилировать пакет в CommonJS, ESM и UMD.
Что такое CommonJS, ESM и UMD?
CommonJS, ESM и UMD — это определения модулей. Именно так Node и браузеры импортируют ваши модули.
- CommonJS — это определение модуля, введенное и в основном используемое в Node.js и сборщиках кода, таких как Webpack. Вы не можете использовать CommonJS в своем браузере.
const a = require(“a”);
- ESM (модуль ECMAScript) — это новый стандартизованный способ работы с модулями. Их можно использовать как в Node, так и в браузере. (Хотя они все еще являются экспериментальными в Node, и лучше использовать упаковщик, если вы хотите запускать код в браузере.) И они идеально подходят для использования с упаковщиками!
import { a, b } from “a”;
- UMD пытается поддерживать Node так же, как и браузеры, но он не идеален для использования с упаковщиками, но вы должны предоставить его по устаревшим причинам.
Если вы используете Webpack в своих проектах, он сначала ищет модули ES (определяемые «модулем» в package.json), а затем переходит к модулям CommonJS. Rollup берет все ваши модули и объединяет их в один файл, который потребители могут импортировать.
Настраивать
Начнем с установки Rollup:
yarn install rollup
Затем создайте этот простой файл rollup.config.js:
Кроме того, добавьте это в свои скрипты в package.json:
"build": "rollup -c"
Для создания проекта используйте:
yarn build
Минификация
Модули CommonJS и ESM не должны быть минимизированы. Минификацию следует оставить конечному пользователю. С другой стороны, для сборки UMD вы должны предоставить уменьшенную версию сборки.
Для этого используйте подключаемый модуль rollup-plugin-terser:
yarn add -D rollup-plugin-terser
Затем добавьте новый ввод в файл конфигурации:
Теперь, если вы запустите yarn build
, он должен произвести это:
Транспилировать код с помощью Babel
Ваш пакет должен быть транспилирован в ES5 для поддержки старых браузеров (например, ie11). Вам не обязательно этого делать, но хорошей практикой является предоставление совместимого кода. Самый простой способ транспилировать код — использовать Babel.
Начните с установки необходимых зависимостей:
yarn add rollup-plugin-babel @babel/core @babel/preset-env
Добавьте файл .babelrc в корневой каталог:
{ "presets": [ ["@babel/preset-env", { "modules": false }] ] }
Мы используем предустановку babel, которая по умолчанию транспилирует код в ES5.
“module: false”
означает, что babel не должен транспилировать импорт ESM и оставлять его для Rollup.
Наконец, обновите конфигурацию Rollup, добавив плагин Babel к своим входам:
Добавьте точки входа вашего пакета
Теперь у вас есть скомпилированные файлы, но вам также нужно добавить точки входа в package.json
:
"type": "module", "main": "lib/index.js", "module": "lib/index.es.js", "jsnext:main": "lib/index.es.js", "browser": "dist/index.js",
type
указывает, что пакет использует модули ES.main
является точкой входа для CommonJS.module
иjsnext:main
— точки входа для модулей ES.browser
— точка входа для UMD.
Тестовый код с Jest
Для тестирования кода я предпочитаю использовать Jest. Начните с установки необходимых зависимостей:
yarn add -D jest
Jest не требует никаких настроек для работы «из коробки», поэтому вы можете приступить к созданию своих тестов.
К сожалению, Jest неподдерживает модули ES из коробки, поэтому я использовал CommonJS require.
Наконец, добавьте "test": "jest"
в свои скрипты и используйте yarn test
для запуска Jest.
Публикация пакета
Прежде чем опубликовать свой пакет, вы можете предоставить дополнительную информацию о нем в файле package.json.
{ "name": "@alfonz/random", "private": false, "version": "0.0.1", "author": "Denis Homolik", "license": "MIT", "description": "Simple package of random related utilities", // it's a good practice to use "sideEffects": false if your package doesn't have side effects "sideEffects": false, // list of all files that will be included in the package (all files are included if omitted) "files": [ "dist", "lib" ], // relevant keywords for your package "keywords": [ "random" ], [...] }
Чтобы опубликовать свой пакет в npm, вам потребуется учетная запись npm, которая бесплатна, если вы не хотите публиковать частные пакеты. После этого вам нужно войти с помощью:
npm login
Затем просто опубликуйте пакет с помощью:
npm publish --access public
Теперь вы должны быть в состоянии создавать пакеты, которые могут легко использовать другие. Спасибо за чтение :)
Пакет npm: https://www.npmjs.com/package/@alfonz/random
Репозиторий Github: https://github.com/AlfonzAlfonz/random