Создание пакета 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