Пакеты JavaScript, опубликованные в NPM, используются разными потребителями. Создать действительно универсальную упаковку стало невозможно, потому что потребности потребителей принципиально разные. В этом документе описывается политика, которой я следую при публикации своих пакетов JavaScript в NPM.

Сначала нам нужно идентифицировать потребителей. Пакет JavaScript может быть

  • требуется для приложения node.js.
  • используется инструментом сборки (webpack, rollup, parcel).
  • доставляется непосредственно на веб-страницы через unpkg.com.

В зависимости от потребителя исходный код JavaScript должен быть подготовлен по-разному. Например, исходный код, загружаемый приложением node.js, может использовать большинство последних функций ES2018 (классы, стрелочные функции, итераторы, генераторы и т. Д., В зависимости от целевой версии node.js), но должен использовать require() при обращении к другим файлам. Файлы, которые используются с помощью инструмента сборки, должны использовать последний синтаксис ES2018 и быть написаны как модули ES6 (используйте операторы import / export). Файлы, передаваемые на веб-страницы, должны быть перенесены, чтобы быть совместимыми с любыми версиями браузера, на которые вы нацелены, минифицированы, но все же предоставлять исходные карты.

У меня есть еще одно ограничение - личный выбор - предоставлять объявления типов TypeScript для моих пакетов.

К счастью, можно создать единый пакет, который может удовлетворить все это, путем определения для каждого отдельного «файла ввода». В package.json вы можете указать, какой файл следует использовать, когда пакет используется node.js, сборщиком или unpkg.com:

{
    "main": "dist/index.node.js", /* node.js */
    "module": "dist/index.js",    /* bundler */
    "unpkg": "dist/index.min.js", /* unpkg.com */
    "types": "dist/index.d.ts"    /* TypeScript */
}

Что это означает для организации исходного кода в репозитории и процесса сборки / публикации:

  • Я начинаю с папки (src/), которая содержит исходный код TypeScript.
  • Я использую компилятор TypeScript с параметром target = es2018, чтобы скомпилировать исходники в другую папку (dist/). Это сгенерирует ES2018-совместимый код, который использует синтаксис модуля ES6. Это именно то, что нужно инструментам сборщика. Компилятор TypeScript также генерирует отдельные файлы объявления типа.
  • Затем я использую rollup с параметром format = cjs и конфигурацией babel, нацеленной на конкретную версию node.js (в настоящее время 10), чтобы создать отдельный файл, подходящий для node.js.
  • Если требуется - не все мои пакеты предоставляют это - я буду использовать другую конфигурацию накопления (target = amd, babel env config, которая нацелена на определенные версии браузера и minfier) ​​для создания файла, который может быть загружен веб-браузерами для использования через unpkg.com.
  • Все сгенерированные файлы попадают в папку dist/. Эта папка вместе с файлом package.json - это то, что я поместил в архив, который загружается в NPM.

Вот некоторые репозитории: computing, avers, valde.