Archivos de Configuración

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 →

Tipos de archivos de configuración

Babel tiene dos formatos de archivos de configuración paralelos, que pueden usarse conjuntamente o de forma independiente.

History

Version	Changes
v7.21.0	Support .babelrc.cts and babel.config.cts (Experimental)
v7.8.0	Support .babelrc.mjs and babel.config.mjs
v7.7.0	Support .babelrc.json, .babelrc.cjs, babel.config.json, babel.config.cjs

• Configuración para todo el proyecto

  • Archivos babel.config.* con las siguientes extensiones: .json, .js, .cjs, .mjs, .cts.

• Configuración relativa al archivo

  • Archivos .babelrc.* con las siguientes extensiones: .json, .js, .cjs, .mjs, .cts.
  • Archivo .babelrc sin extensión.
  • Archivos package.json con una clave "babel".

Configuración para todo el proyecto

Novedad en Babel 7.x: Babel introduce el concepto de directorio "raíz", que por defecto es el directorio de trabajo actual. Para la configuración global, Babel buscará automáticamente un archivo babel.config.json, o equivalente usando las extensiones admitidas, en este directorio raíz. Alternativamente, los usuarios pueden especificar un valor explícito "configFile" para sobrescribir este comportamiento predeterminado.

Al estar desvinculados de la ubicación física del archivo, estos ajustes globales son ideales para configuraciones de amplio alcance. Permiten que plugins y presets se apliquen fácilmente a archivos en node_modules o paquetes con enlaces simbólicos, escenarios que eran complejos de gestionar en Babel 6.x.

La principal desventaja es su dependencia del directorio de trabajo, lo que puede complicar su uso en monorepos cuando dicho directorio no coincide con la raíz del monorepo. Consulte la documentación sobre monorepos para ver ejemplos de configuración en este contexto.

Estas configuraciones globales pueden desactivarse estableciendo "configFile" en false.

Configuración relativa al archivo

Babel carga archivos .babelrc.json (o equivalentes con extensiones admitidas) ascendiendo en la estructura de directorios desde el "archivo" que se compila (con las limitaciones indicadas). Esto permite crear configuraciones independientes para secciones de un paquete. Estas configuraciones locales se fusionan sobre los valores globales, siendo útiles para anulaciones específicas, aunque esto también puede lograrse mediante "overrides".

Al usar configuraciones relativas, considere estos casos particulares:

• La búsqueda se detiene al encontrar un package.json, por lo que la configuración solo aplica dentro de un paquete individual.

• El "archivo" compilado debe estar dentro de paquetes "babelrcRoots", o la búsqueda se omitirá por completo.

Estas restricciones implican que:

• Los archivos .babelrc.json solo aplican a archivos dentro de su propio paquete

• Los archivos .babelrc.json en paquetes no considerados 'raíz' por Babel se ignoran a menos que se habilite con "babelrcRoots".

Vea la documentación de monorepos para configurar entornos con múltiples paquetes. Estas configuraciones pueden desactivarse estableciendo "babelrc" en false.

Carga de .babelrc en 6.x vs 7.x

Usuarios de Babel 6.x deberán considerar estos casos particulares, novedosos en la versión 7.x. Estas restricciones abordan problemas comunes en Babel 6.x:

• Los archivos .babelrc aplicaban a dependencias en node_modules, frecuentemente de forma inesperada.

• Los archivos .babelrc no se aplicaban a dependencias enlazadas simbólicamente en node_modules cuando se esperaba que se comportaran como dependencias normales.

• Los archivos .babelrc dentro de dependencias en node_modules eran detectados, aunque generalmente los plugins y presets internos no estaban instalados, y podrían no ser válidos en la versión de Babel que compilaba el archivo.

Estos casos afectarán principalmente a usuarios con estructura de monorepo, porque si tienes

.babelrc
packages/
  mod1/
    package.json
    src/index.js
  mod2/
    package.json
    src/index.js

la configuración ahora será ignorada por completo, ya que cruza un límite de paquete.

Una alternativa sería crear un .babelrc en cada subpaquete que use "extends" como

.babelrc.json

{ "extends": "../../.babelrc" }

Desafortunadamente, este enfoque puede ser algo repetitivo y, dependiendo de cómo se use Babel, podría requerir configurar "babelrcRoots".

Dado esto, puede ser más deseable renombrar el .babelrc como un "babel.config.json" de todo el proyecto. Como se mencionó en la sección de todo el proyecto anterior, esto puede requerir configurar explícitamente "configFile" ya que Babel no encontrará el archivo de configuración si el directorio de trabajo no es correcto.

Extensiones de archivo admitidas

Babel puede configurarse usando cualquier extensión de archivo admitida nativamente por Node.js, como se menciona en la sección Tipos de archivo de configuración:

• babel.config.json y .babelrc.json se analizan como JSON5 y deben contener un objeto que coincida con el formato de opciones que acepta Babel. Han sido compatibles desde v7.7.0.

  Recomendamos usar este tipo de archivo siempre que sea posible: los archivos de configuración JS son útiles si tienes configuraciones complejas que son condicionales o calculadas en tiempo de compilación. Sin embargo, la desventaja es que las configuraciones JS son menos analizables estáticamente, lo que afecta negativamente la capacidad de caché, linting, autocompletado en IDEs, etc. Dado que babel.config.json y .babelrc.json son archivos JSON estáticos, permiten que otras herramientas que usan Babel (como empaquetadores) almacenen en caché los resultados de manera segura, lo que puede ser una gran ventaja en el rendimiento de compilación.

• babel.config.cjs y .babelrc.cjs te permiten definir tu configuración como CommonJS usando module.exports. Han sido compatibles desde v7.7.0.

• babel.config.mjs y .babelrc.mjs usan módulos ECMAScript nativos. Son compatibles con Node.js 13.2+ (o versiones anteriores mediante la bandera --experimental-modules). Recuerda que los módulos ECMAScript nativos son asíncronos (¡por eso import() siempre devuelve una promesa!): por esta razón, los archivos de configuración .mjs fallarán al llamar a Babel de manera síncrona. Han sido compatibles desde v7.8.0.

• babel.config.js y .babelrc.js se comportan como sus equivalentes .mjs cuando tu archivo package.json contiene la opción "type": "module", de lo contrario son exactamente iguales que los archivos .cjs.

• babel.config.cts y .babelrc.cts te permiten definir tu configuración como TypeScript + CommonJS. Debes instalar @babel/preset-typescript o ejecutar Babel usando ts-node.

  nota

  🚧 Esta funcionalidad es experimental. Aún no es posible usar archivos babel.config.ts y babel.config.mts, pendiente de la estabilización de la API de carga ESM de Node.js.

Los archivos de configuración JavaScript pueden exportar un objeto o una función que, al llamarse, devolverá la configuración generada. Las configuraciones que devuelven funciones tienen poderes especiales porque pueden acceder a una API expuesta por el propio Babel. Consulta API de función de configuración para más información.

nota

Por motivos de compatibilidad, .babelrc es un alias de .babelrc.json.

Monorepos

Los repositorios estructurados como monorepos suelen contener muchos paquetes, lo que frecuentemente genera los casos especiales mencionados en la configuración relativa a archivos y la carga de archivos de configuración en general. Esta sección ayuda a comprender cómo abordar la configuración en monorepos.

En configuraciones de monorepo, lo fundamental es entender que Babel trata tu directorio de trabajo como su "root" lógico, lo que causa problemas si deseas ejecutar herramientas de Babel dentro de un subpaquete específico sin que Babel se aplique a todo el repositorio.

Además, es importante decidir si usar archivos .babelrc.json o solo un babel.config.json central. Los archivos .babelrc.json no son obligatorios para configuraciones específicas de subcarpetas como en Babel 6, por lo que frecuentemente no son necesarios en Babel 7, prefiriéndose babel.config.json.

Archivo raíz babel.config.json

El primer paso en cualquier estructura de monorepo debe ser crear un archivo babel.config.json en la raíz del repositorio. Esto establece el concepto central de Babel del directorio base de tu repositorio. Incluso si planeas usar archivos .babelrc.json para configurar paquetes individuales, es crucial tenerlo como punto central para opciones a nivel de repositorio.

Frecuentemente puedes colocar toda la configuración del repositorio en el babel.config.json raíz. Con "overrides", puedes especificar fácilmente configuración que solo aplica a subcarpetas específicas, lo que suele ser más manejable que crear múltiples archivos .babelrc.json en el repositorio.

El primer problema común es que, por defecto, Babel espera cargar archivos babel.config.json desde el directorio establecido como su "root". Si has creado un babel.config.json pero ejecutas Babel dentro de un paquete individual, p.ej.:

Shell

cd packages/some-package;
babel src -d dist

el "root" que Babel usa en ese contexto no será tu raíz de monorepo, y no podrá encontrar el archivo babel.config.json.

Si todos tus scripts de construcción se ejecutan desde la raíz del repositorio, funcionará correctamente. Pero si ejecutas la compilación de Babel desde un subpaquete, debes indicarle a Babel dónde buscar la configuración. La forma recomendada es mediante la opción "rootMode" con valor "upward", que hace que Babel busque ascendentemente desde el directorio de trabajo tu archivo babel.config.json, usando su ubicación como valor de "root".

Un método útil para verificar si tu configuración se detecta es agregar una llamada console.log() dentro del archivo si es un babel.config.json JavaScript: el log se ejecutará durante la primera carga de Babel.

La implementación varía por proyecto, pero aquí hay ejemplos comunes:

CLI

Shell

babel --root-mode upward src -d lib

@babel/register

JavaScript

require("@babel/register")({
  rootMode: "upward",
});

Webpack

webpack.config.js

module: {
  rules: [
    {
      loader: "babel-loader",
      options: {
        rootMode: "upward",
      },
    },
  ];
}

Jest

Jest suele instalarse en la raíz del monorepo y puede no requerir configuración adicional, pero si se instala por paquete, desafortunadamente la configuración puede ser más compleja.

La parte clave es crear un transformador personalizado para Jest que envuelva el comportamiento predeterminado de babel-jest para establecer la opción, por ejemplo:

wrapper.js

module.exports = require("babel-jest").default.createTransformer({
  rootMode: "upward",
});

Al guardar este archivo, lo usarías en lugar de babel-jest en tus opciones de Jest mediante transform option:

jest.config.js

"transform": {
  "^.+\\.jsx?$": "./path/to/wrapper.js"
},

por lo que todos los archivos JS se procesarán con tu versión de babel-jest con la opción habilitada.

nota

Cuando uses babel-jest < 27, debes omitir la parte .default: require("babel-jest").createTransformer({ ....

Otros

Existen muchas herramientas, pero en esencia necesitan que la opción rootMode esté habilitada si el directorio de trabajo no es la raíz del monorepo.

Archivos .babelrc.json en subpaquetes

Similar a cómo los archivos babel.config.json deben estar en la "raíz", los archivos .babelrc.json deben estar por defecto en el paquete raíz. Esto significa que, de igual forma que el directorio de trabajo afecta la carga de babel.config.json, también afecta la carga de .babelrc.json.

Suponiendo que ya cargaste correctamente tu archivo babel.config.json como se discutió anteriormente, Babel solo procesará archivos .babelrc.json dentro de ese paquete raíz (y no en subpaquetes), por ejemplo:

package.json
babel.config.js
packages/
  mod/
    package.json
    .babelrc.json
    index.js

compilar el archivo packages/mod/index.js no cargará packages/mod/.babelrc.json porque este .babelrc.json está dentro de un subpaquete, no del paquete raíz.

Para habilitar el procesamiento de ese .babelrc.json, querrás usar la opción "babelrcRoots" dentro de tu archivo babel.config.json para:

JavaScript

babelrcRoots: [
  ".",
  "packages/*",
],

que Babel considere todos los paquetes packages/* como permitidos para cargar archivos .babelrc.json, junto con la raíz original del repositorio.

API de función de configuración

Los archivos de configuración JS pueden exportar una función que recibe la API de configuración como parámetro:

babel.config.js

module.exports = function(api) {
  return {};
};

El objeto ConfigAPI api proporciona las siguientes propiedades o métodos:

api.version

Tipo: string

La cadena de versión de la versión de Babel que carga el archivo de configuración.

api.cache

Las configuraciones JS son potentes porque pueden calcular configuraciones dinámicamente, pero la desventaja es que complican el almacenamiento en caché. Babel quiere evitar re-ejecutar la función de configuración cada vez que se compila un archivo, ya que esto requeriría re-ejecutar todos los plugins y presets referenciados.

Para evitar esto, Babel espera que los usuarios de funciones de configuración especifiquen cómo gestionar el almacenamiento en caché.

• api.cache.forever() - Almacena permanentemente la configuración calculada y nunca vuelve a llamar a la función.

• api.cache.never() - No almacena en caché esta configuración y re-ejecuta la función cada vez.

• api.cache.using(() => process.env.NODE_ENV) - Almacena en caché según el valor de NODE_ENV. Cada vez que el callback using retorna un valor diferente al esperado, la función de configuración completa se vuelve a ejecutar y se añade una nueva entrada a la caché.

• api.cache.invalidate(() => process.env.NODE_ENV) - Usa NODE_ENV para la caché.
  Cuando el callback using devuelve un valor diferente al esperado,
  la función de configuración se ejecuta nuevamente y todas las entradas de caché se reemplazan con el nuevo resultado.

• api.cache(true) - Equivalente a api.cache.forever()

• api.cache(false) - Equivalente a api.cache.never()

Dado que el resultado del callback determina la validez de la entrada de caché, se recomienda:

• Los callbacks deben ser pequeños y libres de efectos secundarios.

• Los callbacks deben devolver valores con el rango más reducido posible. Por ejemplo,
  .using(() => process.env.NODE_ENV) no es ideal porque crearía un número indeterminado
  de entradas de caché según los valores de NODE_ENV. Es más seguro usar
  .using(() => process.env.NODE_ENV === "development") ya que la entrada de caché
  solo podrá ser true o false.

api.env(...)

Como NODE_ENV es común para alternar comportamientos, Babel incluye una API específica
para esto. Permite verificar rápidamente el "envName" con el que
se cargó Babel, que considera NODE_ENV si no hay otro entorno sobrescrito.

Tiene varias formas:

• api.env("production") devuelve true si envName === "production".

• api.env(["development", "test"]) devuelve true si ["development", "test"].includes(envName).

• api.env() devuelve el envName actual como string.

• api.env(envName => envName.startsWith("test-")) devuelve true si el entorno comienza con "test-".

nota

Esta función internamente usa api.cache para asegurar que Babel reconozca
la dependencia del envName. No debe usarse con api.cache.forever() o api.cache.never().

api.caller(cb)

Accede a los datos caller pasados a Babel. Como múltiples instancias de Babel
pueden ejecutarse en el mismo proceso con diferentes valores caller, esta API
configura automáticamente api.cache (igual que api.env()).

El valor caller está disponible como primer parámetro del callback. Se usa mejor con:

JavaScript

function isBabelRegister(caller) {
  return !!(caller && caller.name === "@babel/register");
}

module.exports = function(api) {
  const isRegister = api.caller(isBabelRegister);

  return {
    // ...
  };
};

para alternar comportamientos basados en entornos específicos.

api.assertVersion(range)

Aunque api.version es útil, a veces basta con declarar tu versión.
Esta API ofrece un método simple para hacerlo con:

JavaScript

module.exports = function(api) {
  api.assertVersion("^7.2");

  return {
    // ...
  };
};