@babel/preset-env

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

@babel/preset-env es un preset inteligente que te permite usar JavaScript moderno sin necesidad de gestionar manualmente qué transformaciones de sintaxis (y opcionalmente, polyfills para navegadores) requiere tu entorno objetivo. ¡Esto simplifica tu trabajo y reduce el tamaño de los bundles JavaScript!

Instalación
¿Cómo funciona?
Integración con Browserslist
Opciones

Instalación

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

¿Cómo funciona?

@babel/preset-env no sería posible sin varios proyectos open-source extraordinarios como browserslist, compat-table y electron-to-chromium.

Utilizamos estas fuentes de datos para mantener mapeos de versiones donde entornos objetivo compatibles obtuvieron soporte para características de JavaScript o navegadores, así como mapeos de esas sintaxis y características hacia plugins de transformación de Babel y polyfills de core-js.

nota

@babel/preset-env no incluirá propuestas de sintaxis JavaScript inferiores al Stage 3 porque en esa fase del proceso TC39, ningún navegador las implementaría de todos modos. Estas deben incluirse manualmente. La opción shippedProposals incluirá propuestas en Stage 3 que algunos navegadores ya implementaron.

@babel/preset-env toma los entornos objetivo especificados, los contrasta con sus mapeos, compila una lista de plugins y la pasa a Babel.

Integración con Browserslist

Para proyectos basados en navegadores o Electron, recomendamos usar un archivo .browserslistrc para definir objetivos. Es posible que ya tengas este archivo ya que lo usan muchas herramientas del ecosistema como autoprefixer, stylelint, eslint-plugin-compat y otras.

Por defecto @babel/preset-env usará fuentes de configuración browserslist a menos que se configuren las opciones targets o ignoreBrowserslistConfig.

consejo

Si dependes de la consulta predeterminada de browserslist (explícitamente o al no tener configuración), revisa la sección Sin objetivos para conocer el comportamiento de preset-env.

Por ejemplo, para incluir solo polyfills y transformaciones necesarias para usuarios cuyos navegadores tengan >0.25% de cuota de mercado (ignorando navegadores sin actualizaciones de seguridad como IE 10 y 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" }

nota

Ten en cuenta que desde v7.4.5 las consultas browserslist se resuelven con mobileToDesktop: true. Ejemplo: para crear un snapshot de una consulta ejecuta npx browserslist --mobile-to-desktop ">0.25%, not dead".

Opciones

Para más información sobre configuración de opciones de presets, consulta la documentación de opciones de preset.

`targets`

string | Array<string> | { [string]: string }, por defecto toma la opción targets de nivel superior si no se especifica opción relacionada con browserslist en la documentación de @babel/preset-env, de lo contrario {}.

Para uso, consulta la documentación de la opción targets.

`bugfixes`

boolean, por defecto false.

Añadido en: v7.9.0

nota

Esta opción estará siempre habilitada y por lo tanto será eliminada en Babel 8.

Por defecto, @babel/preset-env (y los plugins de Babel en general) agrupaban características de sintaxis ECMAScript en colecciones de características pequeñas estrechamente relacionadas. Estos grupos pueden ser grandes e incluir muchos casos extremos, por ejemplo "argumentos de función" incluye parámetros desestructurados, por defecto y rest. A partir de esta información de agrupamiento, Babel habilita o deshabilita cada grupo según el soporte del navegador objetivo que especifiques en la opción targets de @babel/preset-env.

Cuando esta opción está habilitada, @babel/preset-env intenta compilar la sintaxis rota a la sintaxis moderna más cercana que no esté rota soportada por tus navegadores objetivo. Dependiendo de tus targets y de cuánta sintaxis moderna uses, esto puede llevar a una reducción significativa de tamaño en la aplicación compilada. Esta opción combina las características de @babel/preset-modules sin necesidad de usar otro preset.

`spec`

boolean, valor predeterminado: false.

Habilita transformaciones más compatibles con las especificaciones, pero potencialmente más lentas, para cualquier plugin en este preset que las admita.

precaución

Esta opción ha quedado obsoleta y será eliminada en Babel 8. Considera migrar al nivel superior de assumptions disponible desde Babel 7.13. Consulta "Migrando desde los modos "loose" y "spec" de @babel/preset-env" para la configuración equivalente basada en suposiciones, lista para copiar y pegar como punto de partida.

`loose`

boolean, valor predeterminado: false.

Habilita transformaciones "loose" para cualquier plugin en este preset que lo permita.

precaución

`modules`

"amd" | "umd" | "systemjs" | "commonjs" | "cjs" | "auto" | false, valor predeterminado: "auto".

Habilita la transformación de sintaxis de módulos ES a otro tipo de módulo. Ten en cuenta que cjs es solo un alias de commonjs.

Establecer esto en false preservará los módulos ES. Úsalo solo si planeas enviar módulos ES nativos a navegadores. Si usas un bundler con Babel, el valor predeterminado modules: "auto" siempre es preferible.

`modules: "auto"`

Por defecto, @babel/preset-env utiliza datos del caller para determinar si los módulos ES y características de módulos (ej. import()) deben transformarse. Generalmente los datos de caller se especifican en plugins de empaquetadores (ej. babel-loader, @rollup/plugin-babel), por lo que no se recomienda pasar datos de caller manualmente. El caller que pases podría sobrescribir el de los plugins de empaquetadores y, en el futuro, podrías obtener resultados subóptimos si los empaquetadores implementan nuevas características de módulos.

`debug`

boolean, valor predeterminado: false.

Envía a console.log los polyfills y plugins de transformación habilitados por preset-env, indicando además (cuando aplique) qué objetivo específico los requería.

`include`

Array<string|RegExp>, valor predeterminado: [].

History

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

Un array de plugins que siempre se incluirán.

Las opciones válidas incluyen:

Plugins de Babel: se admiten nombres completos y abreviados. Ejemplos funcionalmente equivalentes:
- @babel/plugin-transform-spread
- @babel/transform-spread
- babel-transform-spread
- transform-spread
Built-ins (para core-js@3 y core-js@2), como es.map, es.set o es.object.assign.

Los nombres de plugins pueden especificarse completamente, parcialmente o mediante RegExp.

Formatos aceptados:

Nombre completo (string): "es.math.sign"
Nombre parcial (string): "es.math.*" (incluye todos los plugins con prefijo es.math)
Objeto RegExp: /^transform-.*$/ o new RegExp("^transform-modules-.*")

Nota: El . en RegExp coincide con cualquier carácter, no con el punto literal '.'. Además, para coincidir con cualquier secuencia se usa .* en RegExp (no * como en formato glob).

Esta opción es útil cuando existen errores en implementaciones nativas o cuando la combinación de características soportadas/no soportadas falla.

Ejemplo: Node 4 soporta clases nativas pero no el operador spread. Si se usa super con un argumento spread, entonces la transformación @babel/plugin-transform-classes debe ser includeda, ya que es imposible transpilar un spread con super de otro modo.

nota

Las opciones include/exclude solo funcionan con plugins incluidos en este preset. Incluir @babel/plugin-proposal-do-expressions o excluir @babel/plugin-proposal-function-bind producirá errores. Para plugins externos, añádelos directamente en "plugins".

`exclude`

Array<string|RegExp>, valor predeterminado: [].

Un arreglo de plugins que siempre se excluirán/eliminarán.

Las opciones posibles son las mismas que la opción include.

Esta opción es útil para excluir una transformación como @babel/plugin-transform-regenerator, por ejemplo si estás usando otro plugin como fast-async en lugar de async-to-gen de Babel.

`useBuiltIns`

"usage" | "entry" | false, valor predeterminado: false.

Esta opción configura cómo @babel/preset-env maneja los polyfills.

Cuando se usan las opciones usage o entry, @babel/preset-env agregará referencias directas a módulos de core-js como imports simples (o requires). Esto significa que core-js se resolverá relativamente al archivo mismo y debe ser accesible.

Dado que @babel/polyfill fue desaprobado en la versión 7.4.0, recomendamos agregar core-js directamente y configurar la versión mediante la opción 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

consejo

Usa import "core-js"; solo una vez en toda tu aplicación.

Si estás usando @babel/polyfill, ya incluye core-js: importarlo dos veces lanzará un error.

Múltiples imports o requires de estos paquetes pueden causar colisiones globales y otros problemas difíciles de rastrear. Recomendamos crear un único archivo de entrada que solo contenga las sentencias import.

Esta opción habilita un nuevo plugin que reemplaza las sentencias import "core-js/stable"; y require("core-js"); con imports individuales a diferentes puntos de entrada de core-js basados en el entorno.

Entrada

JavaScript
import "core-js";

Salida (diferente según el entorno)

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

Importar "core-js" carga polyfills para todas las características posibles de ECMAScript: ¿qué pasa si sabes que solo necesitas algunas de ellas? Al usar core-js@3, @babel/preset-env puede optimizar cada punto de entrada de core-js y sus combinaciones. Por ejemplo, podrías querer aplicar polyfill solo a métodos de arrays y nuevas propuestas de Math:

Entrada

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

Salida (diferente según el entorno)

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

Puedes leer la documentación de core-js para obtener más información sobre los diferentes puntos de entrada.

nota

Al usar core-js@2 (ya sea explícitamente con la opción corejs: "2" o implícitamente), @babel/preset-env también transformará los imports y requires de @babel/polyfill. Este comportamiento está obsoleto porque no es posible usar @babel/polyfill con diferentes versiones de core-js.

`useBuiltIns: 'usage'`

Agrega imports específicos para polyfills cuando se usan en cada archivo. Aprovechamos que un bundler cargará el mismo polyfill solo una vez.

Entrada

a.js
var a = new Promise();

b.js
var b = new Map();

Salida (si el entorno no lo soporta)

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

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

Salida (si el entorno lo soporta)

a.js
var a = new Promise();

b.js
var b = new Map();

`useBuiltIns: false`

No agregar polyfills automáticamente por archivo, ni transformar import "core-js" o import "@babel/polyfill" en polyfills individuales.

`corejs`

Añadido en: v7.4.0

string o { version: string, proposals: boolean }, valor predeterminado: "2.0". El string version puede ser cualquier versión compatible de core-js. Por ejemplo, "3.33" o "2.0".

Esta opción solo tiene efecto cuando se usa junto con useBuiltIns: usage o useBuiltIns: entry, y garantiza que @babel/preset-env inyecte los polyfills compatibles con tu versión de core-js. Se recomienda especificar la versión menor; de lo contrario, "3" se interpretará como "3.0", que puede no incluir polyfills para las últimas características.

Por defecto, solo se inyectan polyfills para características estables de ECMAScript. Si deseas polyfills para propuestas, tienes tres opciones:

Al usar useBuiltIns: "entry", puedes importar directamente un polyfill de propuesta: import "core-js/proposals/string-replace-all".
Al usar useBuiltIns: "usage" tienes dos alternativas:
- Establecer la opción shippedProposals en true. Esto habilitará polyfills y transformaciones para propuestas ya implementadas en navegadores.
- Usar corejs: { version: "3.8", proposals: true }. Esto habilitará el polyfill para todas las propuestas compatibles con core-js@3.8.

`forceAllTransforms`

boolean, valor predeterminado: 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"),
        },
      ],
    ],
  };
};

peligro

targets.uglify está obsoleto y será eliminado en la próxima versión mayor en favor de esta opción.

Por defecto, este preset ejecuta solo las transformaciones necesarias para los entornos objetivo. Habilita esta opción para forzar la ejecución de todas las transformaciones, útil cuando la salida será procesada por UglifyJS o un entorno que solo soporta ES5.

consejo

Si necesitas un minificador alternativo que sí soporte sintaxis ES6, recomendamos Terser.

`configPath`

string, valor predeterminado: process.cwd()

Punto inicial donde comenzará la búsqueda de configuración de browserslist, ascendiendo hasta la raíz del sistema hasta encontrarlo.

`ignoreBrowserslistConfig`

boolean, valor predeterminado: false

Activa/desactiva el uso de fuentes de configuración browserslist, lo que incluye buscar archivos browserslist o referenciar la clave browserslist en package.json. Útil para proyectos que usan configuración browserslist para archivos que no serán compilados con Babel.

`browserslistEnv`

Añadido en: v7.10.0 string, valor predeterminado: undefined

El entorno Browserslist a utilizar.

`shippedProposals`

boolean, valor predeterminado: 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

Habilita soporte para propuestas de características ya implementadas en navegadores. Si tus entornos objetivo tienen soporte nativo para una propuesta, se habilita su plugin de sintaxis en lugar de transformaciones. Nota: esto no habilita las mismas transformaciones que @babel/preset-stage-3, ya que las propuestas pueden cambiar antes de implementarse en navegadores.

Actualmente se soportan:

Builtins inyectados con useBuiltIns: "usage"

esnext.global-this (solo compatible con core-js@3)
esnext.string.match-all (solo compatible con core-js@3)

Características

Atributos de importación (solo parsing)

Características Materializadas Estas características estaban detrás de la bandera shippedProposals en versiones anteriores de Babel. Ahora están disponibles de forma general.

Puedes leer más sobre cómo configurar opciones de presets aquí

Advertencias

Consultas browserslist inefectivas

Aunque op_mini all es una consulta browserslist válida, preset-env actualmente la ignora debido a la falta de datos de soporte para Opera Mini.

Instalación​

¿Cómo funciona?​

Integración con Browserslist​

Opciones​

targets​

bugfixes​

spec​

loose​

modules​

modules: "auto"​

debug​

include​

exclude​

useBuiltIns​

useBuiltIns: 'entry'​

useBuiltIns: 'usage'​

useBuiltIns: false​

corejs​

forceAllTransforms​

configPath​

ignoreBrowserslistConfig​

browserslistEnv​

shippedProposals​

Advertencias​

Consultas browserslist inefectivas​

Instalación

¿Cómo funciona?

Integración con Browserslist

Opciones

`targets`

`bugfixes`

`spec`

`loose`

`modules`

`modules: "auto"`

`debug`

`include`

`exclude`

`useBuiltIns`

`useBuiltIns: 'entry'`

`useBuiltIns: 'usage'`

`useBuiltIns: false`

`corejs`

`forceAllTransforms`

`configPath`

`ignoreBrowserslistConfig`

`browserslistEnv`

`shippedProposals`

Advertencias

Consultas browserslist inefectivas