Saltar al contenido principal

Guía de uso

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 →

Existen varias herramientas en el ecosistema de Babel que facilitan su uso tanto para usuarios finales como para quienes integran Babel en sus proyectos. Esta es una introducción rápida a dichas herramientas; podrás encontrar más detalles en la sección "Uso" de la documentación.

Si estás usando un framework, la configuración de Babel puede variar o incluso estar preconfigurada. En su lugar, consulta nuestra guía interactiva de configuración.

Visión general​

Esta guía te mostrará cómo compilar tu código JavaScript con sintaxis ES2015+ para que funcione en navegadores actuales. Esto implica tanto transformar nueva sintaxis como aplicar polyfills para características faltantes.

El proceso completo de configuración incluye:

  1. Ejecutar estos comandos para instalar los paquetes:

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

  2. Crear un archivo de configuración llamado babel.config.json (requiere v7.8.0 o superior) en la raíz de tu proyecto con este contenido:

    babel.config.json
    {
      "presets": [
        [
          "@babel/preset-env",
          {
            "targets": {
              "edge": "17",
              "firefox": "60",
              "chrome": "67",
              "safari": "11.1"
            },
            "useBuiltIns": "usage",
            "corejs": "3.6.5"
          }
        ]
      ]
    }

    La lista de navegadores anterior es solo un ejemplo arbitrario. Deberás adaptarla según los navegadores que quieras soportar. Consulta aquí para más opciones de @babel/preset-env.

O babel.config.js si usas una versión anterior de Babel

babel.config.js
const presets = [
  [
    "@babel/preset-env",
    {
      targets: {
        edge: "17",
        firefox: "60",
        chrome: "67",
        safari: "11.1",
      },
      useBuiltIns: "usage",
      corejs: "3.6.4",
    },
  ],
];

module.exports = { presets };

  1. Ejecutar este comando para compilar todo tu código del directorio src a lib:

    Shell
    ./node_modules/.bin/babel src --out-dir lib

    Puedes usar el ejecutor de paquetes npm incluido en npm@5.2.0 para acortar el comando reemplazando ./node_modules/.bin/babel con npx babel

Continúa leyendo para una explicación paso a paso de este proceso y una introducción a cada herramienta utilizada.

Uso básico con CLI​

Todos los módulos de Babel se publican como paquetes npm independientes bajo el ámbito @babel (desde la versión 7). Este diseño modular permite diversas herramientas especializadas para casos de uso específicos. Aquí veremos @babel/core y @babel/cli.

Biblioteca principal​

La funcionalidad central de Babel reside en el módulo @babel/core. Tras instalarlo:

npm install --save-dev @babel/core

puedes requirearlo directamente en tu programa JavaScript y usarlo así:

JavaScript
const babel = require("@babel/core");

babel.transformSync("code", optionsObject);

Como usuario final, probablemente querrás instalar otras herramientas que sirvan de interfaz para @babel/core y se integren bien con tu flujo de desarrollo. Aun así, conviene consultar su documentación para conocer las opciones disponibles, ya que la mayoría pueden configurarse desde otras herramientas.

Herramienta CLI​

@babel/cli es una herramienta que permite usar Babel desde la terminal. Aquí tienes el comando de instalación y un ejemplo básico de uso:

npm install --save-dev @babel/core @babel/cli

./node_modules/.bin/babel src --out-dir lib

Esto analizará todos los archivos JavaScript en el directorio src, aplicará las transformaciones configuradas y enviará cada archivo al directorio lib. Como aún no hemos especificado transformaciones, el código de salida será idéntico al de entrada (sin preservar el formato exacto). Podemos definir transformaciones mediante opciones adicionales.

Hemos utilizado la opción --out-dir anteriormente. Puedes ver el resto de opciones aceptadas por la herramienta CLI ejecutándola con --help. Pero las más importantes para nosotros ahora mismo son --plugins y --presets.

Plugins y presets​

Las transformaciones se implementan mediante plugins, pequeños programas de JavaScript que instruyen a Babel sobre cómo realizar transformaciones en el código. Incluso puedes escribir tus propios plugins para aplicar las transformaciones que desees. Para convertir sintaxis ES2015+ a ES5, podemos usar plugins oficiales como @babel/plugin-transform-arrow-functions:

npm install --save-dev @babel/plugin-transform-arrow-functions

./node_modules/.bin/babel src --out-dir lib --plugins=@babel/plugin-transform-arrow-functions

Ahora todas las funciones flecha en nuestro código se transformarán en expresiones de función compatibles con ES5:

JavaScript
const fn = () => 1;

// converted to

var fn = function fn() {
  return 1;
};

¡Es un buen comienzo! Pero también tenemos otras características ES2015+ en nuestro código que queremos transformar. En lugar de añadir todos los plugins uno por uno, podemos usar un "preset", que es simplemente un conjunto predefinido de plugins.

Al igual que con los plugins, también puedes crear tus propios presets para compartir cualquier combinación de plugins que necesites. Para nuestro caso de uso, existe un excelente preset llamado env.

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

./node_modules/.bin/babel src --out-dir lib --presets=@babel/env

Sin configuración alguna, este preset incluirá todos los plugins necesarios para admitir JavaScript moderno (ES2015, ES2016, etc.). Pero los presets también pueden recibir opciones. En lugar de pasar tanto las opciones de CLI como las del preset desde la terminal, veamos otra forma de pasar opciones: archivos de configuración.

Configuración​

Existen varias formas de usar archivos de configuración según tus necesidades. Asegúrate de leer nuestra guía detallada sobre cómo configurar Babel para más información.

Por ahora, creemos un archivo llamado babel.config.json (requiere v7.8.0 o superior) con el siguiente contenido:

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        }
      }
    ]
  ]
}

Ahora el preset env solo cargará plugins de transformación para características no disponibles en nuestros navegadores objetivo. Ya tenemos todo listo para la sintaxis. Veamos ahora los polyfills.

Polyfill​

🚨 As de Babel 7.4.0, este paquete ha quedado obsoleto en favor de incluir directamente core-js/stable (para aplicar polyfill a características de ECMAScript):

JavaScript
import "core-js/stable";

Si estás compilando generadores o funciones asíncronas a ES5, y usas una versión de @babel/core o @babel/plugin-transform-regenerator anterior a 7.18.0, también debes cargar el paquete regenerator runtime. Se carga automáticamente al usar la opción useBuiltIns: "usage" de @babel/preset-env o @babel/plugin-transform-runtime.

El módulo @babel/polyfill incluye core-js y un regenerador de runtime personalizado para emular un entorno ES2015+ completo.

Esto significa que puedes usar nuevas funciones integradas como Promise o WeakMap, métodos estáticos como Array.from u Object.assign, métodos de instancia como Array.prototype.includes, y funciones generadoras (cuando se usan con el plugin regenerador). El polyfill añade al ámbito global y a prototipos nativos como String para lograr esto.

Para autores de bibliotecas/herramientas esto puede ser excesivo. Si no necesitas métodos de instancia como Array.prototype.includes, puedes evitar contaminar el ámbito global usando el plugin transform runtime en lugar de @babel/polyfill.

Para ir más allá, si sabes exactamente qué características necesitas con polyfills, puedes importarlas directamente desde core-js.

Como estamos construyendo una aplicación, simplemente podemos instalar @babel/polyfill:

npm install --save @babel/polyfill

Nota: Usa la opción --save en lugar de --save-dev ya que este polyfill debe ejecutarse antes de tu código fuente.

Afortunadamente, estamos usando el preset env que tiene la opción "useBuiltIns". Cuando se establece en "usage", aplica la optimización mencionada donde solo incluyes los polyfills necesarios. Con esta nueva opción la configuración cambia así:

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        },
        "useBuiltIns": "usage"
      }
    ]
  ]
}

Ahora Babel inspeccionará todo tu código para detectar características faltantes en tus entornos objetivo e incluirá solo los polyfills requeridos. Por ejemplo este código:

JavaScript
Promise.resolve().finally();

se transformaría en esto (porque Edge 17 no tiene Promise.prototype.finally):

JavaScript
require("core-js/modules/es.promise.finally");

Promise.resolve().finally();

Si no usáramos el preset env con la opción "useBuiltIns" establecida en "usage" (por defecto es "false"), tendríamos que requerir el polyfill completo solo una vez en nuestro punto de entrada antes que cualquier otro código.

Por ejemplo:

babel.config.json
{
  "presets": [
    [
      "@babel/preset-env",
      {
        "targets": {
          "edge": "17",
          "firefox": "60",
          "chrome": "67",
          "safari": "11.1"
        },
        "useBuiltIns": "entry"
      }
    ]
  ]
}

Then import core-js (to polyfill ECMAScript features) first, in our entry file to emulate a full ES2015+ environment since @babel/polyfill has been deprecated:

JavaScript
 import "core-js/stable";

Resumen​

Usamos @babel/cli para ejecutar Babel desde la terminal, @babel/polyfill para aplicar polyfill a las nuevas características de JavaScript, y el preset env para incluir solo transformaciones y polyfills de las características que usamos y que faltan en nuestros navegadores objetivo.

Para más información sobre cómo configurar Babel con tu sistema de compilación, IDE y otros, consulta nuestra guía de configuración interactiva.