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

class esbuild 构建 commonjs 636 来源： 2024-10-23

总长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 () =&gt; {
  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()
</your></your>

将构建脚本添加到 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 &amp;&amp; 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 () =&gt; {
  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()
</your></your>

更新您的 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"
  }
},

源代码

上一篇：Flexbox Cheatsheet：以简单的方式学习

下一篇：如何将 AI 语音助手添加到您的 React 应用程序中