为具有 ESM 依赖项的 CommonJS 构建 NPM 包

总长DR

您必须使用诸如 esbuild 之类的捆绑器，它将编译您的项目并将其所有依赖项与其一起捆绑，这样它们就不会被导入。这绕过了 ESM/CommonJS 不兼容问题。

如果你不耐烦，可以直接看这个示例实现的代码。

语境

周末准备发布我的新项目 Token.js 时，我遇到了一个非常令人沮丧的问题。我希望我的包除了 ESM 之外还支持 CommonJS，但我有纯粹的 ESM 依赖项。纯粹的 ESM 斗士可能会对我这么说感到非常不高兴，但如果你正在构建一个 NPM 包并希望它被广泛使用，你仍然需要在 2024 年支持 CommonJS。

Token.js 是一个简单的 TypeScript SDK，允许您集成来自 9 个不同提供商（OpenAI、Anthropic、Cohere 等）的 60 多个 LLM。无耻的插件，如果你喜欢生成人工智能，请检查一下并告诉我你的想法。

现在有很多在线资源讨论如何为 ESM、CommonJS 或两者构建 Javascript 项目。然而，我特别难以处理这样一个事实：我有纯 ESM 的依赖项。我发现这很难处理，因为我不熟悉捆绑程序（我主要从事 Web 应用程序后端），并且无法找到有关该主题的良好指南。

因此，如果其他人遇到此问题，这里是解决方案。

指导

安装esbuild

我们将使用 esbuild 作为捆绑器。

yarn add esbuild --save-dev

创建构建脚本

我们需要一个简单的构建脚本来运行 esbuild 并输出结果。

import esbuild from 'esbuild'

const entrypoint = "<your entrypoint here>"
const tsconfig = "<your tsconfig path here>"

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 依赖项，这也将起作用，因为依赖项将被捆绑
连同您的包裹。

由于调用 esbuild 时存在字段“bundle: true”，因此依赖项包含在输出中。

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 = "<your entrypoint here>"
const tsconfig = "<your tsconfig path here>"

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"
  }
},

源代码

以上是为具有 ESM 依赖项的 CommonJS 构建 NPM 包的详细内容。更多信息请关注PHP中文网其他相关文章！