創建一個雙模式跨運行時的 JavaScript 包，你學會了嗎
本文將指導你發布雙模式、跨運行時的 JavaScript 包。了解如何創建與 ESM 和 CommonJS 以及 Node.js、Deno 和瀏覽器等不同運行時兼容的庫。
隨著 JavaScript 開發的不斷發展，人們越來越需要能在多種環境中運行的強大依賴包。在本文中，我們將探討如何發布跨運行時、雙模式的 JavaScript 包。這些包彌補了 ESM 和 CommonJS 之間的差距，讓開發人員可以在任何環境下使用相同的包和文檔。
在深入了解之前，讓我們先熟悉一些關鍵概念：
雙模式包
雙模式包旨在與多個 JavaScript 模塊系統（尤其是 ES Modules (ESM) 和 CommonJS (CJS)）配合使用。這確保了代碼在各種環境中的可重用性和靈活性。創建雙模式包有幾個好處：
- 「更廣泛的兼容性」：并非所有項目都已過渡到使用 ESM。雙模式確保你的包可以在仍然依賴于 CommonJS 的項目中使用。
- 「無縫過渡」：隨著 JavaScript 生態系統逐步轉向 ESM，雙模式包可確保用戶實現無縫過渡，而無需更換包或重構代碼庫。
- 「減少維護」：雙模式包允許用戶管理單一代碼庫，而無需分別維護 ESM 和 CJS 包。
不過，雙模式并不能保證軟件包在不同的運行環境下都能正常工作，這就帶來了以下問題：
跨運行時包
跨運行時包可在 Deno、瀏覽器和 Node.js 等多種環境中運行。它們旨在為不同運行時提供一致的 API。一個全面的跨運行時包應同時支持 ESM 和 CJS，尤其是因為 Node.js 在很大程度上仍在使用 CommonJS。
如果我們忽略 Node.js 的傳統限制（Node.js 嚴重依賴 CommonJS），我們可以只使用 ES 模塊構建跨運行時包。這將簡化包，但會限制其與舊版 Node.js 項目的兼容性。
Node還是Deno優先
你有兩種主要方法：從 Deno 或 Node.js 開始。Deno 優先方法使用 Deno 的內置工具和 Deno 到Node工具（DNT）。另一方面，Node優先方法使用傳統的構建工具來完成測試、檢查和打包等任務。這種方法是轉換現有 NPM 庫的首選。
Deno優先方法
Deno優先方法依賴于DNT，你可以在GitHub[1]上找到。
該工具通過版本庫中的自定義構建腳本使用。
第一步是建立一個基本的 Deno 庫，準備發布到 deno.land/x。之后，你就可以使用 DNT 了。
「添加腳本」
Deno優先方法的核心是構建流程。下面這個名為 scripts/build_npm.ts 的腳本使用 DNT 創建一個 /npm 文件夾，其中包含一個完整的 NPM 包，可以隨時發布。
該腳本將處理清除 NPM 目錄、復制測試數據和構建軟件包等任務。它還會創建一個完整的 package.json 文件。
讓我們一起來看看吧，請務必閱讀注釋。
import { build, copy, emptyDir } from "./deps.ts";
// Clear NPM directory
await emptyDir("./npm");
// (optional) Copy test data, if you have some
// await copy("tests/data", "npm/esm/tests/data", { overwrite: true });
// This assumes that the entrypoint of your module is ./mod.ts
await build({
entryPoints: ["./mod.ts"],
outDir: "./npm",
shims: {
deno: "dev",
},
/*
mappings: {
"<https://deno.land/x/zipjs@v2.7.17/index.js>": {
name: "@zip.js/zip.js",
version: "^2.7.17"
},
},
*/
package: {
// package.json template
name: "my-library-name",
version: Deno.args[0],
description: "My library description.",
license: "MIT",
repository: {/* ... */},
author: "You <your@mail>",
/* Additional information */
},
});
// (optional) post build steps, you might want to copy some files?
// ---------------------------------------------------------------
// Deno.copyFileSync("LICENSE", "npm/LICENSE");
// Deno.copyFileSync("README.md", "npm/README.md");
// (optional) Add .npmignore
// ---------------------------------------------------------------
// ensure the test data is ignored in the `.npmignore` file
// so it doesn't get published with your npm package, if relevant
/*
await Deno.writeTextFile(
"npm/.npmignore",
"esm/tests/data\nscript/tests/data\n",
{ append: true },
);
*/現在，你只需運行 deno run -A scripts/build_npm.ts 0.0.1 來構建 0.0.1 版本的 npm 軟件包。所有相關文件都將在 ./npm 中生成。
最后一步是導航到 ./npm 目錄，然后運行 npm publish，就可以了！
「使用 deno.json 更新構建管道流」
要記錄這一構建步驟，可以修改 deno.json 的task部分，將新的 NPM 構建步驟包括在內。下面是一個設置測試和 NPM 構建的配置示例：
{
/* ... existing configuration ... */
"tasks": {
"test": "deno test tests --allow-read",
"build": "deno run -A scripts/build_npm.ts"
}
}現在，運行 deno task build 0.0.1 時將生成 npm 包。
Node優先方法
或者，你也可以選擇Node優先的方法來創建跨運行時包。
第一步是確保你的項目同時支持 ESM 和 CommonJS。這既可以手動完成，也可以使用構建工具來處理。代碼庫最好是非轉譯的 javascript 或 typescript，以便 Rollup 或類似工具處理。
讓我們以 @hexagon/base64 庫為例進行分析。該庫使用 Rollup 生成 ESM 和 CommonJS 版本的代碼，配置如下：
// rollup.config.js
export default [
{
input: "./src/base64.single.js",
output: {
file: "dist/base64.cjs",
format: "umd",
name: "base64",
exports: "default"
}
},
{
input: "./src/base64.js",
output: {
file: "dist/base64.mjs",
format: "es"
}
}
];該庫的源代碼（/src/base64.js）是以各種方式導出 base64 對象的普通 ES JavaScript。
// src/base64.js
/* ...
Library code making up the base64 object
... */
// Default export
export default base64;
// Named export
export { base64 };Rollup 無法處理多重導出，因此我還創建了一個 /src/base64.single.js，默認情況下它只負責重新導出 base64 對象。這是 Rollup 配置的 UMD 目標所使用的。
// /src/base64.single.js
import base64 from "./base64.js";
export default base64;package.json
package.json 文件是設置雙模式、跨運行時 JavaScript 包的關鍵。它決定了包在不同環境中的結構和行為方式。讓我們來仔細看看其中的關鍵部分及其重要性：
{
/* ... your metadata ... */
"scripts": {
/* ... your existing build steps ... */
"build:dist": "rollup -c ./rollup.config.js",
},
"type": "module",
"main": "./dist/base64.cjs",
"browser": "./dist/base64.min.js",
"module": "./src/base64.js",
"types": "types/base64.single.d.ts",
"exports": {
".": {
"import": "./src/base64.js",
"require": "./dist/base64.cjs",
"browser": "./dist/base64.min.js"
}
}
}- 「"scripts"」 ：該部分包含構建和管理包所需的腳本。在提供的示例中，"build:dist"用于觸發 Rollup 打包過程。根據包的具體要求，你可能還需要其他腳本來進行測試、檢查或執行其他任務。
- 「"type"」 ：該字段設置為"module"，表示你的包是為使用 ESM（ES 模塊）導入而設計的。
- 「"main"」 ：該字段指定了 CommonJS 環境（如 Node.js）的入口點。它指向包的 CommonJS 版本，通常位于 dist 目錄中。
- 「"browser"」 ：該字段用于指定瀏覽器環境的替代入口點。它指向包的最小化版本，以增強與瀏覽器的兼容性。
- 「"module"」 ：與 "main"字段類似，該字段用于指定 ESM 環境的入口點。它指向軟件包的 ESM 版本。
- 「"types"」 ：此字段指明軟件包的 TypeScript 聲明文件（.d.ts）的位置。這些文件為 TypeScript 用戶提供了類型信息，改善了開發人員的體驗。
- 「"exports"」 ：該字段是一項最新功能，允許你定義如何導入包。它為 ESM、CommonJS 和瀏覽器環境指定了不同的導入路徑，確保了跨運行時的流暢兼容性。
根據包的具體需求和配置，你可能需要對 package.json 進行或多或少的修改。仔細調整和測試該文件以確保其在發布時正常運行至關重要。
跨運行時部分
前面提到的步驟主要是在 Node.js 中設置雙模式兼容性。雖然 Deno 可以使用開箱即用的 npm 軟件包，但要創建一個完整的跨運行時包，你還應該將其適配到 Deno。
這包括閱讀 Deno 庫的工作原理[2]、將軟件包發布到 deno.land/x[3]。
還有就是，讓你的軟件包成為雙模式軟件也能幫助其他項目。
總結
創建雙模式、跨運行時的 JavaScript 包是一種有益的體驗。它能使你的代碼具有可移植性和可重用性，讓你在不同的 JavaScript 環境中接觸到更多的用戶。雖然會有一些障礙和注意事項，如管理兼容性以及與不同模塊系統和運行時的配合，但利大于弊。
本文譯自：https://hexagon.56k.guru/posts/dual-mode-cross-runtime-packages/
以上就是本文的全部內容，如果對你所有幫助，歡迎點贊、收藏、轉發~
參考資料
[1]GitHub:https://github.com/denoland/dnt
[2]Deno 庫的工作原理:https://deno.land/manual@v1.36.4/introduction
[3]將軟件包發布到 deno.land/x:https://deno.land/manual@v1.36.4/advanced/publishing
