Aller au contenu principal

@babel/register

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

L'une des façons d'utiliser Babel est via le hook require. Ce hook s'intègre à require de Node et compile automatiquement les fichiers à la volée. Cela équivaut à coffee-script/register de CoffeeScript.

Installation​

npm install @babel/core @babel/register --save-dev

Utilisation​

JavaScript
require("@babel/register");

Tous les fichiers ultérieurement chargés par Node avec les extensions .es6, .es, .jsx, .mjs, et .js seront transformés par Babel.

Polyfill non inclus

Vous devez inclure séparément le polyfill lorsque vous utilisez des fonctionnalités qui en dépendent, comme les générateurs.

Ignore node_modules par défaut​

NOTE : Par défaut, tous les appels à node_modules seront ignorés. Vous pouvez contourner ce comportement en passant une regex d'ignore via :

JavaScript
require("@babel/register")({
  // This will override `node_modules` ignoring - you can alternatively pass
  // an array of strings to be explicitly matched or a regex / glob
  ignore: [],
});

Spécification des options​

JavaScript
require("@babel/register")({
  // Array of ignore conditions, either a regex or a function. (Optional)
  // File paths that match any condition are not compiled.
  ignore: [
    // When a file path matches this regex then it is **not** compiled
    /regex/,

    // The file's path is also passed to any ignore functions. It will
    // **not** be compiled if `true` is returned.
    function(filepath) {
      return filepath !== "/path/to/es6-file.js";
    },
  ],

  // Array of accept conditions, either a regex or a function. (Optional)
  // File paths that match all conditions are compiled.
  only: [
    // File paths that **don't** match this regex are not compiled
    /my_es6_folder/,

    // File paths that **do not** return true are not compiled
    function(filepath) {
      return filepath === "/path/to/es6-file.js";
    },
  ],

  // Setting this will remove the currently hooked extensions of `.es6`, `.es`, `.jsx`, `.mjs`
  // and .js so you'll have to add them back if you want them to be used again.
  extensions: [".es6", ".es", ".jsx", ".js", ".mjs"],

  // Setting this to false will disable the cache.
  cache: true,
});

Vous pouvez passer toutes les autres options, y compris plugins et presets. Notez que les fichiers de configuration seront aussi chargés et que la configuration programmatique fusionnera par-dessus. @babel/register ne prend pas en charge ignore et only dans les fichiers de configuration.

Variables d'environnement​

Par défaut, le CLI @babel/node et @babel/register sauvegardent un cache JSON dans votre répertoire temporaire.

Cela améliore significativement le démarrage et la compilation de vos fichiers. Il existe cependant des scénarios où vous souhaitez modifier ce comportement, et des variables d'environnement sont exposées pour vous le permettre.

BABEL_CACHE_PATH​

Spécifie un emplacement différent pour le cache.

Shell
BABEL_CACHE_PATH=/foo/my-cache.json babel-node script.js

BABEL_DISABLE_CACHE​

Désactive le cache.

Shell
BABEL_DISABLE_CACHE=1 babel-node script.js

Compilation à la volée des plugins et presets​

@babel/register utilise le système de hooks require() de Node pour compiler les fichiers dynamiquement lors de leur chargement. Bien que globalement utile, cela peut créer des situations confuses où le code dans un hook require() provoque davantage d'appels à require, créant un cycle de dépendances. Dans le cas de Babel, cela pourrait signifier que pendant la compilation d'un fichier utilisateur, Babel pourrait tenter de se compiler lui-même lors de son propre chargement.

Pour éviter ce problème, ce module interdit explicitement la compilation réentrante : la logique de compilation de Babel ne peut pas déclencher de compilation supplémentaire d'autres fichiers dynamiquement. L'inconvénient est que si vous souhaitez définir un plugin ou preset lui-même compilé dynamiquement, le processus devient complexe.

L'essentiel est que votre propre code doit charger le plugin/preset en premier. En supposant que le plugin/preset charge toutes ses dépendances immédiatement, vous devrez procéder ainsi :

require("@babel/register")({
  // ...
});

require("./my-plugin");

Comme c'est votre code qui déclenche le chargement, et non la logique interne de @babel/register, cela devrait compiler avec succès tout plugin/preset se chargeant de manière synchrone.

Implémentation expérimentale pour Babel 8​

Vous pouvez aussi tester la nouvelle implémentation expérimentale qui sera activée par défaut dans Babel 8, en utilisant

JavaScript
require("@babel/register/experimental-worker");

Elle exécute Babel de manière asynchrone en interne, donc compatible avec les fichiers de configuration .mjs. Vous pouvez déjà l'utiliser comme remplacement de @babel/register avec quelques réserves :

  • Si vous spécifiez programmatiquement les options de @babel/register (via require("@babel/register")({ /* ... options */ })), assurez-vous qu'elles sont sérialisables. Vous ne pouvez donc pas passer de fonctions de plugin définies inline, mais devez les déplacer dans un fichier séparé ./my-plugin.js ou dans un babel.config.js.

  • La nouvelle implémentation reste expérimentale : elle devrait offrir les mêmes fonctionnalités que la version actuelle, mais des nouveaux bogues et régressions peuvent apparaître.

Note : @babel/register ne prend pas en charge la compilation à la volée des modules ES natifs de Node.js, car aucune API stable n'existe actuellement pour intercepter le chargement des modules ES.