Saltar al contenido principal

Opciones

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 →

Las opciones pueden pasarse a Babel de varias formas. Cuando se pasan directamente a Babel, basta con pasar el objeto de opciones. Cuando se usa Babel a través de un wrapper, también puede ser necesario, o al menos más útil, pasar las opciones mediante archivos de configuración.

Si pasas opciones mediante @babel/cli, deberás usar kebab-case en los nombres. Ej:

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

Opciones principales​

Estas opciones solo están permitidas como parte de las opciones programáticas de Babel, por lo que están principalmente destinadas a herramientas que envuelven Babel o personas que invocan babel.transform directamente. Los usuarios de las integraciones de Babel, como babel-loader o @babel/register, probablemente no las utilicen.

cwd​

Tipo: string
Predeterminado: process.cwd()

El directorio de trabajo al que se resolverán todas las rutas en las opciones programáticas.

caller​

Tipo: Un objeto con la estructura

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

Las utilidades pueden pasar un objeto caller para identificarse ante Babel y pasar banderas relacionadas con capacidades para su uso en configuraciones, presets y plugins. Por ejemplo

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

permitiría que plugins y presets decidan que, dado que los módulos ES son compatibles, omitirán la compilación de módulos ES a módulos CommonJS.

filename​

Tipo: string

El nombre de archivo asociado al código que se está compilando, si existe. El nombre de archivo es opcional, pero no toda la funcionalidad de Babel está disponible cuando el nombre de archivo es desconocido, porque un subconjunto de opciones depende del nombre de archivo para su funcionamiento.

Los tres casos principales que los usuarios podrían encontrar son:

  • El nombre de archivo se expone a los plugins. Algunos plugins pueden requerir su presencia.

  • Opciones como "test", "exclude" e "ignore" requieren el nombre de archivo para coincidencias de cadena/expresión regular.

  • Los archivos .babelrc.json o .babelrc se cargan relativos al archivo que se está compilando. Si se omite esta opción, Babel se comportará como si se hubiera establecido babelrc: false.

filenameRelative​

Tipo: string
Predeterminado: path.relative(opts.cwd, opts.filename) (si se pasó "filename")

Se utiliza como valor predeterminado para la opción sourceFileName de Babel y como parte de la generación de nombres de archivo para las transformaciones de módulos AMD/UMD/SystemJS.

code​

Tipo: boolean
Predeterminado: true

El valor de retorno predeterminado de Babel incluye propiedades code y map con el código generado resultante. En contextos donde se realizan múltiples llamadas a Babel, puede ser útil desactivar la generación de código y en su lugar usar ast: true para obtener el AST directamente, evitando así trabajo innecesario.

ast​

Tipo: boolean
Predeterminado: false

El comportamiento predeterminado de Babel es generar una cadena de texto y un sourcemap, pero en algunos contextos puede ser útil obtener el propio AST. El caso de uso principal sería una cadena de múltiples pasos de transformación, como por ejemplo:

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,
});

Nota: Esta opción no está activada por defecto porque la mayoría de usuarios no la necesitará y porque eventualmente queremos añadir una capa de caché a Babel. Almacenar la estructura AST requeriría significativamente más espacio.

cloneInputAst​

Tipo: boolean
Predeterminado: true
Añadido en v7.11.0

Por defecto, babel.transformFromAst clonará el AST de entrada para evitar mutaciones. Especificar cloneInputAst: false puede mejorar el rendimiento del análisis si el AST de entrada no se usa en otro lugar.

Opciones de carga de configuración​

La carga de configuración puede volverse compleja ya que los entornos pueden tener varios tipos de archivos de configuración, y esos archivos pueden contener diversos objetos de configuración anidados que se aplican según necesidades específicas.

root​

Tipo: string
Predeterminado: opts.cwd
Ubicación: Solo permitido en opciones programáticas de Babel

La ruta inicial que será procesada según "rootMode" para determinar la carpeta raíz conceptual del proyecto actual de Babel. Se usa principalmente en dos casos:

rootMode​

Tipo: "root" | "upward" | "upward-optional"
Predeterminado: "root"
Ubicación: Solo permitido en opciones programáticas de Babel
Añadido en: v7.1.0

Esta opción, combinada con el valor "root", define cómo Babel selecciona su raíz de proyecto. Los diferentes modos determinan distintas formas en que Babel puede procesar el valor "root" para obtener la raíz final del proyecto.

Nota: babel.config.json es compatible desde Babel 7.8.0. En versiones anteriores de Babel 7, solo se admite babel.config.js.

"root" es el modo predeterminado porque evita el riesgo de que Babel cargue accidentalmente un babel.config.json completamente fuera de la carpeta del proyecto actual. Si usas "upward-optional", ten en cuenta que recorrerá la estructura de directorios hasta la raíz del sistema de archivos, y siempre es posible que alguien tenga un babel.config.json olvidado en su directorio personal, lo que podría causar errores inesperados en tus compilaciones.

Los usuarios con estructuras de proyecto monorepo que ejecutan builds/pruebas por paquete probablemente querrán usar "upward", ya que los monorepos suelen tener un babel.config.json en la raíz del proyecto. Ejecutar Babel en un subdirectorio de monorepo sin "upward" hará que Babel omita cargar cualquier archivo babel.config.json en la raíz del proyecto, lo que puede provocar errores inesperados y fallos de compilación.

envName​

Tipo: string
Valor por defecto: process.env.BABEL_ENV || process.env.NODE_ENV || "development"
Ubicación: Solo permitido en las opciones programáticas de Babel

El entorno activo actual utilizado durante la carga de configuración. Este valor se usa como clave al resolver configuraciones "env", y también está disponible dentro de funciones de configuración, plugins y presets mediante la función api.env().

configFile​

Tipo: string | boolean
Valor por defecto: path.resolve(opts.root, "babel.config.json"), si existe, false en caso contrario
Ubicación: Solo permitido en las opciones programáticas de Babel

Busca por defecto un archivo babel.config.json predeterminado, pero puede recibir la ruta de cualquier archivo de configuración JS o JSON5.

NOTA: Esta opción no afecta la carga de archivos .babelrc.json, por lo que aunque pueda ser tentador hacer configFile: "./foo/.babelrc.json", no es recomendable. Si el .babelrc.json dado se carga mediante la lógica estándar relativa al archivo, terminarás cargando el mismo archivo de configuración dos veces, fusionándolo consigo mismo. Si estás enlazando un archivo de configuración específico, se recomienda usar un esquema de nombres independiente del término "babelrc".

babelrc​

Tipo: boolean
Valor por defecto: true siempre que se haya especificado la opción filename
Ubicación: Permitido en las opciones programáticas de Babel o dentro del "configFile" cargado. Una opción programática anulará una del archivo de configuración.

true habilitará la búsqueda de archivos de configuración y el archivo heredado .babelignore relativos al "filename" proporcionado a Babel.

Un valor babelrc pasado en las opciones programáticas anulará cualquier valor establecido dentro de un archivo de configuración.

Nota: Los archivos .babelrc.json solo se cargan si el "filename" actual está dentro de un paquete que coincide con uno de los paquetes "babelrcRoots".

babelrcRoots​

Tipo: boolean | MatchPattern | Array<MatchPattern>
Valor por defecto: opts.root
Ubicación: Permitido en las opciones programáticas de Babel o dentro del configFile cargado. Una opción programática anulará una del archivo de configuración.

Por defecto, Babel solo buscará archivos .babelrc.json dentro del paquete "root" porque, de lo contrario, Babel no puede saber si un .babelrc.json dado debe cargarse o si sus "plugins" y "presets" están instalados, ya que el archivo que se está compilando podría estar dentro de node_modules o haber sido enlazado simbólicamente al proyecto.

Esta opción permite a los usuarios proporcionar una lista de otros paquetes que deben considerarse paquetes "raíz" al evaluar si se deben cargar archivos .babelrc.json.

Por ejemplo, una configuración de monorepo que desee permitir que paquetes individuales tengan sus propias configuraciones podría hacer:

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

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

Opciones de plugins y presets​

plugins​

Tipo: Array<PluginEntry | Plugin> (PluginEntry)
Valor por defecto: []

Un array de plugins para activar al procesar este archivo. Para más información sobre cómo interactúan las entradas individuales, especialmente cuando se usan en múltiples configuraciones anidadas de "env" y "overrides", consulta fusión.

Nota: La opción también permite instancias de Plugin de Babel, pero no se recomienda usarlas directamente. Si necesitas crear una representación persistente de un plugin o preset, debes usar babel.createConfigItem().

presets​

Tipo: Array<PresetEntry> (PresetEntry)
Valor por defecto: []

Un array de presets para activar al procesar este archivo. Para más información sobre cómo interactúan las entradas individuales, especialmente cuando se usan en múltiples configuraciones anidadas de "env" y "overrides", consulta fusión.

Nota: El formato de los presets es idéntico al de los plugins, excepto porque la normalización de nombres espera "preset-" en lugar de "plugin-", y los presets no pueden ser instancias de Plugin.

passPerPreset​

Tipo: boolean
Valor por defecto: false
Estado: Obsoleto

Indica a Babel que ejecute cada preset en el array presets como un pase independiente. Esta opción suele generar confusión sobre el orden exacto de los plugins, pero puede ser útil si necesitas ejecutar un conjunto de operaciones como pases de compilación independientes.

Nota: Esta opción podría eliminarse en futuras versiones de Babel a medida que añadamos mejor soporte para definir el orden entre plugins.

Destinos de salida​

targets​

Tipo: string | Array<string> | { [string]: string }
Valor por defecto: {}
Ubicación: Permitido en opciones programáticas de Babel o en archivos de configuración
Añadido en: v7.13.0

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

Describe los entornos que quieres soportar/destinar en tu proyecto.

Puede ser una consulta compatible con browserslist (con advertencias):

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

O un objeto con las versiones mínimas de entorno a soportar:

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

Entornos soportados: android, chrome, deno, edge, electron, firefox, ie, ios, node, opera, rhino, safari, samsung.

Si no se especifica una versión menor, Babel la interpretará como MAJOR.0. Por ejemplo, "node": 12 se considerará como Node.js 12.0.

Sin destinos​

Cuando no se especifican objetivos: Babel asumirá que apuntas a los navegadores más antiguos posibles. Por ejemplo, @babel/preset-env transformará todo el código ES2015-ES2020 para que sea compatible con ES5.

consejo

Recomendamos configurar targets para reducir el tamaño del código generado.

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

Por este motivo, el comportamiento de Babel difiere de browserslist: no utiliza la consulta defaults cuando no se encuentran objetivos en tu configuración de Babel ni en browserslist. Si deseas usar la consulta defaults, debes pasarla explícitamente como objetivo:

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

Reconocemos que esto no es ideal y lo revisaremos en Babel v8.

targets.esmodules​

Tipo: boolean | "intersect"

History
VersionChanges
v7.13.0Support "intersect"

Puedes apuntar a navegadores compatibles con módulos ES. Cuando esmodules es "intersect", intersectará con los objetivos browsers y los de browserslist. Puedes usar este enfoque con <script type="module"></script> para servir scripts más pequeños condicionalmente (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"
  }
}

Cuando esmodules es true, sobrescribirá los objetivos browsers o los de browserslist.

consejo

Si usas defaults de browserslist como objetivo, o planeas dar soporte a navegadores principales lanzados desde 2019, puedes eliminar esmodules porque estos navegadores ya soportan módulos ES.

targets.node​

Tipo: string | "current" | true.

Para compilar contra la versión actual de Node, especifica "node": true o "node": "current", equivalente a "node": process.versions.node.

Alternativamente, especifica la versión de Node mediante una consulta browserslist:

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

En este caso, browserslist lo resolverá a la versión más reciente en la librería node-releases. Como Node.js puede añadir funciones en versiones menores, un programa generado para Node.js 12.22 podría fallar en Node.js 12.0. Recomendamos especificar siempre una versión menor en consultas Node con browserslist:

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

targets.safari​

Tipo: string | "tp".

Para compilar contra la versión de Technology Preview de Safari, especifica "safari": "tp".

targets.browsers​

Tipo: string | Array<string>.

Consulta para seleccionar navegadores (ej: últimas 2 versiones, >5%, safari tp) usando browserslist.

Nota: Los resultados de los navegadores son sobrescritos por elementos explícitos en targets.

targets.deno​

Tipo: string.

La versión mínima soportada es la 1.0.

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

browserslistConfigFile​

Tipo: boolean
Valor por defecto: true
Ubicación: Permitido en opciones programáticas de Babel o en archivos de configuración
Añadido en: v7.13.0

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.

Si se especifica un string, debe representar la ruta de un archivo de configuración browserslist. Las rutas relativas se resuelven respecto al archivo de configuración que especifica esta opción, o respecto a cwd cuando se pasa como parte de opciones programáticas.

browserslistEnv​

Tipo: string
Valor por defecto: undefined
Ubicación: Permitido en opciones programáticas de Babel o en archivos de configuración
Añadido en: v7.13.0

El entorno Browserslist a utilizar.

Opciones de Combinación de Configuración​

extends​

Tipo: string
Ubicación: No permitido dentro de presets

Las configuraciones pueden "extender" otros archivos de configuración. Los campos de configuración actuales se combinarán sobre la configuración del archivo extendido.

env​

Tipo: { [envKey: string]: Options }
Ubicación: No puede anidarse dentro de otro bloque env

Permite opciones de configuración anidadas completas que solo se habilitarán cuando envKey coincida con la opción envName.

Nota: Las opciones env[envKey] se combinarán sobre las opciones especificadas en el objeto raíz.

overrides​

Tipo: Array<Options>
Ubicación: No puede anidarse dentro de otro objeto overrides o bloque env

Permite proporcionar un array de opciones que se combinarán secuencialmente en la configuración actual. Ideal para usar con "test"/"include"/"exclude" al definir condiciones para aplicar anulaciones. Ejemplo:

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

podría usarse para habilitar la opción compact en un archivo específico conocido por ser grande y minificado, indicando a Babel que no intente formatearlo.

test​

Tipo: MatchPattern | Array<MatchPattern> (MatchPattern)

Si ningún patrón coincide, el objeto de configuración actual se considera inactivo y se ignora durante el procesamiento. Más útil dentro de objetos overrides, pero permitido en cualquier lugar.

Nota: Estas alternancias no afectan las opciones programáticas y de carga de configuración en secciones anteriores, ya que se tienen en cuenta mucho antes de que la configuración esté preparada para la fusión.

include​

Tipo: MatchPattern | Array<MatchPattern> (MatchPattern)

Es un sinónimo de "test".

exclude​

Tipo: MatchPattern | Array<MatchPattern> (MatchPattern)

Si alguno de los patrones coincide, el objeto de configuración actual se considera inactivo y se ignora durante el procesamiento de la configuración. Esta opción es más útil cuando se usa dentro de un objeto de opción overrides, pero se permite en cualquier lugar.

Nota: Estas alternancias no afectan las opciones programáticas y de carga de configuración en secciones anteriores, ya que se tienen en cuenta mucho antes de que la configuración esté preparada para la fusión.

ignore​

Tipo: Array<MatchPattern> (MatchPattern)
Ubicación: No se permite dentro de presets

Si alguno de los patrones coincide, Babel detendrá inmediatamente todo el procesamiento de la compilación actual. Por ejemplo, un usuario podría querer hacer algo como

JavaScript
ignore: ["./lib"];

para deshabilitar explícitamente la compilación de Babel de archivos dentro del directorio lib.

Nota: Esta opción deshabilita todo el procesamiento de Babel de un archivo. Si bien eso tiene sus usos, también vale la pena considerar la opción "exclude" como una alternativa menos agresiva.

only​

Tipo: Array<MatchPattern> (MatchPattern)
Ubicación: No se permite dentro de presets

Si todos los patrones fallan al coincidir, Babel detendrá inmediatamente todo el procesamiento de la compilación actual. Por ejemplo, un usuario podría querer hacer algo como

JavaScript
only: ["./src"];

para habilitar explícitamente la compilación de Babel de archivos dentro del directorio src mientras deshabilita todo lo demás.

Nota: Esta opción deshabilita todo el procesamiento de Babel de un archivo. Si bien eso tiene sus usos, también vale la pena considerar las opciones "test"/"include" como una alternativa menos agresiva.

Opciones de Source Map​

inputSourceMap​

Tipo: boolean | SourceMap
Valor predeterminado: true

true intentará cargar un sourcemap de entrada desde el archivo mismo, si contiene un comentario //# sourceMappingURL=.... Si no se encuentra ningún mapa, o el mapa falla al cargarse o analizarse, se descartará silenciosamente.

Si se proporciona un objeto, se tratará como el objeto source map en sí.

sourceMaps​

Tipo: boolean | "inline" | "both"
Valor predeterminado: false

  • true para generar un sourcemap para el código e incluirlo en el objeto de resultado.

  • "inline" para generar un sourcemap y añadirlo como una URL de datos al final del código, pero no incluirlo en el objeto de resultado.

  • "both" es lo mismo que inline, pero incluirá el mapa en el objeto de resultado.

Las opciones en archivos de configuración no afectan si @babel/cli escribe archivos .map separados en disco. Cuando se pasa la opción CLI --source-maps a @babel/cli, también controlará si se escriben archivos .map:

  • true escribirá el mapa en un archivo .map en el disco

  • "inline" escribirá el archivo directamente, por lo que tendrá un data: que contiene el mapa

  • "both" escribirá el archivo con una URL data: y también un .map.

Nota: Estas opciones son un poco extrañas, por lo que puede tener más sentido usar simplemente true y manejar el resto en tu propio código, dependiendo de tu caso de uso.

sourceMap​

Este es un sinónimo de sourceMaps. Se recomienda usar sourceMaps.

sourceFileName​

Tipo: string
Valor predeterminado: path.basename(opts.filenameRelative) cuando está disponible, o "unknown"

El nombre que se utilizará para el archivo dentro del objeto del mapa de origen.

sourceRoot​

Tipo: string

Los campos sourceRoot que establecer en el mapa de origen generado, si se desea.

Opciones varias​

sourceType​

Tipo: "script" | "module" | "commonjs" | "unambiguous"
Por defecto: "module"

  • "script" - Analiza el archivo usando la gramática de Script de ECMAScript. No se permiten declaraciones import/export, y los archivos no están en modo estricto.

  • "module" - Analiza el archivo usando la gramática de Módulo de ECMAScript. Los archivos son automáticamente estrictos, y se permiten declaraciones import/export.

  • "commonjs" - Analiza el archivo como si se ejecutará en un entorno CommonJS. Esta opción se recomienda al transformar fuentes .cjs. Consulta la documentación del analizador sintáctico para ver las diferencias de sintaxis entre "script" y "commonjs".

  • "unambiguous" - Considera el archivo como "módulo" si hay declaraciones import/export presentes, de lo contrario considéralo "script".

unambiguous puede ser muy útil en contextos donde el tipo es desconocido, pero puede llevar a falsos positivos porque es perfectamente válido tener un archivo de módulo que no usa declaraciones import/export.

Esta opción es importante porque el tipo del archivo actual afecta tanto el análisis de archivos de entrada como ciertas transformaciones que podrían querer añadir uso de import/require al archivo actual.

Por ejemplo, @babel/plugin-transform-runtime depende del tipo del documento actual para decidir si insertar una declaración import o una llamada require(). @babel/preset-env también hace lo mismo con su opción "useBuiltIns". Como Babel trata los archivos como módulos ES por defecto, generalmente estos plugins/presets insertarán declaraciones import. Establecer el sourceType correcto es importante porque tener el tipo incorrecto puede llevar a casos donde Babel insertaría declaraciones import en archivos destinados a ser CommonJS. Esto es particularmente relevante en proyectos donde se compilan dependencias de node_modules, ya que insertar declaraciones import puede hacer que Webpack y otras herramientas interpreten un archivo como módulo ES, rompiendo lo que sería un archivo CommonJS funcional.

Nota: Esta opción no afectará el análisis de archivos .mjs, ya que actualmente están codificados para siempre analizarse como archivos "module".

assumptions​

Tipo: { [assumption: string]: boolean }
Por defecto: {}
Añadido en: v7.13.0
Ubicación: Permitido en opciones programáticas, archivos de configuración y presets.

Establece suposiciones que Babel puede hacer para producir salidas más pequeñas:

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

Para más información, consulta la documentación de suposiciones.

highlightCode​

Tipo: boolean
Predeterminado: true

Resalta tokens en fragmentos de código dentro de los mensajes de error de Babel para facilitar su lectura.

wrapPluginVisitorMethod​

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

Permite a los usuarios agregar un envoltorio a cada visitante para inspeccionar el proceso de visitas mientras Babel ejecuta los plugins.

  • key es una cadena opaca simple que representa el plugin siendo ejecutado.

  • nodeType es el tipo de nodo AST que se está visitando actualmente.

  • fn es la propia función visitante.

Los usuarios pueden devolver una función de reemplazo que debe llamar a la función original después de realizar cualquier registro y análisis que deseen.

parserOpts​

Tipo: {}

Un objeto opaco que contiene opciones para pasar al analizador sintáctico (parser) que se esté utilizando.

Para las opciones disponibles del analizador sintáctico, consulte Opciones del analizador sintáctico.

generatorOpts​

Tipo: {}

Un objeto opaco que contiene opciones para pasar al generador de código que se esté utilizando. Consulte Opciones del generador de código para las opciones más utilizadas.

Opciones del generador de código​

retainLines​

Tipo: boolean
Predeterminado: false

Babel hará un esfuerzo para generar código de modo que los elementos se impriman en la misma línea que tenían en el archivo original. Esta opción existe para que los usuarios que no pueden usar mapas de origen obtengan números de línea de error vagamente útiles, pero es solo un esfuerzo de buena fe y no está garantizada en todos los casos con todos los plugins.

compact​

Tipo: boolean | "auto"
Predeterminado: "auto"

"auto" establecerá el valor evaluando code.length > 500_000

Se omitirán todos los saltos de línea y espacios opcionales al generar código en modo compacto.

minified​

Tipo: boolean
Predeterminado: false

Incluye compact: true, omite punto y coma al final de bloques, omite () de new Foo() cuando es posible y puede generar versiones más cortas de literales.

auxiliaryCommentBefore​

Tipo: string

Permite especificar un comentario de prefijo para insertar antes de fragmentos de código que no estaban presentes en el archivo original.

Nota: La definición de lo que está y no está presente en el archivo original puede volverse un poco confusa, por lo que no se recomienda el uso de esta opción. Si necesita anotar código de alguna manera, es mejor hacerlo mediante un plugin de Babel.

auxiliaryCommentAfter​

Tipo: string

Permite especificar un comentario de prefijo para insertar después de fragmentos de código que no estaban presentes en el archivo original.

Nota: La definición de lo que está y no está presente en el archivo original puede volverse un poco confusa, por lo que no se recomienda el uso de esta opción. Si necesita anotar código de alguna manera, es mejor hacerlo mediante un plugin de Babel.

comments​

Tipo: boolean
Predeterminado: true

Proporciona un estado predeterminado para comentarios en shouldPrintComment si no se proporciona ninguna función. Consulte el valor predeterminado de esa opción para obtener más información.

shouldPrintComment​

Tipo: (value: string) => boolean
Predeterminado sin minified: (val) => opts.comments || /@license|@preserve/.test(val)
Predeterminado con minified: () => opts.comments

Una función que puede decidir si un comentario determinado debe incluirse en el código de salida de Babel.

Uso avanzado​

Para más opciones del generador de código, consulte Opciones del generador.

Opciones de módulos AMD / UMD / SystemJS​

moduleIds​

Tipo: boolean
Predeterminado: !!opts.moduleId

Habilita la generación de IDs de módulo.

moduleId​

Tipo: string

ID fijo para usar en el módulo. No puede usarse junto con getModuleId.

getModuleId​

Tipo: (name: string) => string

Dado el nombre de módulo generado por Babel, devuelve el nombre a usar. Devolver un valor falso usará el name original.

moduleRoot​

Tipo: string

Una ruta raíz para incluir en los nombres de módulo generados.

Conceptos de opciones​

MatchPattern​

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

Varias opciones de Babel realizan pruebas sobre rutas de archivos. En general, estas opciones admiten un enfoque de patrón común donde cada patrón puede ser:

  • string - Una ruta de archivo con soporte básico para **, * y *.ext. Cualquier archivo o carpeta padre que coincida con el patrón se considera una coincidencia. La ruta sigue la lógica de rutas normal de Node, por lo que en sistemas POSIX debe estar separada por /, mientras que en Windows se admiten tanto / como \.

  • RegExp - Una expresión regular para comparar contra el nombre de archivo normalizado. En POSIX, la expresión regular se ejecutará contra una ruta separada por /, y en Windows contra una ruta separada por \.

Es importante destacar que si se usa cualquiera de estos enfoques, Babel requiere que la opción filename esté presente; de lo contrario, se considerará un error.

  • (filename: string | void, context: { caller: { name: string } | void, envName: string, dirname: string }) => boolean es una función de retorno general que debe devolver un booleano indicando si hay coincidencia. La función recibe el nombre de archivo o undefined si no se proporcionó a Babel. También recibe las opciones actuales envName y caller especificadas en la llamada de alto nivel a Babel, y dirname que es el directorio del archivo de configuración o el directorio de trabajo actual (si la transformación se invocó mediante programación).
nota

La coincidencia basada en cadenas no admite patrones glob completos. ** coincide con 0 o más partes de ruta, * coincide exactamente con 1 parte de ruta, y *.ext coincide con un comodín con extensión. Usar * de otras formas (por ejemplo, dentro de una ruta o nombre de archivo) no es compatible. Si necesita coincidencias complejas, utilice expresiones regulares o una función personalizada en la configuración.

Estos son algunos ejemplos de cómo funciona la coincidencia:

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

Aquí hay ejemplos donde * no tiene función de comodín:

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

Fusión​

Consulta Cómo Babel fusiona elementos de configuración.

Entradas de plugins y presets​

PluginEntry / PresetEntry​

Los elementos individuales de plugins/presets pueden tener varias estructuras:

  • EntryTarget - Plugin individual

  • [EntryTarget, EntryOptions] - Plugin individual con opciones

  • [EntryTarget, EntryOptions, string] - Plugin individual con opciones y nombre (ver fusión para más detalles sobre nombres)

  • ConfigItem - Elemento de configuración creado por babel.createConfigItem().

El mismo EntryTarget puede usarse múltiples veces solo si cada instancia tiene un nombre diferente; hacerlo de otra forma generará un error de plugin/preset duplicado.

Esto puede resultar confuso, así que como ejemplo:

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​

Tipo: string | {} | Function

Un plugin o preset puede especificarse de diferentes formas:

  • string - Una ruta al estilo require o identificador de plugin/preset. Los identificadores pasarán por normalización de nombres.

  • {} | Function - Un objeto o función real de plugin/preset después de ser cargado con require().

EntryOptions​

Tipo: undefined | {} | false

Las opciones se pasan a cada plugin/preset durante su ejecución. undefined se normaliza a un objeto vacío.

false indica que una entrada está completamente deshabilitada. Esto es útil cuando el orden es importante pero se necesita una condición separada para habilitar elementos. Por ejemplo:

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

habilitaría el plugin two para archivos en src, pero two aún se ejecutaría entre one y three.

Normalización de nombres​

Por defecto, Babel espera que los plugins tengan el prefijo babel-plugin- o babel-preset-. Para evitar repetición, Babel normaliza nombres automáticamente al cargar elementos con estas reglas principales:

  • Las rutas absolutas permanecen intactas.

  • Las rutas relativas que comienzan con ./ permanecen intactas.

  • Las referencias a archivos dentro de paquetes permanecen intactas.

  • Cualquier identificador con prefijo module: tendrá el prefijo removido pero permanecerá intacto.

  • plugin-/preset- se inyectará al inicio de paquetes con ámbito @babel que carezcan de este prefijo.

  • babel-plugin-/babel-preset- se inyectará como prefijo en paquetes sin ámbito que carezcan de él.

  • babel-plugin-/babel-preset- se inyectará como prefijo en paquetes con ámbito @ que no lo contengan en ningún lugar de su nombre.

  • babel-plugin/babel-preset se inyectará como nombre de paquete si solo se especifica el ámbito @.

Aquí hay ejemplos aplicados en contexto de plugins:

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"