@babel/preset-env

Traduzione Beta Non Ufficiale

Questa pagina è stata tradotta da PageTurner AI (beta). Non ufficialmente approvata dal progetto. Hai trovato un errore? Segnala problema →

@babel/preset-env è un preset intelligente che ti permette di utilizzare le ultime funzionalità JavaScript senza dover gestire manualmente quali trasformazioni di sintassi (e opzionalmente, polyfill per browser) sono necessarie per i tuoi ambienti target. Questo semplifica il tuo lavoro e riduce le dimensioni dei bundle JavaScript!

Installazione
Come funziona?
Integrazione con Browserslist
Opzioni

Installazione

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

Come funziona?

@babel/preset-env non sarebbe possibile senza numerosi fantastici progetti open-source come browserslist, compat-table e electron-to-chromium.

Utilizziamo queste fonti dati per mantenere mappature delle versioni dei nostri ambienti target supportati che hanno implementato una sintassi JavaScript o funzionalità browser, oltre a una mappatura di queste sintassi e funzionalità con i plugin di trasformazione Babel e i polyfill core-js.

nota

@babel/preset-env non includerà proposte di sintassi JavaScript inferiori allo Stage 3 perché in quella fase del processo TC39, non sarebbero comunque implementate da alcun browser. Queste dovrebbero essere incluse manualmente. L'opzione shippedProposals includerà proposte Stage 3 già implementate da alcuni browser.

@babel/preset-env prende gli ambienti target specificati, li confronta con le sue mappature per compilare una lista di plugin e la passa a Babel.

Integrazione con Browserslist

Per progetti basati su browser o Electron, consigliamo di usare un file .browserslistrc per specificare i target. Potresti già avere questo file di configurazione poiché è utilizzato da molti strumenti nell'ecosistema come autoprefixer, stylelint, eslint-plugin-compat e molti altri.

Per impostazione predefinita @babel/preset-env utilizzerà le fonti di configurazione browserslist a meno che non siano impostate le opzioni targets o ignoreBrowserslistConfig.

consiglio

Se fai affidamento sulla query predefinita di browserslist (esplicitamente o senza configurazione browserslist), consulta la sezione No targets per informazioni sul comportamento di preset-env.

Ad esempio, per includere solo i polyfill e le trasformazioni di codice necessari per browser con >0.25% di quota di mercato (escludendo browser senza aggiornamenti di sicurezza come IE 10 e BlackBerry):

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

.browserslistrc
> 0.25%
not dead

oppure

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

nota

Nota che dalla versione v7.4.5 la query browserslist viene risolta con mobileToDesktop: true. Ad esempio, per creare uno snapshot di una query esegui npx browserslist --mobile-to-desktop ">0.25%, not dead".

Opzioni

Per maggiori informazioni sull'impostazione delle opzioni per un preset, consulta la documentazione delle opzioni preset.

`targets`

string | Array<string> | { [string]: string }, predefinito all'opzione top-level targets se non è specificata alcuna opzione browserslist nella documentazione di @babel/preset-env, altrimenti {}.

Per l'utilizzo, consulta la documentazione dell'opzione targets.

`bugfixes`

boolean, predefinito a false.

Aggiunto in: v7.9.0

nota

Questa opzione sarà sempre abilitata e quindi rimossa in Babel 8.

Per impostazione predefinita, @babel/preset-env (e i plugin Babel in generale) raggruppano le funzionalità sintattiche ECMAScript in raccolte di funzionalità minori strettamente correlate. Questi gruppi possono essere ampi e includere molti casi limite, ad esempio "argomenti delle funzioni" include parametri destrutturati, predefiniti e rest. Da queste informazioni di raggruppamento, Babel abilita o disabilita ogni gruppo in base al target di supporto browser specificato nell'opzione targets di @babel/preset-env.

Quando questa opzione è abilitata, @babel/preset-env tenta di compilare la sintassi problematica nella sintassi moderna più vicina non problematica supportata dai tuoi browser target. A seconda dei tuoi targets e di quanto utilizzi la sintassi moderna, ciò può portare a una significativa riduzione delle dimensioni dell'applicazione compilata. Questa opzione incorpora le funzionalità di @babel/preset-modules senza dover utilizzare un altro preset.

`spec`

boolean, predefinito false.

Abilita trasformazioni più conformi alle specifiche, ma potenzialmente più lente, per tutti i plugin in questo preset che le supportano.

attenzione

Questa opzione è stata deprecata e verrà rimossa in Babel 8. Prendi in considerazione la migrazione al livello superiore assumptions disponibile da Babel 7.13. Vedi "Migrazione dalle modalità "loose" e "spec" di @babel/preset-env" per la configurazione equivalente basata su assunzioni, pronta per essere copiata e incollata come punto di partenza.

`loose`

boolean, predefinito false.

Abilita trasformazioni in "modalità loose" per tutti i plugin in questo preset che le consentono.

attenzione

`modules`

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false, predefinito "auto".

Abilita la trasformazione della sintassi dei moduli ES in un altro tipo di modulo. Nota che cjs è solo un alias per commonjs.

Impostare questo valore a false preserverà i moduli ES. Usalo solo se intendi distribuire moduli ES nativi ai browser. Se stai utilizzando un bundler con Babel, è sempre preferibile l'impostazione predefinita modules: "auto".

`modules: "auto"`

Per impostazione predefinita, @babel/preset-env utilizza i dati caller per determinare se i moduli ES e le relative funzionalità (ad es. import()) debbano essere trasformati. Generalmente i dati caller vengono specificati nei plugin dei bundler (es. babel-loader, @rollup/plugin-babel), pertanto non è consigliato passare manualmente i dati caller — il caller passato potrebbe sovrascrivere quello dei plugin dei bundler e in futuro potresti ottenere risultati subottimali se i bundler supporteranno nuove funzionalità dei moduli.

`debug`

boolean, predefinito false.

Scrive in console.log i polyfill e i plugin di trasformazione abilitati da preset-env e, se applicabile, quale dei tuoi target li richiedeva.

`include`

Array<string|RegExp>, predefinito [].

History

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

Un array di plugin da includere sempre.

Le opzioni valide includono:

Plugin Babel - sono supportati sia nomi completi che abbreviati, ad esempio i seguenti sono funzionalmente equivalenti:
- @babel/plugin-transform-spread
- @babel/transform-spread
- babel-transform-spread
- transform-spread
Built-in (sia per core-js@3 che core-js@2), come es.map, es.set o es.object.assign.

I nomi dei plugin possono essere specificati completamente o parzialmente (o usando RegExp).

Input accettabili:

Nome completo (string): "es.math.sign"
Nome parziale (string): "es.math.*" (risolve tutti i plugin con prefisso es.math)
Oggetto RegExp: /^transform-.*$/ o new RegExp("^transform-modules-.*")

Nota: il carattere . sopra rappresenta l'equivalente RegExp per corrispondere a qualsiasi carattere, non il carattere '.' letterale. Inoltre, per corrispondere a qualsiasi carattere in RegExp si usa .*, diversamente dal formato glob che usa *.

Questa opzione è utile se esiste un bug in un'implementazione nativa, o se una combinazione di funzionalità non supportata + una supportata non funziona.

Ad esempio, Node 4 supporta le classi native ma non lo spread. Se super viene utilizzato con un argomento spread, allora la trasformazione @babel/plugin-transform-classes deve essere includeta, poiché altrimenti non è possibile transpilare uno spread con super.

nota

Le opzioni include ed exclude funzionano solo con i plugin inclusi in questo preset; quindi, ad esempio, includere @babel/plugin-proposal-do-expressions o escludere @babel/plugin-proposal-function-bind genererà errori. Per utilizzare un plugin non incluso in questo preset, aggiungilo direttamente ai tuoi "plugins".

`exclude`

Array<string|RegExp>, predefinito [].

Un array di plugin da escludere/rimuovere sempre.

Le opzioni possibili sono le stesse dell'opzione include.

Questa opzione è utile per escludere una trasformazione come @babel/plugin-transform-regenerator, ad esempio se si utilizza un altro plugin come fast-async al posto di async-to-gen di Babel.

`useBuiltIns`

"usage" | "entry" | false, predefinito false.

Questa opzione configura come @babel/preset-env gestisce i polyfill.

Quando si utilizzano le opzioni usage o entry, @babel/preset-env aggiungerà riferimenti diretti ai moduli core-js come importazioni dirette (o require). Ciò significa che core-js verrà risolto relativamente al file stesso e deve essere accessibile.

Poiché @babel/polyfill è stato deprecato nella versione 7.4.0, consigliamo di aggiungere direttamente core-js e impostare la versione tramite l'opzione 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

consiglio

Utilizza import "core-js"; solo una volta nell'intera applicazione.

Se stai usando @babel/polyfill, include già core-js: importarlo due volte genererà un errore.

Importazioni multiple o require di questi pacchetti potrebbero causare collisioni globali e altri problemi difficili da tracciare. Consigliamo di creare un unico file di ingresso che contenga solo le istruzioni import.

Questa opzione abilita un nuovo plugin che sostituisce le istruzioni import "core-js/stable"; e require("core-js"); con importazioni individuali verso diversi entry point di core-js basati sull'ambiente.

JavaScript
import "core-js";

Out (dipende dall'ambiente)

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

Importare "core-js" carica polyfill per ogni possibile funzionalità ECMAScript: e se sapessi di averne bisogno solo di alcune? Usando core-js@3, @babel/preset-env può ottimizzare ogni singolo entry point di core-js e le loro combinazioni. Ad esempio, potresti voler polyfillare solo i metodi degli array e le nuove proposte per Math:

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

Out (dipende dall'ambiente)

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";

Puoi consultare la documentazione di core-js per maggiori informazioni sui diversi entry point.

nota

Quando si usa core-js@2 (esplicitamente con l'opzione corejs: "2" o implicitamente), @babel/preset-env trasformerà anche import e require di @babel/polyfill. Questo comportamento è deprecato perché non è possibile usare @babel/polyfill con diverse versioni di core-js.

`useBuiltIns: 'usage'`

Aggiunge import specifici per i polyfill quando vengono utilizzati in ogni file. Sfruttiamo il fatto che un bundler caricherà lo stesso polyfill una sola volta.

a.js
var a = new Promise();

b.js
var b = new Map();

Out (se l'ambiente non lo supporta)

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

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

Out (se l'ambiente lo supporta)

a.js
var a = new Promise();

b.js
var b = new Map();

`useBuiltIns: false`

Non aggiunge automaticamente polyfill per file e non trasforma import "core-js" o import "@babel/polyfill" in polyfill individuali.

`corejs`

Aggiunto in: v7.4.0

string o { version: string, proposals: boolean }, predefinito "2.0". La stringa version può essere qualsiasi versione supportata di core-js. Ad esempio, "3.33" o "2.0".

Questa opzione ha effetto solo quando utilizzata insieme a useBuiltIns: usage o useBuiltIns: entry, e garantisce che @babel/preset-env inietti i polyfill supportati dalla tua versione di core-js. Si raccomanda di specificare la versione minore, altrimenti "3" verrà interpretato come "3.0" che potrebbe non includere polyfill per le funzionalità più recenti.

Per impostazione predefinita, vengono iniettati solo polyfill per funzionalità ECMAScript stabili. Se desideri utilizzare polyfill per le proposte, hai tre opzioni:

utilizzando useBuiltIns: "entry", puoi importare direttamente un polyfill per proposta: import "core-js/proposals/string-replace-all".
utilizzando useBuiltIns: "usage" hai due alternative:
- imposta l'opzione shippedProposals a true. Ciò abiliterà polyfill e trasformazioni per proposte già implementate nei browser da tempo.
- usa corejs: { version: "3.8", proposals: true }. Ciò abiliterà il polyfilling di ogni proposta supportata da core-js@3.8.

`forceAllTransforms`

boolean, predefinito 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"),
        },
      ],
    ],
  };
};

pericolo

targets.uglify è deprecato e verrà rimosso nella prossima major a favore di questa opzione.

Per impostazione predefinita, questo preset esegue solo le trasformazioni necessarie per gli ambienti target. Abilita questa opzione per forzare l'esecuzione di tutte le trasformazioni, utile quando l'output verrà processato da UglifyJS o in ambienti che supportano solo ES5.

consiglio

Se necessiti di un minifier alternativo che supporti la sintassi ES6, raccomandiamo Terser.

`configPath`

string, predefinito process.cwd()

Punto di partenza per la ricerca della configurazione browserslist, che risalirà fino alla root del sistema finché non viene trovata.

`ignoreBrowserslistConfig`

boolean, predefinito false

Attiva/disattiva l'utilizzo delle fonti di configurazione browserslist, che include la ricerca di file browserslist o il riferimento alla chiave browserslist in package.json. Utile per progetti che utilizzano una configurazione browserslist per file non compilati con Babel.

`browserslistEnv`

Aggiunto in: v7.10.0 string, predefinito undefined

L'ambiente Browserslist da utilizzare.

`shippedProposals`

boolean, predefinito 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

Abilita il supporto per proposte integrate/funzionalità già implementate nei browser. Se gli ambienti target supportano nativamente una proposta, viene abilitato il corrispondente plugin sintattico anziché applicare trasformazioni. Nota che ciò non abilita le stesse trasformazioni di @babel/preset-stage-3, poiché le proposte possono evolvere prima di essere implementate nei browser.

Attualmente sono supportati:

Builtins iniettati con useBuiltIns: "usage"

esnext.global-this (supportato solo da core-js@3)
esnext.string.match-all (supportato solo da core-js@3)

Funzionalità

Import attributes (solo parsing)

Funzionalità Implementate Queste funzionalità erano disponibili dietro il flag shippedProposals nelle vecchie versioni di Babel. Ora sono generalmente disponibili.

Ulteriori informazioni sulla configurazione delle opzioni dei preset sono disponibili qui

Avvertenze

Query browserslist inefficaci

Nonostante op_mini all sia una query browserslist valida, preset-env attualmente la ignora a causa della mancanza di dati di supporto per Opera Mini.

Installazione​

Come funziona?​

Integrazione con Browserslist​

Opzioni​

targets​

bugfixes​

spec​

loose​

modules​

modules: "auto"​

debug​

include​

exclude​

useBuiltIns​

useBuiltIns: 'entry'​

useBuiltIns: 'usage'​

useBuiltIns: false​

corejs​

forceAllTransforms​

configPath​

ignoreBrowserslistConfig​

browserslistEnv​

shippedProposals​

Avvertenze​

Query browserslist inefficaci​

Installazione

Come funziona?

Integrazione con Browserslist

Opzioni

`targets`

`bugfixes`

`spec`

`loose`

`modules`

`modules: "auto"`

`debug`

`include`

`exclude`

`useBuiltIns`

`useBuiltIns: 'entry'`

`useBuiltIns: 'usage'`

`useBuiltIns: false`

`corejs`

`forceAllTransforms`

`configPath`

`ignoreBrowserslistConfig`

`browserslistEnv`

`shippedProposals`

Avvertenze

Query browserslist inefficaci