Fichiers de configuration

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 →

Types de fichiers de configuration

Babel propose deux formats de fichiers de configuration parallèles, utilisables conjointement ou indépendamment.

History

Version	Changes
v7.21.0	Support .babelrc.cts and babel.config.cts (Experimental)
v7.8.0	Support .babelrc.mjs and babel.config.mjs
v7.7.0	Support .babelrc.json, .babelrc.cjs, babel.config.json, babel.config.cjs

• Configuration à l'échelle du projet

  • Fichiers babel.config.* avec extensions : .json, .js, .cjs, .mjs, .cts.

• Configuration relative aux fichiers

  • Fichiers .babelrc.* avec extensions : .json, .js, .cjs, .mjs, .cts.
  • Fichier .babelrc sans extension.
  • Fichiers package.json avec une clé "babel".

Configuration à l'échelle du projet

Nouveauté de Babel 7.x : le concept de répertoire "root" par défaut correspondant au répertoire de travail actuel. Pour une configuration globale, Babel recherche automatiquement un fichier babel.config.json (ou équivalent avec les extensions supportées) dans ce répertoire racine. L'option "configFile" permet de remplacer ce comportement par défaut.

Étant dissociés de leur emplacement physique, ces fichiers de configuration globale sont idéaux pour des réglages étendus, permettant même aux plugins et presets de s'appliquer aux fichiers dans node_modules ou aux packages symlinkés - configuration historiquement complexe dans Babel 6.x.

L'inconvénient majeur est leur dépendance au répertoire de travail, ce qui peut compliquer leur utilisation dans les monorepos si ce répertoire n'est pas la racine du monorepo. Consultez la documentation monorepo pour des exemples d'implémentation.

Désactivez cette configuration via "configFile" = false.

Configuration relative aux fichiers

Babel charge les fichiers .babelrc.json (ou équivalents avec extensions supportées) en remontant l'arborescence depuis le "filename" compilé (sous réserves ci-dessous). Cette approche permet des configurations indépendantes pour des sous-sections d'un package. Les configurations relatives sont fusionnées par-dessus les valeurs globales, permettant des surcharges spécifiques (alternative à "overrides").

Cas particuliers à connaître :

• La recherche s'arrête à l'identification d'un package.json, limitant la portée à un seul package.

• Le "filename" compilé doit impérativement se situer dans des packages "babelrcRoots", sinon la recherche est ignorée.

Ces contraintes impliquent que :

• Les .babelrc.json s'appliquent UNIQUEMENT aux fichiers de leur propre package

• Les .babelrc.json des packages non racines de Babel sont ignorés sauf activation via "babelrcRoots".

Voir la documentation monorepo pour configurer des monorepos multi-packages. Désactivez cette configuration via "babelrc" = false.

Chargement .babelrc : 6.x vs 7.x

Les utilisateurs de Babel 6.x rencontreront ces nouveautés de la 7.x. Ces restrictions corrigent des problèmes récurrents :

• Les fichiers .babelrc s'appliquaient aux dépendances node_modules, souvent de manière inattendue.

• Les fichiers .babelrc échouaient à s'appliquer aux node_modules liés symboliquement alors qu'on s'attendait à ce qu'ils se comportent comme des dépendances normales.

• Les fichiers .babelrc dans les dépendances node_modules étaient détectés, bien que les plugins et presets qu'ils contenaient n'étaient généralement pas installés, et pouvaient même être incompatibles avec la version de Babel compilant le fichier.

Ces cas poseront principalement problème aux utilisateurs ayant une structure monorepo, car si vous avez

.babelrc
packages/
  mod1/
    package.json
    src/index.js
  mod2/
    package.json
    src/index.js

la configuration sera désormais entièrement ignorée car elle franchit une limite de package.

Une alternative consisterait à créer un .babelrc dans chaque sous-package utilisant "extends" comme suit :

.babelrc.json

{ "extends": "../../.babelrc" }

Malheureusement, cette approche peut être répétitive et, selon l'utilisation de Babel, pourrait nécessiter de définir "babelrcRoots".

Compte tenu de cela, il peut être préférable de renommer le .babelrc en un "babel.config.json" global. Comme mentionné dans la section sur la configuration globale, cela pourrait alors nécessiter de définir explicitement "configFile" car Babel ne trouvera pas le fichier de configuration si le répertoire de travail est incorrect.

Extensions de fichiers prises en charge

Babel peut être configuré en utilisant toute extension de fichier nativement supportée par Node.js, comme mentionné dans la section Types de fichiers de configuration :

• babel.config.json et .babelrc.json sont analysés comme du JSON5 et doivent contenir un objet correspondant au format des options acceptées par Babel. Supportés depuis v7.7.0.

  Nous recommandons d'utiliser ce type de fichier autant que possible : les fichiers de configuration JS sont pratiques pour une configuration complexe conditionnelle ou calculée au moment de la compilation. Cependant, l'inconvénient est que les configurations JS sont moins statiquement analysables, ce qui nuit à la mise en cache, au linting, à l'autocomplétion des IDE, etc. Comme babel.config.json et .babelrc.json sont des fichiers JSON statiques, ils permettent à d'autres outils utilisant Babel (comme les bundlers) de cacher en toute sécurité les résultats de Babel, ce qui peut représenter un gain de performance significatif.

• babel.config.cjs et .babelrc.cjs permettent de définir la configuration en CommonJS via module.exports. Supportés depuis v7.7.0.

• babel.config.mjs et .babelrc.mjs utilisent les modules ECMAScript natifs. Supportés par Node.js 13.2+ (ou versions antérieures via le flag --experimental-modules). Rappelez-vous que les modules ECMAScript natifs sont asynchrones (c'est pourquoi import() renvoie toujours une promesse !) : pour cette raison, les fichiers .mjs généreront une erreur lors d'un appel synchrone à Babel. Supportés depuis v7.8.0.

• babel.config.js et .babelrc.js se comportent comme leurs équivalents .mjs si votre package.json contient l'option "type": "module", sinon ils sont identiques aux fichiers .cjs.

• babel.config.cts et .babelrc.cts permettent de définir la configuration en TypeScript + CommonJS. Vous devez installer @babel/preset-typescript ou exécuter Babel via ts-node.

  note

  🚧 Cette fonctionnalité est expérimentale. Les fichiers babel.config.ts et babel.config.mts ne sont pas encore supportés, en attente de stabilisation de l'API de chargement ESM de Node.js.

Les fichiers de configuration JavaScript peuvent exporter soit un objet, soit une fonction qui renvoie la configuration générée. Les configurations sous forme de fonction disposent de capacités spéciales car elles peuvent accéder à une API exposée par Babel lui-même. Voir API des fonctions de configuration pour plus d'informations.

note

Pour des raisons de compatibilité, .babelrc est un alias pour .babelrc.json.

Monorepos

Les dépôts structurés en monorepo contiennent généralement de nombreux paquets, ce qui signifie qu'ils rencontrent fréquemment les limitations mentionnées dans la configuration relative aux fichiers et le chargement des fichiers de configuration en général. Cette section vise à aider les utilisateurs à comprendre comment aborder la configuration des monorepos.

Avec les configurations monorepo, l'élément essentiel à comprendre est que Babel considère votre répertoire de travail comme sa "root" logique, ce qui pose problème si vous souhaitez exécuter les outils Babel dans un sous-paquet spécifique sans que Babel ne s'applique à l'ensemble du dépôt.

Par ailleurs, il est également important de décider si vous souhaitez utiliser des fichiers .babelrc.json ou simplement un fichier central babel.config.json. Les fichiers .babelrc.json ne sont plus nécessaires pour la configuration spécifique aux sous-dossiers comme c'était le cas dans Babel 6 ; ils sont donc souvent inutiles dans Babel 7, au profit du fichier babel.config.json.

Fichier racine babel.config.json

La première étape dans toute structure monorepo devrait être de créer un fichier babel.config.json à la racine du dépôt. Cela établit le concept fondamental de Babel concernant le répertoire de base de votre dépôt. Même si vous souhaitez utiliser des fichiers .babelrc.json pour configurer chaque paquet séparé, il est important d'avoir ce fichier comme emplacement pour les options au niveau du dépôt.

Vous pouvez souvent placer toute la configuration de votre dépôt dans le fichier racine babel.config.json. Grâce aux "overrides", vous pouvez facilement spécifier une configuration qui ne s'applique qu'à certains sous-dossiers de votre dépôt, ce qui est souvent plus simple à gérer que de créer de nombreux fichiers .babelrc.json à travers le dépôt.

Le premier problème auquel vous serez probablement confronté est que par défaut, Babel s'attend à charger les fichiers babel.config.json à partir du répertoire défini comme sa "root", ce qui signifie que si vous créez un fichier babel.config.json mais exécutez Babel à l'intérieur d'un paquet individuel, par exemple :

Shell

cd packages/some-package;
babel src -d dist

la "racine" que Babel utilise dans ce contexte n'est pas la racine de votre monorepo, et il ne pourra pas trouver le fichier babel.config.json.

Si tous vos scripts de build s'exécutent relativement à la racine de votre dépôt, les choses devraient déjà fonctionner, mais si vous exécutez votre processus de compilation Babel depuis un sous-paquet, vous devez indiquer à Babel où chercher la configuration. Il existe plusieurs façons de le faire, mais la méthode recommandée est l'option "rootMode" avec "upward", qui fera que Babel recherchera à partir du répertoire de travail vers le haut votre fichier babel.config.json, et utilisera son emplacement comme valeur "root".

Une méthode utile pour vérifier si votre configuration est détectée consiste à placer un appel console.log() à l'intérieur si c'est un fichier JavaScript babel.config.json : le log s'exécutera lors du premier chargement par Babel.

La manière de définir cette valeur varie selon le projet, mais voici quelques exemples :

CLI

Shell

babel --root-mode upward src -d lib

@babel/register

JavaScript

require("@babel/register")({
  rootMode: "upward",
});

Webpack

webpack.config.js

module: {
  rules: [
    {
      loader: "babel-loader",
      options: {
        rootMode: "upward",
      },
    },
  ];
}

Jest

Jest est souvent installé à la racine du monorepo et peut ne pas nécessiter de configuration, mais s'il est installé par paquet, cela peut malheureusement être plus complexe à configurer.

L'essentiel consiste à créer un fichier transformeur Jest personnalisé qui encapsule le comportement par défaut de babel-jest afin de définir l'option, par exemple :

wrapper.js

module.exports = require("babel-jest").default.createTransformer({
  rootMode: "upward",
});

et après avoir enregistré ce fichier quelque part, vous l'utiliseriez à la place de babel-jest dans vos options Jest via l'option transform :

jest.config.js

"transform": {
  "^.+\\.jsx?$": "./path/to/wrapper.js"
},

donc tous les fichiers JS seront traités avec votre version de babel-jest avec l'option activée.

note

Lorsque vous utilisez babel-jest < 27, vous devez omettre la partie .default : require("babel-jest").createTransformer({ ....

Autres

Il existe de nombreux outils, mais au cœur du sujet, ils nécessitent que l'option rootMode soit activée si le répertoire de travail n'est pas déjà la racine du monorepo.

Fichiers .babelrc.json des sous-paquets

À l'instar des fichiers babel.config.json qui doivent se trouver dans la "root", les fichiers .babelrc.json doivent par défaut se situer dans le package racine. Cela signifie que, de la même manière que le répertoire de travail affecte le chargement de babel.config.json, il affecte également le chargement de .babelrc.json.

En supposant que vous ayez correctement chargé votre fichier babel.config.json comme discuté précédemment, Babel ne traitera que les fichiers .babelrc.json situés dans ce package racine (et non dans les sous-paquets). Par exemple :

package.json
babel.config.js
packages/
  mod/
    package.json
    .babelrc.json
    index.js

la compilation du fichier packages/mod/index.js ne chargera pas packages/mod/.babelrc.json car ce .babelrc.json se trouve dans un sous-package, non dans le package racine.

Pour activer le traitement de ce .babelrc.json, vous devrez utiliser l'option "babelrcRoots" dans votre fichier babel.config.json pour :

JavaScript

babelrcRoots: [
  ".",
  "packages/*",
],

permettre à Babel de considérer tous les packages packages/* comme autorisés à charger des fichiers .babelrc.json, ainsi que la racine originale du dépôt.

API de fonction de configuration

Les fichiers de configuration JS peuvent exporter une fonction qui reçoit l'API de configuration en paramètre :

babel.config.js

module.exports = function(api) {
  return {};
};

L'objet ConfigAPI api expose les propriétés ou méthodes suivantes :

api.version

Type : string

La chaîne de version de Babel qui charge le fichier de configuration.

api.cache

Les configurations JS sont puissantes car elles permettent de calculer une configuration dynamiquement, mais l'inconvénient est qu'elles compliquent la mise en cache. Babel souhaite éviter de réexécuter la fonction de configuration à chaque compilation de fichier, car cela nécessiterait également de réexécuter toutes les fonctions de plugins et presets référencées dans cette configuration.

Pour contourner ce problème, Babel attend des utilisateurs de fonctions de configuration qu'ils indiquent comment gérer la mise en cache dans le fichier de configuration.

• api.cache.forever() - Met en cache permanente la configuration calculée sans jamais rappeler la fonction.

• api.cache.never() - Ne met pas en cache cette configuration et réexécute la fonction à chaque fois.

• api.cache.using(() => process.env.NODE_ENV) - Met en cache en fonction de la valeur de NODE_ENV. Chaque fois que le callback using renvoie une valeur différente de celle attendue, la fonction de configuration globale sera rappelée et une nouvelle entrée sera ajoutée au cache.

• api.cache.invalidate(() => process.env.NODE_ENV) - Met en cache en fonction de la valeur de NODE_ENV. Chaque fois que le callback using retourne une valeur différente de celle attendue, la fonction de configuration entière sera rappelée et toutes les entrées du cache seront remplacées par le résultat.

• api.cache(true) - Équivalent à api.cache.forever()

• api.cache(false) - Équivalent à api.cache.never()

Comme le résultat réel du callback est utilisé pour vérifier la validité de l'entrée du cache, il est recommandé :

• Que les callbacks soient courts et sans effets de bord.

• Que les callbacks retournent des valeurs ayant la plage de valeurs la plus réduite possible. Par exemple, l'utilisation .using(() => process.env.NODE_ENV) ci-dessus n'est pas idéale car elle créerait un nombre inconnu d'entrées de cache selon les valeurs détectées de NODE_ENV. Il serait plus sûr d'utiliser .using(() => process.env.NODE_ENV === "development") car l'entrée du cache ne pourrait alors être que true ou false.

api.env(...)

Comme NODE_ENV est une méthode courante pour modifier le comportement, Babel inclut une fonction API dédiée. Cette API permet de vérifier rapidement "envName" avec lequel Babel a été chargé, qui prend en compte NODE_ENV si aucun autre environnement prioritaire n'est défini.

Elle se présente sous plusieurs formes :

• api.env("production") retourne true si envName === "production".

• api.env(["development", "test"]) retourne true si ["development", "test"].includes(envName).

• api.env() retourne la chaîne envName actuelle.

• api.env(envName => envName.startsWith("test-")) retourne true si l'environnement commence par "test-".

note

Cette fonction utilise en interne api.cache mentionné ci-dessus pour s'assurer que Babel sait que cette compilation dépend d'un envName spécifique. Elle ne doit pas être utilisée conjointement avec api.cache.forever() ou api.cache.never().

api.caller(cb)

Cette API permet d'accéder aux données caller transmises à Babel. Comme plusieurs instances de Babel peuvent s'exécuter dans le même processus avec des valeurs caller différentes, cette API est conçue pour configurer automatiquement api.cache, de la même manière que api.env().

La valeur caller est disponible comme premier paramètre de la fonction de callback. Elle est optimale pour :

JavaScript

function isBabelRegister(caller) {
  return !!(caller && caller.name === "@babel/register");
}

module.exports = function(api) {
  const isRegister = api.caller(isBabelRegister);

  return {
    // ...
  };
};

modifier le comportement de configuration selon un environnement spécifique.

api.assertVersion(range)

Bien qu'api.version soit généralement utile, il est parfois préférable de simplement déclarer votre version. Cette API expose une méthode simple pour le faire avec :

JavaScript

module.exports = function(api) {
  api.assertVersion("^7.2");

  return {
    // ...
  };
};