Aller au contenu principal

Options

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 →

Les options peuvent être transmises à Babel de différentes manières. Lorsqu'elles sont passées directement à Babel, il suffit de fournir l'objet d'options. Lorsque Babel est utilisé via un wrapper, il peut être nécessaire, ou du moins plus pratique, de transmettre les options via des fichiers de configuration.

Si vous passez les options via @babel/cli, vous devrez utiliser la notation kebab-case pour les noms. Par exemple :

npx babel --root-mode upward file.js # equivalent of passing the rootMode config option

Options principales​

Ces options ne sont autorisées que dans le cadre des options programmatiques de Babel, elles sont donc principalement destinées aux outils qui encapsulent Babel ou aux personnes appelant directement babel.transform. Les utilisateurs des intégrations de Babel, comme babel-loader ou @babel/register, les utiliseront rarement.

cwd​

Type : string
Par défaut : process.cwd()

Le répertoire de travail auquel seront résolus tous les chemins dans les options programmatiques.

caller​

Type : Un objet de la forme

interface CallerData {
  name: string;
  supportsStaticESM?: boolean;
  supportsDynamicImport?: boolean;
  supportsTopLevelAwait?: boolean;
  supportsExportNamespaceFrom?: boolean;
}
History
VersionChanges
v7.11.0Add supportsExportNamespaceFrom
v7.7.0Add supportsTopLevelAwait
v7.5.0Add supportsDynamicImport

Les utilitaires peuvent passer un objet caller pour s'identifier auprès de Babel et transmettre des indicateurs de capacités utilisables par les configurations, presets et plugins. Par exemple :

JavaScript
babel.transformFileSync("example.js", {
  caller: {
    name: "my-custom-tool",
    supportsStaticESM: true,
  },
});

cela permettrait aux plugins et presets de décider que, puisque les modules ES sont pris en charge, ils ignoreront la compilation des modules ES en modules CommonJS.

filename​

Type : string

Le nom de fichier associé au code en cours de compilation, s'il existe. Le nom de fichier est optionnel, mais toutes les fonctionnalités de Babel ne sont pas disponibles lorsque le nom de fichier est inconnu, car un sous-ensemble d'options dépend du nom de fichier pour leur fonctionnement.

Les trois principaux cas que les utilisateurs peuvent rencontrer sont :

  • Le nom de fichier est exposé aux plugins. Certains plugins peuvent nécessiter sa présence.

  • Les options comme "test", "exclude" et "ignore" nécessitent le nom de fichier pour le filtrage par chaîne/expression régulière.

  • Les fichiers .babelrc.json ou .babelrc sont chargés relativement au fichier compilé. Si cette option est omise, Babel se comportera comme si babelrc: false était défini.

filenameRelative​

Type : string
Par défaut : path.relative(opts.cwd, opts.filename) (si "filename" est fourni)

Utilisée comme valeur par défaut pour l'option sourceFileName de Babel, et employée dans la génération des noms de fichiers pour les transformations de modules AMD/UMD/SystemJS.

code​

Type : boolean
Par défaut : true

La valeur de retour par défaut de Babel inclut les propriétés code et map avec le code généré résultant. Dans certains contextes où plusieurs appels à Babel sont effectués, il peut être utile de désactiver la génération de code et d'utiliser plutôt ast: true pour obtenir l'AST directement afin d'éviter un travail inutile.

ast​

Type : boolean
Par défaut : false

Par défaut, Babel génère une chaîne de caractères et une sourcemap, mais dans certains contextes, il peut être utile d'obtenir l'AST lui-même. Le principal cas d'utilisation serait une chaîne de plusieurs passes de transformation, comme dans

JavaScript
const filename = "example.js";
const source = fs.readFileSync(filename, "utf8");

// Load and compile file normally, but skip code generation.
const { ast } = babel.transformSync(source, {
  filename,
  ast: true,
  code: false,
});

// Minify the file in a second pass and generate the output code here.
const { code, map } = babel.transformFromAstSync(ast, source, {
  filename,
  presets: ["minify"],
  babelrc: false,
  configFile: false,
});

Remarque : Cette option n'est pas activée par défaut car la majorité des utilisateurs n'en auront pas besoin et parce que nous aimerions éventuellement ajouter une couche de cache à Babel. Le cache de la structure AST prendrait considérablement plus d'espace.

cloneInputAst​

Type : boolean
Par défaut : true
Ajouté dans v7.11.0

Par défaut, babel.transformFromAst clone l'AST d'entrée pour éviter les mutations. Spécifier cloneInputAst: false peut améliorer les performances d'analyse si l'AST d'entrée n'est pas utilisé ailleurs.

Options de chargement de configuration​

Le chargement de la configuration peut devenir un peu complexe car les environnements peuvent avoir plusieurs types de fichiers de configuration, et ces fichiers de configuration peuvent avoir divers objets de configuration imbriqués qui s'appliquent en fonction de la configuration.

root​

Type : string
Par défaut : opts.cwd
Emplacement : Autorisé uniquement dans les options programmatiques de Babel

Le chemin initial qui sera traité en fonction de "rootMode" pour déterminer le dossier racine conceptuel du projet Babel actuel. Ceci est utilisé dans deux cas principaux :

  • Le répertoire de base lors de la vérification de la valeur par défaut de "configFile"

  • La valeur par défaut pour "babelrcRoots".

rootMode​

Type : "root" | "upward" | "upward-optional"
Par défaut : "root"
Emplacement : Autorisé uniquement dans les options programmatiques de Babel
Ajouté dans : v7.1.0

Cette option, combinée avec la valeur "root", définit comment Babel choisit sa racine de projet. Les différents modes définissent différentes manières dont Babel peut traiter la valeur "root" pour obtenir la racine du projet finale.

Remarque : babel.config.json est pris en charge à partir de Babel 7.8.0. Dans les versions antérieures de Babel 7, seul babel.config.js est pris en charge.

Le mode "root" est le comportement par défaut car il évite le risque que Babel charge accidentellement un babel.config.json situé complètement en dehors du dossier projet actuel. Si vous utilisez "upward-optional", soyez conscient qu'il remontera l'arborescence des répertoires jusqu'à la racine du système de fichiers, et il est toujours possible qu'un babel.config.json oublié existe dans le répertoire personnel, ce qui pourrait provoquer des erreurs inattendues dans vos builds.

Les utilisateurs avec des structures monorepo exécutant des builds/tests par package voudront probablement utiliser "upward" car les monorepos ont souvent un babel.config.json à la racine du projet. Exécuter Babel dans un sous-répertoire monorepo sans "upward" empêchera le chargement des fichiers babel.config.json à la racine du projet, ce qui peut entraîner des erreurs inattendues et des échecs de compilation.

envName​

Type : string
Valeur par défaut : process.env.BABEL_ENV || process.env.NODE_ENV || "development"
Emplacement : Uniquement dans les options programmatiques de Babel

L'environnement actuellement actif utilisé pendant le chargement de la configuration. Cette valeur sert de clé lors de la résolution des configs "env" et est également disponible dans les fonctions de configuration, plugins et presets via la fonction api.env().

configFile​

Type : string | boolean
Valeur par défaut : path.resolve(opts.root, "babel.config.json") s'il existe, sinon false
Emplacement : Uniquement dans les options programmatiques de Babel

Recherche par défaut un fichier babel.config.json, mais peut recevoir le chemin de n'importe quel fichier de config JS ou JSON5.

NOTE : Cette option n'affecte pas le chargement des fichiers .babelrc.json. Bien qu'il soit tentant de faire configFile: "./foo/.babelrc.json", ce n'est pas recommandé. Si le .babelrc.json donné est chargé via la logique standard relative au fichier, vous chargerez le même fichier de config deux fois, le fusionnant avec lui-même. Si vous liez un fichier de config spécifique, privilégiez un schéma de nommage indépendant du nom "babelrc".

babelrc​

Type : boolean
Valeur par défaut : true si l'option filename est spécifiée
Emplacement : Autorisé dans les options programmatiques ou dans le "configFile" chargé. Une option programmatique écrase celle du fichier de config.

true activera la recherche de fichiers de configuration et de l'ancien fichier .babelignore relatifs au "filename" fourni à Babel.

Une valeur babelrc passée dans les options programmatiques écrasera celle définie dans un fichier de configuration.

Note : Les fichiers .babelrc.json ne sont chargés que si le "filename" actuel est dans un package correspondant à un des packages "babelrcRoots".

babelrcRoots​

Type : boolean | MatchPattern | Array<MatchPattern>
Valeur par défaut : opts.root
Emplacement : Autorisé dans les options programmatiques ou dans le configFile chargé. Une option programmatique écrase celle du fichier de config.

Par défaut, Babel ne recherchera les fichiers .babelrc.json qu'au sein du package "root", car sans cela Babel ne peut pas déterminer si un .babelrc.json donné doit être chargé, ou si ses "plugins" et "presets" sont installés, puisque le fichier compilé peut se trouver dans node_modules ou avoir été lié symboliquement au projet.

Cette option permet aux utilisateurs de fournir une liste d'autres packages devant être considérés comme packages "racine" lors de la décision de charger des fichiers .babelrc.json.

Par exemple, une configuration monorepo souhaitant autoriser des configurations individuelles pour chaque package pourrait utiliser :

JavaScript
babelrcRoots: [
  // Keep the root as a root
  ".",

  // Also consider monorepo packages "root" and load their .babelrc.json files.
  "./packages/*",
];

Options des plugins et presets​

plugins​

Type : Array<PluginEntry | Plugin> (PluginEntry)
Défaut : []

Tableau de plugins à activer lors du traitement de ce fichier. Pour plus d'informations sur l'interaction entre les entrées, notamment lorsqu'utilisées dans plusieurs configurations imbriquées "env" et "overrides", voir fusion.

Note : L'option accepte aussi des instances Plugin de Babel lui-même, mais leur utilisation directe est déconseillée. Si vous devez créer une représentation persistante d'un plugin ou preset, utilisez babel.createConfigItem().

presets​

Type : Array<PresetEntry> (PresetEntry)
Défaut : []

Tableau de presets à activer lors du traitement de ce fichier. Pour plus d'informations sur l'interaction entre les entrées, notamment lorsqu'utilisées dans plusieurs configurations imbriquées "env" et "overrides", voir fusion.

Note : Le format des presets est identique à celui des plugins, sauf que la normalisation des noms attend "preset-" au lieu de "plugin-", et que les presets ne peuvent pas être des instances de Plugin.

passPerPreset​

Type : boolean
Défaut : false
Statut : Déprécié

Ordonne à Babel d'exécuter chaque preset du tableau presets comme une passe indépendante. Cette option tend à introduire beaucoup de confusion sur l'ordre exact des plugins, mais peut être utile si vous devez absolument exécuter un ensemble d'opérations comme passes de compilation indépendantes.

Note : Cette option pourrait être supprimée dans les futures versions de Babel avec l'ajout d'un meilleur support pour définir l'ordre entre les plugins.

Cibles de sortie​

targets​

Type : string | Array<string> | { [string]: string }
Défaut : {}
Emplacement : Autorisé dans les options programmatiques de Babel ou les fichiers de configuration
Ajouté dans : v7.13.0

History
VersionChanges
v7.20.0Support deno target
v7.15.0Support rhino target

Décrit les environnements que vous prenez en charge/ciblez pour votre projet.

Cela peut être soit une requête compatible browserslist (avec des mises en garde) :

babel.config.json
{
  "targets": "> 0.25%, not dead"
}

Soit un objet des versions minimales d'environnement à supporter :

babel.config.json
{
  "targets": {
    "chrome": "58",
    "ie": "11"
  }
}

Environnements pris en charge : android, chrome, deno, edge, electron, firefox, ie, ios, node, opera, rhino, safari, samsung.

Si une version mineure n'est pas spécifiée, Babel l'interprétera comme MAJOR.0. Par exemple, "node": 12 sera considéré comme Node.js 12.0.

Aucune cible​

Lorsqu'aucune cible n'est spécifiée : Babel supposera que vous ciblez les navigateurs les plus anciens possibles. Par exemple, @babel/preset-env transformera tout le code ES2015-ES2020 pour être compatible ES5.

astuce

Nous recommandons de définir targets pour réduire la taille du code généré.

babel.config.json
{
  "presets": ["@babel/preset-env"]
}

De ce fait, le comportement de Babel diffère de browserslist : il n'utilise pas la requête defaults lorsqu'aucune cible n'est trouvée dans votre configuration Babel ou browserslist. Si vous souhaitez utiliser la requête defaults, vous devez l'indiquer explicitement comme cible :

babel.config.json
{
  "targets": "defaults"
}

Nous reconnaissons que ce n'est pas idéal et reviendrons sur ce point dans Babel v8.

targets.esmodules​

Type : boolean | "intersect"

History
VersionChanges
v7.13.0Support "intersect"

Vous pouvez également cibler les navigateurs prenant en charge les ES Modules. Lorsque l'option esmodules est définie à "intersect", elle s'intersectera avec la cible browsers et les cibles de browserslist. Vous pouvez utiliser cette approche avec <script type="module"></script> pour servir conditionnellement des scripts plus légers aux utilisateurs (https://jakearchibald.com/2017/es-modules-in-browsers/#nomodule-for-backwards-compatibility).

babel.config.json
{
  // Resolve to "Chrome 61+, FF60+, Safari 11+"
  "targets": {
    "esmodules": "intersect", // Chrome 61+, FF 60+, Safari 10.1+
    "browsers": "chrome 58, firefox 60, safari 11"
  }
}

Lorsque l'option esmodules est true, elle remplacera la cible browsers ou les cibles de browserslist.

astuce

Si vous utilisez defaults de browserslist comme cible, ou si vous prévoyez de prendre en charge les principaux navigateurs sortis en 2019 ou après, vous pouvez supprimer en toute sécurité esmodules car ces navigateurs prennent déjà en charge les ES Modules.

targets.node​

Type : string | "current" | true.

Si vous souhaitez compiler pour la version actuelle de Node, vous pouvez spécifier "node": true ou "node": "current", ce qui équivaut à "node": process.versions.node.

Alternativement, vous pouvez spécifier la version de Node dans une requête browserslist :

babel.config.json
{
  "targets": "node 12" // not recommended
}

Dans ce cas, browserslist la résoudra à la version la plus récente disponible dans la bibliothèque node-releases. Comme Node.js peut prendre en charge de nouvelles fonctionnalités du langage dans des versions mineures, un programme généré pour Node.js 12.22 peut générer une erreur de syntaxe sur Node.js 12.0. Nous vous recommandons de toujours spécifier une version mineure lorsque vous utilisez des requêtes node avec browserslist :

babel.config.json
{
  "targets": "node 12.0"
}

targets.safari​

Type : string | "tp".

Si vous souhaitez compiler pour la version technology preview de Safari, vous pouvez spécifier "safari": "tp".

targets.browsers​

Type : string | Array<string>.

Requête pour sélectionner les navigateurs (ex: last 2 versions, > 5%, safari tp) via browserslist.

Notez que les résultats des navigateurs sont remplacés par les éléments explicites de targets.

targets.deno​

Type : string.

La version minimale prise en charge est la 1.0.

babel.config.json
{
  "targets": {
    "deno": "1.9"
  }
}

browserslistConfigFile​

Type : boolean
Valeur par défaut : true
Emplacement : Autorisé dans les options programmatiques de Babel ou dans les fichiers de configuration
Ajouté dans : v7.13.0

Active ou désactive l'utilisation des sources de configuration browserslist, ce qui inclut la recherche de fichiers browserslist ou la référence à la clé browserslist dans package.json. Utile pour les projets utilisant une configuration browserslist pour des fichiers qui ne seront pas compilés avec Babel.

Si une chaîne est spécifiée, elle doit représenter le chemin d'un fichier de configuration browserslist. Les chemins relatifs sont résolus par rapport au fichier de configuration qui spécifie cette option, ou par rapport à cwd lorsqu'elle est passée dans les options programmatiques.

browserslistEnv​

Type : string
Valeur par défaut : undefined
Emplacement : Autorisé dans les options programmatiques de Babel ou dans les fichiers de configuration
Ajouté dans : v7.13.0

L'environnement Browserslist à utiliser.

Options de fusion de configuration​

extends​

Type : string
Emplacement : Non autorisé à l'intérieur des presets

Les configurations peuvent "étendre" d'autres fichiers de configuration. Les champs de configuration actuels seront fusionnés par-dessus la configuration du fichier étendu.

env​

Type : { [envKey: string]: Options }
Emplacement : Ne peut pas être imbriqué dans un autre bloc env

Permet des configurations imbriquées complètes qui ne seront activées que si envKey correspond à l'option envName.

Note : Les options env[envKey] seront fusionnées par-dessus les options spécifiées dans l'objet racine.

overrides​

Type : Array<Options>
Emplacement : Ne peut pas être imbriqué dans un autre objet overrides ou dans un bloc env

Permet de fournir un tableau d'options qui seront fusionnées dans la configuration actuelle une par une. Cette fonctionnalité est particulièrement utile avec les options "test"/"include"/"exclude" pour définir des conditions d'application. Par exemple :

JavaScript
overrides: [{
  test: "./vendor/large.min.js",
  compact: true,
}],

pourrait activer l'option compact pour un fichier spécifique connu pour être volumineux et minifié, indiquant à Babel de ne pas tenter de formater joliment ce fichier.

test​

Type : MatchPattern | Array<MatchPattern> (MatchPattern)

Si tous les motifs ne correspondent pas, l'objet de configuration courant est considéré comme inactif et ignoré pendant le traitement. Cette option est particulièrement utile dans un objet overrides, mais est autorisée partout.

Remarque : Ces options n'affectent pas les options programmatiques et de chargement de configuration des sections précédentes, car elles sont prises en compte bien avant la configuration préparée pour la fusion.

include​

Type : MatchPattern | Array<MatchPattern> (MatchPattern)

Cette option est synonyme de "test".

exclude​

Type : MatchPattern | Array<MatchPattern> (MatchPattern)

Si l'un des motifs correspond, l'objet de configuration actuel est considéré comme inactif et ignoré lors du traitement de la configuration. Cette option est particulièrement utile lorsqu'elle est utilisée dans un objet d'option overrides, mais elle est autorisée n'importe où.

Remarque : Ces options n'affectent pas les options programmatiques et de chargement de configuration des sections précédentes, car elles sont prises en compte bien avant la configuration préparée pour la fusion.

ignore​

Type : Array<MatchPattern> (MatchPattern)
Placement : Non autorisé dans les presets

Si l'un des motifs correspond, Babel arrêtera immédiatement tout traitement de la construction en cours. Par exemple, un utilisateur peut vouloir faire quelque chose comme

JavaScript
ignore: ["./lib"];

pour désactiver explicitement la compilation Babel des fichiers du répertoire lib.

Remarque : Cette option désactive tous les traitements Babel d'un fichier. Bien que cela ait son utilité, il vaut également la peine de considérer l'option "exclude" comme une alternative moins agressive.

only​

Type : Array<MatchPattern> (MatchPattern)
Placement : Non autorisé dans les presets

Si tous les motifs ne correspondent pas, Babel arrêtera immédiatement tout traitement de la construction en cours. Par exemple, un utilisateur peut vouloir faire quelque chose comme

JavaScript
only: ["./src"];

pour activer explicitement la compilation Babel des fichiers du répertoire src tout en désactivant tout le reste.

Remarque : Cette option désactive tous les traitements Babel d'un fichier. Bien que cela ait son utilité, il vaut également la peine de considérer les options "test"/"include" comme une alternative moins agressive.

Options des source maps​

inputSourceMap​

Type : boolean | SourceMap
Défaut : true

true tentera de charger une source map en entrée depuis le fichier lui-même, s'il contient un commentaire //# sourceMappingURL=.... Si aucune carte n'est trouvée, ou si la carte échoue au chargement ou à l'analyse, elle sera ignorée silencieusement.

Si un objet est fourni, il sera traité comme l'objet source map lui-même.

sourceMaps​

Type : boolean | "inline" | "both"
Défaut : false

  • true pour générer une source map du code et l'inclure dans l'objet résultat.

  • "inline" pour générer une source map et l'ajouter comme URL de données à la fin du code, sans l'inclure dans l'objet résultat.

  • "both" identique à inline, mais inclura la carte dans l'objet résultat.

Les options dans les fichiers de configuration n'affectent pas l'écriture de fichiers .map séparés par @babel/cli. Lorsque l'option CLI --source-maps est passée à @babel/cli, elle contrôlera également l'écriture des fichiers .map :

  • true écrira la carte dans un fichier .map sur le disque

  • "inline" écrira le fichier directement avec une data: contenant la carte

  • "both" écrira le fichier avec une URL data: et également un .map.

Remarque : Ces options sont quelque peu particulières, il peut donc être plus pertinent d'utiliser simplement true et de gérer le reste dans votre propre code selon votre cas d'utilisation.

sourceMap​

Ceci est un synonyme de sourceMaps. L'utilisation de sourceMaps est recommandée.

sourceFileName​

Type : string
Défaut : path.basename(opts.filenameRelative) lorsqu'il est disponible, sinon "unknown"

Le nom à utiliser pour le fichier dans l'objet source map.

sourceRoot​

Type : string

Les champs sourceRoot à définir dans la source map générée, si elle est souhaitée.

Options diverses​

sourceType​

Type : "script" | "module" | "commonjs" | "unambiguous"
Par défaut : "module"

  • "script" - Analyse le fichier en utilisant la grammaire ECMAScript Script. Les instructions import/export ne sont pas autorisées, et les fichiers ne sont pas en mode strict.

  • "module" - Analyse le fichier en utilisant la grammaire ECMAScript Module. Les fichiers sont automatiquement en mode strict, et les instructions import/export sont autorisées.

  • "commonjs" - Analyse le fichier tel qu'il sera exécuté dans un environnement CommonJS. Cette option est recommandée lors de la transformation de sources .cjs. Consultez la documentation du parseur pour les différences de syntaxe entre "script" et "commonjs".

  • "unambiguous" - Considère le fichier comme un "module" si des instructions import/export sont présentes, sinon le considère comme un "script".

unambiguous peut être très utile dans des contextes où le type est inconnu, mais cela peut entraîner des faux positifs car il est parfaitement valide d'avoir un fichier module sans instructions import/export.

Cette option est importante car le type du fichier courant affecte à la fois l'analyse des fichiers d'entrée et certaines transformations qui pourraient ajouter des usages de import/require au fichier actuel.

Par exemple, @babel/plugin-transform-runtime s'appuie sur le type du document courant pour décider s'il faut insérer une déclaration import ou un appel require(). @babel/preset-env fait de même pour son option "useBuiltIns". Comme Babel traite par défaut les fichiers comme des modules ES, ces plugins/presets inséreront généralement des instructions import. Définir le bon sourceType est crucial car un type incorrect peut conduire Babel à insérer des instructions import dans des fichiers destinés à être CommonJS. Ceci est particulièrement important dans les projets où la compilation des dépendances node_modules est effectuée, car l'insertion d'instructions import peut amener Webpack et d'autres outils à considérer un fichier comme un module ES, compromettant ainsi un fichier CommonJS par ailleurs fonctionnel.

Note : Cette option n'affectera pas l'analyse des fichiers .mjs, car ils sont actuellement codés en dur pour être toujours analysés comme des fichiers "module".

assumptions​

Type : { [assumption: string]: boolean }
Par défaut : {}
Ajouté dans : v7.13.0
Placement : Autorisé dans les options programmatiques, fichiers de config et presets.

Définissez des hypothèses que Babel peut faire pour produire un résultat plus compact :

babel.config.json
{
  "assumptions": {
    "iterableIsArray": true
  },
  "presets": ["@babel/preset-env"]
}

Pour plus d'informations, consultez la page de documentation sur les hypothèses.

highlightCode​

Type : boolean
Par défaut : true

Met en surbrillance les tokens dans les extraits de code des messages d'erreur de Babel pour faciliter leur lecture.

wrapPluginVisitorMethod​

Type : (key: string, nodeType: string, fn: Function) => Function

Permet aux utilisateurs d'ajouter un wrapper sur chaque visiteur afin d'inspecter le processus de visite pendant que Babel exécute les plugins.

  • key est une simple chaîne opaque représentant le plugin en cours d'exécution.

  • nodeType est le type du nœud AST actuellement visité.

  • fn est la fonction de visite elle-même.

Les utilisateurs peuvent renvoyer une fonction de remplacement qui doit appeler la fonction originale après avoir effectué les opérations de journalisation et d'analyse souhaitées.

parserOpts​

Type : {}

Objet opaque contenant les options à transmettre au parser utilisé.

Pour les options disponibles, voir Parser Options.

generatorOpts​

Type : {}

Objet opaque contenant les options à transmettre au générateur de code utilisé. Voir Code Generator Options pour les options les plus courantes.

Options du générateur de code​

retainLines​

Type : boolean
Par défaut : false

Babel s'efforcera de générer un code où les éléments sont imprimés sur la même ligne que dans le fichier original. Cette option existe pour que les utilisateurs ne pouvant pas utiliser les source maps obtiennent des numéros de ligne d'erreur vaguement utiles, mais il s'agit seulement d'un effort et aucune garantie n'est fournie dans tous les cas avec tous les plugins.

compact​

Type : boolean | "auto"
Par défaut : "auto"

"auto" définit la valeur en évaluant code.length > 500_000

Tous les sauts de ligne et espaces facultatifs seront omis lors de la génération de code en mode compact.

minified​

Type : boolean
Par défaut : false

Inclut compact: true, omet les points-virgules de fin de bloc, omet () dans new Foo() quand possible, et peut produire des versions plus courtes des littéraux.

auxiliaryCommentBefore​

Type : string

Permet de spécifier un commentaire préfixe à insérer avant les morceaux de code absents du fichier original.

Note : La définition de ce qui est présent ou non dans le fichier original peut devenir complexe, l'utilisation de cette option est donc déconseillée. Si vous devez annoter du code, il est préférable d'utiliser un plugin Babel.

auxiliaryCommentAfter​

Type : string

Permet de spécifier un commentaire préfixe à insérer après les morceaux de code absents du fichier original.

Note : La définition de ce qui est présent ou non dans le fichier original peut devenir complexe, l'utilisation de cette option est donc déconseillée. Si vous devez annoter du code, il est préférable d'utiliser un plugin Babel.

comments​

Type : boolean
Par défaut : true

Fournit un état de commentaire par défaut pour shouldPrintComment si aucune fonction n'est fournie. Voir la valeur par défaut de cette option pour plus d'informations.

shouldPrintComment​

Type : (value: string) => boolean
Par défaut sans minified : (val) => opts.comments || /@license|@preserve/.test(val)
Par défaut avec minified : () => opts.comments

Fonction déterminant si un commentaire donné doit être inclus dans le code généré par Babel.

Utilisation avancée​

Pour plus d'options du générateur, voir Generator Options.

Options des modules AMD / UMD / SystemJS​

moduleIds​

Type : boolean
Par défaut : !!opts.moduleId

Active la génération d'ID de module.

moduleId​

Type : string

Un ID fixe à utiliser pour le module. Ne peut pas être utilisé avec getModuleId.

getModuleId​

Type : (name: string) => string

Étant donné le nom de module généré par Babel, retourne le nom à utiliser. Retourner une valeur falsy utilisera le name original.

moduleRoot​

Type : string

Un chemin racine à inclure dans les noms de modules générés.

Concepts des options​

MatchPattern​

Type : string | RegExp | (filename: string | void, context: { caller: { name: string } | void, envName: string, dirname: string ) => boolean

Plusieurs options de Babel effectuent des tests sur les chemins de fichiers. Généralement, ces options supportent une approche par motif commun où chaque motif peut être :

  • string - Un chemin de fichier avec support basique pour **, * et *.ext. Tout fichier ou dossier parent correspondant au motif est considéré comme un match. Le chemin suit la logique normale de Node, donc sur POSIX il doit être séparé par /, tandis que sur Windows / et \ sont supportés.

  • RegExp - Une expression régulière à comparer avec le nom de fichier normalisé. Sur POSIX, le chemin RegExp s'exécutera contre un chemin séparé par /, et sur Windows par \.

Important : si l'une de ces approches est utilisée, Babel exige que l'option filename soit présente, et considérera cela comme une erreur dans le cas contraire.

  • (filename: string | void, context: { caller: { name: string } | void, envName: string, dirname: string }) => boolean est un callback général qui doit retourner un booléen indiquant s'il s'agit d'un match. La fonction reçoit le filename ou undefined si aucun n'a été fourni à Babel. Elle reçoit également les options envName et caller spécifiées par l'appel principal à Babel, et dirname qui est soit le dossier du fichier de configuration soit le répertoire de travail courant (si la transformation est appelée programmatiquement).
note

Le matching basé sur les chaînes ne supporte pas les motifs glob complets. ** correspond à 0 ou plusieurs parties de chemin, * correspond exactement à 1 partie de chemin, et *.ext correspond à un wildcard avec une extension. Utiliser * d'une autre manière, par exemple dans un chemin ou un nom de fichier, n'est pas supporté. Si vous avez besoin d'une correspondance de motifs complexes, utilisez un regex ou une fonction personnalisée dans la configuration.

Voici des exemples illustrant le fonctionnement de la correspondance :

DescriptionPatternMatchesDoes Not Match
Exact path matchingfoo/bar/src/foo/bar/src/foo, /src/foo/baz, /src/foo/bar/baz
Single wildcard (*)*/bar/src/foo/bar, /src/xyz/bar/src/foo/baz, /src/bar, /src/foo/bar/baz
Double wildcard (**)**/bar/src/bar, /src/foo/bar, /src/a/b/c/bar/src/bar/foo, /src/barfoo
File extension pattern (*.ext)foo/*.js/src/foo/test.js, /src/foo/index.js//src/foo/test.ts, /src/foo/test.js.map
Combined patterns**/test/*.js/src/test/file.js, /src/a/b/test/file.js/src/test.js, /src/test/sub/file.js

Voici des exemples où * n'a pas de fonction de wildcard :

DescriptionPatternDoes Not Match
Star in pathtest*me/*.js/src/testme/1.js, /src/testme/2.js, /src/test-me/3.js
Star in file namefoo*bar.js/src/foobar.js, /src/foo-bar.js
Star in extensionfile.ts*/src/file.ts, /src/file.tsx

Fusion​

Veuillez vous référer à Comment Babel fusionne les éléments de configuration.

Entrées de plugin/preset​

PluginEntry / PresetEntry​

Les éléments individuels de plugin/preset peuvent avoir plusieurs structures différentes :

  • EntryTarget - Plugin individuel

  • [EntryTarget, EntryOptions] - Plugin individuel avec options

  • [EntryTarget, EntryOptions, string] - Plugin individuel avec options et nom (voir fusion pour plus d'infos sur les noms)

  • ConfigItem - Élément de configuration de plugin créé par babel.createConfigItem().

Le même EntryTarget peut être utilisé plusieurs fois à moins que chacun ne reçoive un nom différent, et le faire autrement générera une erreur de plugin/preset en double.

Cela peut être difficile à lire, donc par exemple :

JavaScript
plugins: [
  // EntryTarget
  '@babel/plugin-transform-classes',

  // [EntryTarget, EntryOptions]
  ['@babel/plugin-transform-arrow-functions', { spec: true }],

  // [EntryTarget, EntryOptions, string]
  ['@babel/plugin-transform-for-of', { loose: true }, "some-name"],

  // ConfigItem
  babel.createConfigItem(require("@babel/plugin-transform-spread")),
],

EntryTarget​

Type : string | {} | Function

Une cible de plugin/preset peut provenir de différentes sources :

  • string - Un chemin de type require ou un identifiant de plugin/preset. Les identifiants seront normalisés via la normalisation de nom.

  • {} | Function - Un objet ou une fonction de plugin/preset après avoir été require().

EntryOptions​

Type: undefined | {} | false

Les options sont transmises à chaque plugin/preset lors de leur exécution. undefined sera normalisé en objet vide.

false indique qu'une entrée est complètement désactivée. Utile lorsque l'ordre est important mais qu'une condition séparée détermine l'activation. Par exemple :

JavaScript
plugins: [
  'one',
  ['two', false],
  'three',
],
overrides: [{
  test: "./src",
  plugins: [
    'two',
  ]
}]

activerait le plugin two pour les fichiers dans src, mais two s'exécuterait toujours entre one et three.

Normalisation de nom​

Par défaut, Babel attend que les plugins aient un préfixe babel-plugin- ou babel-preset-. Pour éviter les répétitions, une phase de normalisation ajoute automatiquement ces préfixes lors du chargement. Règles principales :

  • Les chemins absolus restent inchangés.

  • Les chemins relatifs commençant par ./ restent inchangés.

  • Les références à des fichiers dans un package restent inchangées.

  • Tout identifiant préfixé par module: verra le préfixe supprimé mais reste sinon inchangé.

  • plugin-/preset- sera injecté au début des packages scopés @babel sans ce préfixe.

  • babel-plugin-/babel-preset- sera préfixé aux packages non scopés sans ce préfixe.

  • babel-plugin-/babel-preset- sera préfixé aux packages scopés @ sans cette chaîne nulle part dans leur nom.

  • babel-plugin/babel-preset deviendra le nom du package si seul le nom de scope @ est fourni.

Exemples en contexte de plugin :

InputNormalized
"/dir/plugin.js""/dir/plugin.js"
"./dir/plugin.js""./dir/plugin.js"
"mod""babel-plugin-mod"
"mod/plugin""mod/plugin"
"babel-plugin-mod""babel-plugin-mod"
"@babel/mod""@babel/plugin-mod"
"@babel/plugin-mod""@babel/plugin-mod"
"@babel/mod/plugin""@babel/mod/plugin"
"@scope""@scope/babel-plugin"
"@scope/babel-plugin""@scope/babel-plugin"
"@scope/mod""@scope/babel-plugin-mod"
"@scope/babel-plugin-mod""@scope/babel-plugin-mod"
"@scope/prefix-babel-plugin-mod""@scope/prefix-babel-plugin-mod"
"@scope/mod/plugin""@scope/mod/plugin"
"module:foo""foo"