Node.js : corriger les erreurs d’import ESM et CommonJS

Relevez le message exact et la version Node du processus qui échoue. Cette fiche concerne Node.js exécuté directement ; un bundler ou un runner de tests peut appliquer d’autres règles.

Identifier le format du fichier

Depuis le projet :

node --version
npm pkg get type engines scripts

Fichier ou configuration	Format explicite
`.mjs`	ES module : `import` / `export`
`.cjs`	CommonJS : `require` / `module.exports`
`.js` avec le `package.json` parent le plus proche contenant `"type": "module"`	ES module
`.js` avec `"type": "commonjs"`	CommonJS

Les versions récentes peuvent détecter la syntaxe ESM d’un .js ambigu. Déclarez le format attendu pour éviter de dépendre de cette détection. Un package.json imbriqué peut changer le format des fichiers de son dossier.

Partir du message d’erreur

Erreur	Vérification prioritaire
`require is not defined in ES module scope`	Code CommonJS exécuté comme ESM
`Cannot use import statement outside a module`	Fichier interprété comme CommonJS par le runtime ou l’outil
`ERR_MODULE_NOT_FOUND` / `MODULE_NOT_FOUND`	Chemin, extension, paquet installé et fichier généré
`ERR_PACKAGE_PATH_NOT_EXPORTED`	Import d’un sous-chemin privé du paquet
`does not provide an export named`	Export nommé demandé qui n’existe pas
`ERR_REQUIRE_ESM`	Version Node ou outil qui ne permet pas ce chargement via `require`
`ERR_REQUIRE_ASYNC_MODULE`	`require` tente de charger un graphe ESM avec un `await` au niveau supérieur

Corriger les imports locaux

Dans un projet ESM, utilisez des extensions explicites pour les fichiers exécutés par Node :

// calcul.mjs
export function doubler(nombre) {
  return nombre * 2;
}

// app.mjs
import { doubler } from "./calcul.mjs";
console.log(doubler(3));

Exécutez node app.mjs : le résultat attendu est 6. Pour un dossier, importez le fichier réel, par exemple ./utils/index.js. Un chemin relatif part du fichier importeur, pas du terminal. Vérifiez la casse : Client.js et client.js peuvent sembler équivalents sur un poste et échouer sous Linux.

Si votre application est compilée, contrôlez que les fichiers attendus existent dans le dossier de sortie. Un alias défini dans tsconfig.json n’est pas nécessairement compris par Node au runtime.

Faire communiquer les deux formats

Depuis CommonJS, import() permet de charger un module ESM, y compris asynchrone :

// app.cjs, à côté du fichier calcul.mjs précédent
async function main() {
  const { doubler } = await import("./calcul.mjs");
  console.log(doubler(3));
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Les versions Node récentes prennent aussi en charge require() pour certains modules ESM synchrones. Ne partez donc pas du principe qu’il est toujours interdit : vérifiez la version et l’absence d’await au niveau supérieur dans tout le graphe importé. import() reste adapté au cas asynchrone.

Depuis ESM vers un module CommonJS local :

// legacy.cjs
module.exports = { message: "Bonjour" };

// lecture.mjs
import legacy from "./legacy.cjs";
console.log(legacy.message);

L’import par défaut correspond à module.exports. Les exports nommés CommonJS reposent sur une détection qui ne couvre pas tous les cas. Pour une API exigeant réellement require, ESM permet d’en créer un avec createRequire(import.meta.url) depuis node:module.

Vérifier le paquet et les fichiers de configuration

Pour un paquet tiers, remplacez NOM_DU_PAQUET :

npm ls NOM_DU_PAQUET

Consultez la documentation de la version installée et son champ exports. Remplacez un import privé comme paquet/dist/interne.js par une entrée publique documentée. Modifier node_modules donne une correction perdue à la prochaine installation.

Si seul un fichier de configuration utilise encore module.exports, son renommage en .cjs peut suffire, si l’outil accepte ce nom. Ajouter "type": "module" à tout le projet change le traitement de tous ses .js concernés : vérifiez aussi les scripts, tests et configurations.

Vérifier le résultat

Relancez la commande exacte qui échouait, puis les tests et le build avec la version Node prévue en CI. Pour TypeScript exécuté après compilation, contrôlez le JavaScript produit et choisissez une configuration de modules cohérente avec votre runtime ; une configuration destinée au bundler n’a pas les mêmes garanties.