@babel/preset-env

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/preset-env est un preset intelligent qui vous permet d'utiliser les dernières fonctionnalités JavaScript sans avoir à gérer manuellement quelles transformations syntaxiques (et optionnellement, quels polyfills navigateur) sont nécessaires pour vos environnements cibles. Cela simplifie votre travail et réduit la taille des bundles JavaScript !

Installation
Fonctionnement
Intégration Browserslist
Options

Installation

npm
Yarn
pnpm
Bun

npm install --save-dev @babel/preset-env

yarn add --dev @babel/preset-env

pnpm add --save-dev @babel/preset-env

bun add --dev @babel/preset-env

Fonctionnement

@babel/preset-env n'existerait pas sans plusieurs projets open-source remarquables comme browserslist, compat-table et electron-to-chromium.

Nous exploitons ces sources de données pour maintenir des correspondances indiquant à partir de quelle version nos environnements cibles supportés ont acquis une fonctionnalité JavaScript ou navigateur, ainsi qu'un mapping entre ces syntaxes/fonctionnalités et les plugins de transformation Babel ou les polyfills core-js.

note

@babel/preset-env n'inclura aucune proposition de syntaxe JavaScript inférieure au Stage 3 car à ce stade du processus TC39, elle ne serait de toute façon implémentée par aucun navigateur. Celles-ci doivent être incluses manuellement. L'option shippedProposals inclura les propositions Stage 3 déjà implémentées par certains navigateurs.

@babel/preset-env prend les environnements cibles spécifiés, les compare à ses mappings pour compiler une liste de plugins, et la transmet à Babel.

Intégration Browserslist

Pour les projets basés sur des navigateurs ou Electron, nous recommandons d'utiliser un fichier .browserslistrc pour spécifier les cibles. Vous possédez peut-être déjà ce fichier de configuration car il est utilisé par de nombreux outils de l'écosystème comme autoprefixer, stylelint, eslint-plugin-compat et bien d'autres.

Par défaut, @babel/preset-env utilisera les sources de configuration browserslist sauf si l'option targets ou ignoreBrowserslistConfig est définie.

astuce

Si vous comptez sur la requête par défaut de browserslist (explicitement ou par absence de configuration browserslist), consultez la section Aucune cible pour comprendre le comportement de preset-env.

Par exemple, pour n'inclure que les polyfills et transformations nécessaires aux utilisateurs dont les navigateurs ont >0.25% de parts de marché (en excluant les navigateurs sans mises à jour de sécurité comme IE 10 et BlackBerry) :

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "entry",
        "corejs": "3.22"
      }
    ]
  ]
}

.browserslistrc
> 0.25%
not dead

package.json
{ "browserslist": "> 0.25%, not dead" }

note

Notez qu'à partir de v7.4.5, la requête browserslist est résolue avec mobileToDesktop: true. Par exemple, pour créer un instantané d'une requête : npx browserslist --mobile-to-desktop ">0.25%, not dead".

Options

Pour plus d'informations sur la configuration des options d'un preset, consultez la documentation preset options.

`targets`

string | Array<string> | { [string]: string }, par défaut égale à l'option targets de niveau supérieur si aucune option liée à browserslist n'est spécifiée dans la doc de @babel/preset-env, sinon {}.

Pour l'utilisation, reportez-vous à la documentation de l'option targets.

`bugfixes`

boolean, par défaut false.

Ajoutée dans : v7.9.0

note

Cette option sera toujours activée et donc supprimée dans Babel 8.

Par défaut, @babel/preset-env (et les plugins Babel en général) regroupent les fonctionnalités de syntaxe ECMAScript en collections de petites fonctionnalités étroitement liées. Ces groupes peuvent être volumineux et inclure de nombreux cas particuliers, par exemple "function arguments" inclut les paramètres destructurés, par défaut et rest. À partir de ces regroupements, Babel active ou désactive chaque groupe en fonction des cibles de support navigateur que vous spécifiez dans l'option targets de @babel/preset-env.

Lorsque cette option est activée, @babel/preset-env tente de compiler la syntaxe défaillante vers la syntaxe moderne non défaillante la plus proche supportée par vos navigateurs cibles. Selon vos targets et la quantité de syntaxe moderne utilisée, cela peut réduire significativement la taille de l'application compilée. Cette option fusionne les fonctionnalités de @babel/preset-modules sans nécessiter un preset supplémentaire.

`spec`

boolean, valeur par défaut : false.

Active des transformations plus conformes aux spécifications, mais potentiellement plus lentes, pour tous les plugins de ce préréglage qui les prennent en charge.

attention

Cette option est dépréciée et sera supprimée dans Babel 8. Envisagez de migrer vers les assumptions globales disponibles depuis Babel 7.13. Voir "Migration depuis les modes "loose" et "spec" de @babel/preset-env" pour une configuration équivalente basée sur les hypothèses, prête à être copiée-collée comme point de départ.

`loose`

boolean, valeur par défaut : false.

Active les transformations en mode "laxiste" pour tous les plugins de ce préréglage qui les autorisent.

attention

`modules`

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false, valeur par défaut : "auto".

Active la transformation de la syntaxe des modules ES vers un autre type de module. Notez que cjs est un alias de commonjs.

Définir cette option sur false préservera les modules ES. À utiliser uniquement si vous prévoyez d'envoyer des modules ES natifs aux navigateurs. Si vous utilisez un bundler avec Babel, la valeur par défaut modules: "auto" est toujours préférable.

`modules: "auto"`

Par défaut, @babel/preset-env utilise les données du caller pour déterminer si les modules ES et les fonctionnalités associées (comme import()) doivent être transformés. Généralement, les données caller sont spécifiées dans les plugins de bundlers (ex: babel-loader, @rollup/plugin-babel). Il n'est donc pas recommandé de passer vous-même les données caller -- le caller passé pourrait écraser celui des plugins de bundlers, et à l'avenir vous pourriez obtenir des résultats sous-optimaux si les bundlers prennent en charge de nouvelles fonctionnalités de modules.

`debug`

boolean, valeur par défaut : false.

Affiche dans console.log les polyfills et plugins de transformation activés par preset-env, ainsi que (le cas échéant) les cibles spécifiques qui les nécessitent.

`include`

Array<string|RegExp>, valeur par défaut : [].

History

Version	Changes
`v7.4.0`	Support injecting `core-js@3` polyfills

Une liste de plugins à toujours inclure.

Les options valides incluent :

Plugins Babel - les noms complets et abrégés sont acceptés, par exemple ces formulations sont fonctionnellement équivalentes :
- @babel/plugin-transform-spread
- @babel/transform-spread
- babel-transform-spread
- transform-spread
Fonctions natives (pour core-js@3 et core-js@2), comme es.map, es.set ou es.object.assign.

Les noms de plugins peuvent être spécifiés intégralement, partiellement (ou via RegExp).

Formats acceptés :

Nom complet (string) : "es.math.sign"
Nom partiel (string) : "es.math.*" (inclut tous les plugins avec le préfixe es.math)
Objet RegExp : /^transform-.*$/ ou new RegExp("^transform-modules-.*")

Notez que le . ci-dessus correspond à tout caractère en RegExp, et non au caractère littéral '.'. De plus, .* est utilisé en RegExp pour correspondre à n'importe quelle séquence de caractères, contrairement au * dans un format glob.

Cette option est utile en cas de bug dans une implémentation native, ou si une combinaison de fonctionnalités (une non supportée + une supportée) ne fonctionne pas.

Par exemple, Node 4 supporte les classes natives mais pas l'opérateur spread. Si super est utilisé avec un argument spread, alors la transformation @babel/plugin-transform-classes doit être explicitement include, car il est impossible de transpiler un spread avec super autrement.

note

Les options include et exclude fonctionnent uniquement avec les plugins inclus dans ce preset. Ainsi, inclure @babel/plugin-proposal-do-expressions ou exclure @babel/plugin-proposal-function-bind générera des erreurs. Pour utiliser un plugin non inclus dans ce preset, ajoutez-le directement à vos "plugins".

`exclude`

Array<string|RegExp>, valeur par défaut : [].

Un tableau de plugins à toujours exclure/supprimer.

Les options possibles sont identiques à l'option include.

Cette option est utile pour exclure une transformation comme @babel/plugin-transform-regenerator, par exemple si vous utilisez un autre plugin comme fast-async au lieu de async-to-gen de Babel.

`useBuiltIns`

"usage" | "entry" | false, valeur par défaut : false.

Cette option configure la manière dont @babel/preset-env gère les polyfills.

Lorsque les options usage ou entry sont utilisées, @babel/preset-env ajoutera des références directes aux modules core-js sous forme d'imports bruts (ou requires). Cela signifie que core-js sera résolu relativement au fichier lui-même et doit être accessible.

Depuis que @babel/polyfill est déprécié en version 7.4.0, nous recommandons d'ajouter directement core-js et de définir la version via l'option corejs.

npm
Yarn
pnpm
Bun

npm install core-js@3 --save

# or

npm install core-js@2 --save

yarn add core-js@3

# or

yarn add core-js@2

pnpm add core-js@3

# or

pnpm add core-js@2

bun add core-js@3

# or

bun add core-js@2

`useBuiltIns: 'entry'`

History

Version	Changes
`v7.4.0`	It replaces `"core-js/stable"` and `"regenerator-runtime/runtime"` entry imports
`v7.0.0`	It replaces `"@babel/polyfill"` entry imports

astuce

N'utilisez import "core-js"; qu'une seule fois dans toute votre application.

Si vous utilisez @babel/polyfill, il inclut déjà core-js : l'importer deux fois générera une erreur.

Les imports multiples ou require de ces packages peuvent causer des collisions globales et d'autres problèmes difficiles à tracer. Nous recommandons de créer un fichier d'entrée unique contenant uniquement les instructions import.

Cette option active un nouveau plugin qui remplace les instructions import "core-js/stable"; et require("core-js"); par des imports individuels vers différents points d'entrée de core-js basés sur l'environnement.

Entrée

JavaScript
import "core-js";

Sortie (diffère selon l'environnement)

JavaScript
import "core-js/modules/es.string.pad-start";
import "core-js/modules/es.string.pad-end";

Importer "core-js" charge des polyfills pour toutes les fonctionnalités ECMAScript possibles : et si vous savez que vous n'en avez besoin que de certaines ? Avec core-js@3, @babel/preset-env peut optimiser chaque point d'entrée core-js et leurs combinaisons. Par exemple, vous pourriez vouloir uniquement polyfill les méthodes de tableau et les nouvelles propositions Math :

Entrée

JavaScript
import "core-js/es/array";
import "core-js/proposals/math-extensions";

Sortie (diffère selon l'environnement)

JavaScript
import "core-js/modules/es.array.unscopables.flat";
import "core-js/modules/es.array.unscopables.flat-map";
import "core-js/modules/esnext.math.clamp";
import "core-js/modules/esnext.math.deg-per-rad";
import "core-js/modules/esnext.math.degrees";
import "core-js/modules/esnext.math.fscale";
import "core-js/modules/esnext.math.rad-per-deg";
import "core-js/modules/esnext.math.radians";
import "core-js/modules/esnext.math.scale";

Vous pouvez consulter la documentation de core-js pour plus d'informations sur les différents points d'entrée.

note

Avec core-js@2 (explicitement via l'option corejs: "2" ou implicitement), @babel/preset-env transformera aussi les imports et require de @babel/polyfill. Ce comportement est déprécié car il est impossible d'utiliser @babel/polyfill avec différentes versions de core-js.

`useBuiltIns: 'usage'`

Ajoute des imports spécifiques pour les polyfills lorsqu'ils sont utilisés dans chaque fichier. Nous exploitons le fait qu'un bundler ne chargera qu'une seule fois le même polyfill.

Entrée

a.js
var a = new Promise();

b.js
var b = new Map();

Sortie (si l'environnement ne le supporte pas)

a.js
import "core-js/modules/es.promise";
var a = new Promise();

b.js
import "core-js/modules/es.map";
var b = new Map();

Sortie (si l'environnement le supporte)

a.js
var a = new Promise();

b.js
var b = new Map();

`useBuiltIns: false`

N'ajoute pas automatiquement de polyfills par fichier et ne transforme pas import "core-js" ou import "@babel/polyfill" en polyfills individuels.

`corejs`

Ajouté dans : v7.4.0

string ou { version: string, proposals: boolean }, valeur par défaut : "2.0". La chaîne version peut être n'importe quelle version supportée de core-js. Par exemple, "3.33" ou "2.0".

Cette option n'a d'effet que lorsqu'elle est utilisée avec useBuiltIns: usage ou useBuiltIns: entry, et garantit que @babel/preset-env injecte les polyfills supportés par votre version de core-js. Il est recommandé de spécifier la version mineure, sinon "3" sera interprété comme "3.0" et pourrait ne pas inclure les polyfills des dernières fonctionnalités.

Par défaut, seuls les polyfills pour les fonctionnalités stables d'ECMAScript sont injectés. Si vous souhaitez polyfill des propositions, vous avez trois options :

avec useBuiltIns: "entry", vous pouvez importer directement un polyfill de proposition : import "core-js/proposals/string-replace-all".
avec useBuiltIns: "usage", vous avez deux alternatives :
- définir l'option shippedProposals à true. Cela activera les polyfills et transformations pour les propositions déjà implémentées dans certains navigateurs.
- utiliser corejs: { version: "3.8", proposals: true }. Cela activera le polyfill de chaque proposition supportée par core-js@3.8.

`forceAllTransforms`

boolean, valeur par défaut : false.

Example

With Babel 7's JavaScript config file support, you can force all transforms to be run if env is set to production.

babel.config.js
module.exports = function(api) {
  return {
    presets: [
      [
        "@babel/preset-env",
        {
          targets: {
            chrome: 59,
            edge: 13,
            firefox: 50,
          },
          // for uglifyjs...
          forceAllTransforms: api.env("production"),
        },
      ],
    ],
  };
};

danger

targets.uglify est déprécié et sera supprimé dans la prochaine version majeure au profit de cette option.

Par défaut, ce préréglage exécute uniquement les transformations nécessaires pour les environnements ciblés. Activez cette option pour forcer l'exécution de toutes les transformations, utile si le résultat doit être traité par UglifyJS ou un environnement ne supportant que ES5.

astuce

Si vous utilisez un minifieur alternatif supportant la syntaxe ES6, nous recommandons Terser.

`configPath`

string, valeur par défaut : process.cwd()

Point de départ où la recherche de configuration browserslist commencera, en remontant jusqu'à la racine du système.

`ignoreBrowserslistConfig`

boolean, valeur par défaut : false

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.

`browserslistEnv`

Ajouté dans : v7.10.0 string, valeur par défaut : undefined

L'environnement Browserslist à utiliser.

`shippedProposals`

boolean, valeur par défaut : false

History

Version	Changes
`v7.14.0`	Include private field brand checks
`v7.12.0`	Include class static block and import assertions
`v7.10.0`	Include class properties and private methods
`v7.9.0`	Include numeric separator

Active le support des propositions intégrées/fonctionnalités déjà livrées dans les navigateurs. Si vos environnements cibles supportent nativement une proposition, son plugin de syntaxe correspondant est activé au lieu d'effectuer une transformation. Notez que cela n'active pas les mêmes transformations que @babel/preset-stage-3, car les propositions peuvent évoluer avant leur implémentation finale.

Actuellement supporté :

Fonctionnalités intégrées injectées avec useBuiltIns: "usage"

esnext.global-this (uniquement supporté par core-js@3)
esnext.string.match-all (uniquement supporté par core-js@3)

Fonctionnalités

Attributs d'import (parsing uniquement)

Fonctionnalités Matérialisées Ces fonctionnalités étaient contrôlées par le drapeau shippedProposals dans les anciennes versions de Babel. Elles sont désormais généralement disponibles.

Vous pouvez en savoir plus sur la configuration des options des préconfigurations ici

Mises en garde

Requêtes browserslist inefficaces

Bien que op_mini all soit une requête browserslist valide, preset-env l'ignore actuellement en raison d'un manque de données de support pour Opera Mini.

Installation​

Fonctionnement​

Intégration Browserslist​

Options​

targets​

bugfixes​

spec​

loose​

modules​

modules: "auto"​

debug​

include​

exclude​

useBuiltIns​

useBuiltIns: 'entry'​

useBuiltIns: 'usage'​

useBuiltIns: false​

corejs​

forceAllTransforms​

configPath​

ignoreBrowserslistConfig​

browserslistEnv​

shippedProposals​

Mises en garde​

Requêtes browserslist inefficaces​

Installation

Fonctionnement

Intégration Browserslist

Options

`targets`

`bugfixes`

`spec`

`loose`

`modules`

`modules: "auto"`

`debug`

`include`

`exclude`

`useBuiltIns`

`useBuiltIns: 'entry'`

`useBuiltIns: 'usage'`

`useBuiltIns: false`

`corejs`

`forceAllTransforms`

`configPath`

`ignoreBrowserslistConfig`

`browserslistEnv`

`shippedProposals`

Mises en garde

Requêtes browserslist inefficaces