Aller au contenu principal

Configurer Babel

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 →

Babel peut être configuré ! De nombreux autres outils ont des configurations similaires : ESLint (.eslintrc), Prettier (.prettierrc).

Toutes les options de l'API Babel sont autorisées. Cependant, si une option nécessite du JavaScript, vous devriez utiliser un fichier de configuration JavaScript.

Quel est votre cas d'utilisation ?​

  • Vous utilisez un monorepo ?

  • Vous souhaitez compiler node_modules ?

babel.config.json est fait pour vous !

  • Vous avez une configuration qui ne s'applique qu'à une partie spécifique de votre projet ?

.babelrc.json est fait pour vous !

  • Guy Fieri est votre héros ?

Nous recommandons d'utiliser le format babel.config.json.

babel.config.json​

Créez un fichier nommé babel.config.json avec le contenu suivant à la racine de votre projet (là où se trouve le package.json).

babel.config.json
{
  "presets": [...],
  "plugins": [...]
}

Consultez la documentation de babel.config.json pour voir plus d'options de configuration.

.babelrc.json​

Créez un fichier nommé .babelrc.json avec le contenu suivant dans votre projet.

.babelrc.json
{
  "presets": [...],
  "plugins": [...]
}

Consultez la documentation .babelrc pour voir plus d'options de configuration.

package.json​

Alternativement, vous pouvez spécifier votre configuration .babelrc.json directement dans le package.json en utilisant la clé babel comme suit :

package.json
{
  "name": "my-package",
  "version": "1.0.0",
  "babel": {
    "presets": [ ... ],
    "plugins": [ ... ],
  }
}

Fichiers de configuration JavaScript​

Vous pouvez également écrire des fichiers babel.config.js (comme nous le faisons) et .babelrc.js en JavaScript :

babel.config.js
module.exports = function (api) {
  api.cache(true);

  const presets = [ ... ];
  const plugins = [ ... ];

  return {
    presets,
    plugins
  };
}

Vous pouvez utiliser toutes les API Node.js, par exemple pour une configuration dynamique basée sur l'environnement d'exécution :

babel.config.js
module.exports = function (api) {
  api.cache(true);

  const presets = [ ... ];
  const plugins = [ ... ];

  if (process.env["ENV"] === "prod") {
    plugins.push(...);
  }

  return {
    presets,
    plugins
  };
}

Vous pouvez en savoir plus sur les fichiers de configuration JavaScript dans la documentation dédiée.

Utilisation de la CLI (@babel/cli)​

Shell
babel --plugins @babel/plugin-transform-arrow-functions script.js

Consultez la documentation de babel-cli pour voir plus d'options de configuration.

Utilisation de l'API (@babel/core)​

JavaScript
require("@babel/core").transformSync("code", {
  plugins: ["@babel/plugin-transform-arrow-functions"],
});

Consultez la documentation de babel-core pour voir plus d'options de configuration.

Afficher les configurations effectives​

Vous pouvez demander à Babel d'afficher les configurations effectives pour un chemin d'entrée donné.

# *nix or WSL
BABEL_SHOW_CONFIG_FOR=./src/myComponent.jsx npm start

BABEL_SHOW_CONFIG_FOR accepte les chemins de fichiers absolus et relatifs. S'il s'agit d'un chemin relatif, il sera résolu à partir du cwd.

Une fois que Babel a traité le fichier d'entrée spécifié par BABEL_SHOW_CONFIG_FOR, il affichera les configurations effectives dans la console. Voici un exemple de sortie :

Babel configs on "/path/to/cwd/src/index.js" (ascending priority):
config /path/to/cwd/babel.config.json
{
  "sourceType": "script",
  "plugins": [
    "@foo/babel-plugin-1"
  ],
  "extends": "./my-extended.js"
}

config /path/to/cwd/babel.config.json .env["test"]
{
  "plugins": [
    [
      "@foo/babel-plugin-3",
      {
        "noDocumentAll": true
      },
    ]
  ]
}

config /path/to/cwd/babel.config.json .overrides[0]
{
  "test": "src/index.js",
  "sourceMaps": true
}

config /path/to/cwd/.babelrc
{}

programmatic options from @babel/cli
{
  "sourceFileName": "./src/index.js",
  "presets": [
    "@babel/preset-env"
  ],
  "configFile": "./my-config.js",
  "caller": {
    "name": "@babel/cli"
  },
  "filename": "./src/index.js"
}

Babel affiche les sources de configuration effective par ordre de priorité croissante. En reprenant l'exemple ci-dessus, la priorité est :

babel.config.json < .babelrc < programmatic options from @babel/cli

Autrement dit, babel.config.json est écrasé par .babelrc, et .babelrc est écrasé par les options programmatiques.

Pour chaque source de configuration, Babel affiche les éléments applicables (par ex. overrides et env) par ordre de priorité croissante. Généralement, chaque source contient au moins un élément configuré - le contenu racine. Si vous avez configuré overrides ou env, Babel ne les affichera pas à la racine, mais générera plutôt un élément distinct intitulé .overrides[index] où index représente la position de l'élément. Cela permet de déterminer si l'élément est effectif pour l'entrée et quelles configurations il remplace.

Si votre entrée est ignorée par ignore ou only, Babel indiquera que ce fichier est ignoré.

Comment Babel fusionne les éléments de configuration​

La fusion des configurations dans Babel est relativement simple. Les options écrasent les options existantes lorsqu'elles sont présentes et que leur valeur n'est pas undefined. Cependant, quelques cas particuliers existent :

  • Pour assumptions, parserOpts et generatorOpts, les objets sont fusionnés plutôt que remplacés.

  • Pour plugins et presets, ils sont remplacés en fonction de l'identité du plugin/présentiel (objet/fonction) combinée au nom de l'entrée.

Fusion des options (sauf plugins/présets)​

Prenons par exemple une configuration avec :

JavaScript
{
  sourceType: "script",
  assumptions: {
    setClassFields: true,
    iterableIsArray: false
  },
  env: {
    test: {
      sourceType: "module",
      assumptions: {
        iterableIsArray: true,
      },
    }
  }
};

Lorsque NODE_ENV est test, l'option sourceType sera remplacée et l'option assumptions sera fusionnée. La configuration effective est :

JavaScript
{
  sourceType: "module", // sourceType: "script" is overwritten
  assumptions: {
    setClassFields: true,
    iterableIsArray: true, // assumptions are merged by Object.assign
  },
}

Fusion de plugins/presets​

Prenons par exemple une configuration avec :

JavaScript
plugins: [
  './other',
  ['./plug', { thing: true, field1: true }]
],
overrides: [{
  plugins: [
    ['./plug', { thing: false, field2: true }],
  ]
}]

L'élément overrides sera fusionné par-dessus les options de niveau supérieur. Il est important de noter que le tableau plugins dans son ensemble ne remplace pas simplement celui du niveau supérieur. La logique de fusion détectera que "./plug" est le même plugin dans les deux cas, et { thing: false, field2: true } remplacera les options d'origine, ce qui donnera une configuration comme

JavaScript
plugins: [
  './other',
  ['./plug', { thing: false, field2: true }],
],

Comme la fusion repose sur l'identité + le nom, il est considéré comme une erreur d'utiliser le même plugin avec le même nom deux fois dans le même tableau plugins/presets. Par exemple

JavaScript
plugins: ["./plug", "./plug"];

est considéré comme une erreur, car il est identique à plugins: ['./plug']. De plus, même

JavaScript
plugins: [["./plug", { one: true }], ["./plug", { two: true }]];

est considéré comme une erreur, car le second remplacerait systématiquement le premier.

Si vous souhaitez réellement instancier deux instances distinctes d'un plugin, vous devez leur attribuer un nom unique pour les distinguer. Par exemple :

JavaScript
plugins: [
  ["./plug", { one: true }, "first-instance-name"],
  ["./plug", { two: true }, "second-instance-name"],
];

parce que chaque instance a reçu un nom unique et donc une identité unique.