TLDR

Вам необходимо использовать сборщик, такой как esbuild, который скомпилирует ваш проект и объединит вместе с ним все его зависимости, чтобы они не импортировались. Это позволяет обойти проблему несовместимости ESM/CommonJS.

Если вам не терпится, вы можете сразу перейти к коду этого примера реализации.

Контекст

Готовясь к выпуску моего нового проекта Token.js на выходных, я столкнулся с довольно неприятной проблемой. Я хотел, чтобы мой пакет поддерживал CommonJS в дополнение к ESM, но у меня были чистые зависимости ESM. Сторонники чистого ESM, возможно, будут весьма недовольны моими словами, но если вы создаете пакет NPM и хотите, чтобы он широко использовался, вам все равно потребуется поддержка CommonJS в 2024 году.

Token.js — это простой TypeScript SDK, который позволяет интегрировать 60 LLM от 9 разных поставщиков (OpenAI, Anthropic, Cohere и т. д.). Бесстыдный плагин, посмотрите и дайте мне знать, что вы думаете, если вам нравится генеративный искусственный интеллект.

Сейчас в Интернете есть ряд ресурсов, на которых обсуждается, как создавать проекты Javascript для ESM, CommonJS или обоих. Однако у меня были проблемы с тем фактом, что у меня были зависимости, которые были чистым ESM. Мне показалось, что с этим довольно сложно справиться, потому что я не знаком с упаковщиками (в основном я работал над серверной частью веб-приложений) и не смог найти хорошего руководства по этой теме.

Так что, если кто-то еще столкнулся с этой проблемой, вот решение.

Гид

Установить эсбилд

Мы будем использовать esbuild для сборщика.

yarn add esbuild --save-dev

Создать скрипт сборки

Нам понадобится простой скрипт сборки для запуска esbuild и вывода результатов.

import esbuild from 'esbuild'

const entrypoint = ""
const tsconfig = ""

const build = async () => {
  await Promise.all([
    // bundle for commonjs
    esbuild.build({
      entryPoints: [entrypoint],
      bundle: true,
      minify: true,
      format: 'cjs',
      outfile: `./dist/index.cjs`,
      platform: 'node',
      treeShaking: true,
      tsconfig,
    }),
  ])
}

build()

Добавьте скрипт сборки в ваш package.json.

Запускайте в предпочитаемой вами среде выполнения.

"scripts": {
  "build": "vite-node ./scripts/build.ts",
}

Лично мне нравится vite-node. Итак, если вы хотите точно следовать инструкциям, вам необходимо установить это:

yarn add vite-node --save-dev

Создайте свой проект

yarn build

Это приведет к сборке вашего проекта с помощью esbuild, и вы увидите новый файл dist/index.cjs, который представляет собой сборку CommonJS вашего пакета.

Настроить точку входа

Обновите package.json, чтобы он указывал на вашу точку входа CommonJS.

"main": "dist/index.cjs",

Бам! Итак, вы создали свой пакет для CommonJS. Это будет работать, даже если у вас есть зависимости ESM, поскольку зависимости будут объединены в пакет
вместе с вашей посылкой.

Зависимости включаются в выходные данные из-за пакета полей: true при вызове esbuild.

Объявления TypeScript

Хотя технически это не требуется, вам, скорее всего, также понадобятся объявления TypeScript, которые, к сожалению, esbuild в настоящее время не выводит. Итак, чтобы сгенерировать
вы захотите использовать обычный tsc.

Обновите свой tsconfig.json

Добавление этих параметров в файл tsconfig.json приведет к выводу только объявлений TypeScript. Это именно то, что нам нужно, поскольку остальная часть пакета
собирается с помощью esbuild.

"declaration": true,
"declarationDir": "./dist",
"emitDeclarationOnly": true

Обновите скрипт сборки

"scripts": {
  "build:tsc": "yarn tsc -p tsconfig.json",
  "build": "vite-node ./scripts/build.ts && yarn build:tsc",
}

Двойные точки входа

В этом руководстве рекомендуется выводить только одну точку входа CommonJS для вашего пакета. Лично я считаю, что это лучший вариант по двум причинам:

• Минимизирует размер пакета
• Предотвращает опасность двойной упаковки

Однако это не единственный вариант. Вы также можете опубликовать свой пакет с двумя точками входа для CommonJS и ESM.

Обновите сценарий сборки, включив в него сборку ESM.

import esbuild from 'esbuild'

const entrypoint = ""
const tsconfig = ""

const build = async () => {
  await Promise.all([
    // bundle for commonjs
    esbuild.build({
      entryPoints: [entrypoint],
      bundle: true,
      minify: true,
      format: 'cjs',
      outfile: `./dist/index.cjs`,
      platform: 'node',
      treeShaking: true,
      tsconfig,
    }),
    // bundle for ESM
    esbuild.build({
      entryPoints: [entrypoint],
      bundle: true,
      minify: true,
      format: 'esm',
      outfile: `./dist/index.js`,
      platform: 'node',
      treeShaking: true,
      tsconfig,
    }),
  ])
}

build()

Обновите файл package.json, включив в него двойные точки входа.

"main": "dist/index.cjs",
"module": "dist/index.js",
"type": "module",
"exports": {
  ".": {
    "import": "./dist/index.js",
    "require": "./dist/index.cjs",
    "types": "./dist/index.d.ts"
  }
},

Исходный код