Node.js et esbuild : attention au mélange cjs et esm

TL;DR

Lorsque vous utilisez esbuild pour regrouper du code avec --platform=node qui dépend de packages npm avec un mélange de points d'entrée cjs et esm, utilisez la règle empirique suivante :

• Lorsque vous utilisez --bundle, définissez --format sur cjs. Cela fonctionnera dans tous les cas, sauf pour les modules esm avec attente de niveau supérieur.
  • --format=esm peut être utilisé mais nécessite un polyfill tel que celui-ci.
• Lorsque vous utilisez --packages=external, définissez --format sur esm.

Si vous vous interrogez sur la différence entre cjs et esm, jetez un œil à Node.js : un bref historique de cjs, bundlers et esm.

Symptôme

Lors de l'exécution du code groupé esbuild avec --platform=node, vous avez peut-être rencontré l'une des erreurs d'exécution suivantes :

Error: Dynamic require of "<module_name>" is not supported
</module_name>

Error [ERR_REQUIRE_ESM]: require() of ES Module (...) from (...) not supported.
Instead change the require of (...) in (...) to a dynamic import() which is available in all CommonJS modules.

Cause

Cela est dû à l'une des limitations suivantes :

• Transformations esm d'esbuild en cjs (et vice-versa).
• Interopérabilité Node.js cjs/esm.

Analyse

esbuild a des capacités de transformation limitées entre esm et cjs. De plus, certains scénarios, bien que pris en charge par esbuild, ne sont pas pris en charge par Node.js lui-même. Depuis esbuild@0.24.0, le tableau suivant résume ce qui est pris en charge :

Format	Scenario	Supported?
cjs	static import	Yes
cjs	dynamic import()	Yes
cjs	top-level await	No
cjs	--packages=external of esm entry point	No*
esm	require() of user modules**	Yes***
esm	require() of node:* modules	No****
esm	--packages=external of cjs entry point	Yes

* Pris en charge par esbuild mais pas par Node.js

** Fait référence aux packages npm ou aux fichiers de chemin relatif.

*** Les modules utilisateur sont pris en charge avec quelques mises en garde : __dirname et __filename ne sont pas pris en charge sans polyfill.

Nœud **** :* les modules peuvent être pris en charge avec le même polyfill.

Ce qui suit est une description détaillée de ces scénarios sans l'utilisation de polyfills :

---

paquets npm

Nous utiliserons les exemples de packages npm suivants :

importation statique

module esm avec un import statique :

Error: Dynamic require of "<module_name>" is not supported
</module_name>

importation dynamique

module esm avec un import() dynamique au sein d'une fonction asynchrone :

Error [ERR_REQUIRE_ESM]: require() of ES Module (...) from (...) not supported.
Instead change the require of (...) in (...) to a dynamic import() which is available in all CommonJS modules.

attente de niveau supérieur

module esm avec un import() dynamique et un wait de haut niveau :

import { version } from "node:process";

export function getVersion() {
  return version;
}

exiger

module cjs avec une invocation require() :

export async function getVersion() {
  const { version } = await import("node:process");
  return version;
}

---

--format=cjs

Nous exécuterons esbuild avec les arguments suivants :

const { version } = await import("node:process");

export function getVersion() {
  return version;
}

et le code suivant :

const { version } = require("node:process");

exports.getVersion = function() {
  return version;
}

importation statique

Produit ce qui suit qui fonctionne très bien :

esbuild --bundle --format=cjs --platform=node --outfile=bundle.cjs src/main.js

importation dynamique()

Produit ce qui suit qui fonctionne très bien :

import { getVersion } from "{npm-package}";

(async () => {
  // version can be `string` or `Promise<string>`
  const version = await getVersion();

  console.log(version);
})();
</string>

Remarquez comment l'import dynamique () n'est pas transformé en require() car il est également autorisé dans les modules cjs.

attente de haut niveau

esbuild échoue avec l'erreur suivante :

// node_modules/static-import/index.js
var import_node_process = require("node:process");
function getVersion() {
  return import_node_process.version;
}

// src/main.js
(async () => {
  const version2 = await getVersion();
  console.log(version2);
})();

--packages=externe

L'utilisation de --packages=external réussit avec tous les packages npm :

// (...esbuild auto-generated helpers...)

// node_modules/dynamic-import/index.js
async function getVersion() {
  const { version } = await import("node:process");
  return version;
}

// src/main.js
(async () => {
  const version = await getVersion();
  console.log(version);
})();

produit :

[ERROR] Top-level await is currently not supported with the "cjs" output format

    node_modules/top-level-await/index.js:1:20:
      1 │ const { version } = await import("node:process");
        ╵                     ~~~~~

Cependant, ils ne parviennent pas tous à s'exécuter car Nodes.js n'autorise pas les modules cjs à importer des modules esm :

esbuild --packages=external --format=cjs --platform=node --outfile=bundle.cjs src/main.js

---

--format=esm

Nous allons maintenant exécuter esbuild avec les arguments suivants :

var npm_package_import = require("{npm-package}");
(async () => {
  const version = await (0, npm_package_import.getVersion)();
  console.log(version);
})();

require() des modules utilisateur

src/main.js

/(...)/bundle.cjs:1
var import_static_import = require("static-import");
                           ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /(...)/node_modules/static-import/index.js from /(...)/bundle.cjs not supported.
Instead change the require of index.js in /(...)/bundle.cjs to a dynamic import() which is available in all CommonJS modules.

produit ce qui suit qui fonctionne très bien :

esbuild --bundle --format=esm --platform=node --outfile=bundle.mjs src/main.js

require() du nœud :* modules

src/main.js

const { getVersion } = require("static-import");

console.log(getVersion());

produit ce qui suit :

// (...esbuild auto-generated helpers...)

// node_modules/static-import/index.js
var static_import_exports = {};
__export(static_import_exports, {
  getVersion: () => getVersion
});
import { version } from "node:process";
function getVersion() {
  return version;
}
var init_static_import = __esm({
  "node_modules/static-import/index.js"() {
  }
});

// src/main.js
var { getVersion: getVersion2 } = (init_static_import(), __toCommonJS(static_import_exports));
console.log(getVersion2());

Cependant, il ne parvient pas à s'exécuter :

import { getVersion } from "require";

console.log(getVersion());

--packages=externe

L'utilisation de --packages=external réussit avec tous les packages npm, y compris ceux avec des points d'entrée cjs. Par exemple :

// (...esbuild auto-generated helpers...)

var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
}) : x)(function(x) {
  if (typeof require !== "undefined") return require.apply(this, arguments);
  throw Error('Dynamic require of "' + x + '" is not supported');
});

// (...esbuild auto-generated helpers...)

// node_modules/require/index.js
var require_require = __commonJS({
  "node_modules/require/index.js"(exports) {
    var { version } = __require("node:process");
    exports.getVersion = function() {
      return version;
    };
  }
});

// src/main.js
var import_require = __toESM(require_require());
console.log((0, import_require.getVersion)());

avec :

src/index.js

Error: Dynamic require of "node:process" is not supported

produit une sortie presque textuelle qui fonctionne très bien car les modules esm peuvent importer des packages npm avec des points d'entrée cjs :

esbuild --packages=external --format=esm --platform=node --outfile=bundle.mjs src/main.js

---

Conclusion

J'espère que cet article vous sera utile pour dépanner les sorties esbuild maintenant et à l'avenir. Faites-moi part de vos réflexions ci-dessous !

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!