Metro Bundler: qué es, agrupación de proyectos y principio de funcionamiento

Qué es Metro Bundler

Metro Bundler es un agrupador de JavaScript de código abierto desarrollado por Meta para React Native y utilizado por defecto en todos los proyectos del framework. La tarea de Metro es tomar el código JavaScript del proyecto junto con las dependencias y agruparlo en uno o varios bundles que se ejecutan en el dispositivo. A diferencia de los agrupadores universales (Webpack, Rollup, Parcel), Metro está optimizado para las especificidades del desarrollo móvil: tiempo mínimo de compilación, actualizaciones incrementales durante el desarrollo y manejo correcto de módulos de plataforma (módulos nativos Objective-C, Swift, Java, Kotlin). Metro se incluye en React Native CLI y no requiere instalación adicional. A partir de React Native 0.72, Metro versión 0.80+ admite transpilación paralela de módulos, acelerando las compilaciones en procesadores multinúcleo hasta en un 40%.

Arquitectura de Metro: Resolver, Transformer y Bundler

La arquitectura de Metro se divide en tres componentes independientes: Resolver, Transformer y Bundler. El Resolver se encarga de encontrar y resolver módulos: lee expresiones import/require, encuentra los archivos correspondientes considerando las extensiones de plataforma y devuelve rutas absolutas. El Transformer realiza la transpilación: aplica Babel con presets y plugins, transforma JSX, TypeScript o Flow a JavaScript puro. El Bundler es la etapa final: toma el grafo de dependencias del Resolver y los archivos transformados del Transformer, luego los serializa en uno o varios bundles (module bundles). La separación en tres pasos permite a Metro almacenar en caché los resultados de cada etapa: si solo cambió un archivo, el Resolver y el Bundler pueden usar la caché para los módulos restantes, proporcionando un aumento de velocidad de compilación de hasta 10 veces en modo de desarrollo.

Resolver: resolución de módulos y búsqueda con conocimiento de plataforma

El Resolver en Metro implementa un algoritmo de resolución de módulos parcialmente compatible con la resolución de módulos de Node.js. La diferencia clave con Node.js es el soporte para extensiones de plataforma: require(‘./Component’) busca Component.native.js, Component.ios.js, Component.android.js en el orden de prioridad especificado. El Resolver también admite el campo package.json “react-native” para mapear módulos a implementaciones alternativas: este es el mecanismo estándar para bibliotecas con código específico de plataforma. Si no se encuentra un archivo, el Resolver lanza un error con la pila de búsqueda completa.

Transformer: Babel y transpilación

El Transformer dentro de Metro utiliza Babel con el preset metro-react-native-babel-preset. La configuración estándar incluye: transformación de JSX a React.createElement, soporte de TypeScript (eliminación de tipos), soporte de Flow y polyfills para estándares modernos de JavaScript (async/await, optional chaining, nullish coalescing). El Transformer funciona en modo paralelo: cada módulo se transpila de forma independiente, utilizando un grupo de procesos worker (por defecto, el número corresponde al número de CPU). A partir de Metro 0.80, se admite Granular Transformer Cache: invalidación de caché a nivel de archivo individual.

Extensiones específicas de plataforma en Metro

Una de las características clave de Metro es el soporte para extensiones de archivo de plataforma. Un proyecto de React Native puede contener tres versiones del mismo módulo: Component.ios.js (iOS), Component.android.js (Android) y Component.native.js (ambas plataformas). Al importar require(‘./Component’), el Resolver selecciona automáticamente la versión correcta según la plataforma de compilación objetivo. Esto permite escribir código dependiente de la plataforma sin construcciones condicionales Platform.OS. Orden de prioridad: nombre.plataforma.js > nombre.native.js > nombre.js. La extensión .native.js se utiliza para código común que funciona en ambas plataformas pero es incompatible con la web. Las extensiones .ios.js y .android.js sirven para implementar características específicas: navegación, gestos, operaciones del sistema de archivos. Metro admite extensiones personalizadas a través de la configuración resolver.sourceExts.

// metro.config.js — configuración de sourceExts y watchFolders
const config = {
  resolver: {
    sourceExts: ['jsx', 'js', 'tsx', 'ts', 'json'],
    platformExtensions: ['ios', 'android', 'native'],
  },
  transformer: {
    babelTransformerPath: require('metro-react-native-babel-transformer'),
  },
  watchFolders: [path.resolve('../shared')],
};

Hot Reload y Fast Refresh en Metro

Fast Refresh es un mecanismo de recarga en caliente para React Native construido sobre Metro. Cuando un desarrollador cambia un archivo, Metro re-transpila solo el módulo modificado y envía la actualización a la aplicación a través de WebSocket. Fast Refresh actualiza la interfaz sin recargar toda la aplicación y conserva el estado de los componentes de React si solo se modificaron JSX o estilos. Si se modifica código con hooks o estado, Fast Refresh vuelve a montar solo el componente modificado. Metro admite dos modos: Hot Module Replacement (HMR) para reemplazo de módulos sobre la marcha y Live Reload para recarga completa de la aplicación cuando cambian módulos nativos o configuración. Fast Refresh está habilitado por defecto en React Native 0.76 y no requiere configuración adicional: basta con ejecutar npx react-native start.

Configuración de Metro: metro.config.js

El archivo metro.config.js es el archivo de configuración de Metro ubicado en la raíz de un proyecto React Native. En él se configuran: resolver (sourceExts, platformExtensions, extraNodeModules), transformer (babelTransformerPath, minifierConfig), server (port, host, enableFastRefresh) y watcher (watchFolders, healthCheck). La configuración estándar de Metro hereda del paquete @react-native/metro-config (React Native 0.76+). Para proyectos con monorepositorio, añada watchFolders: esto permite a Metro rastrear cambios en paquetes fuera de la raíz del proyecto. Para configurar sourceExts, agregue ‘svg’, ‘png’, ‘gql’ para transformadores personalizados. Metro admite configuraciones asíncronas a través de async function: útil para generación dinámica de configuración según el entorno.

Optimización de compilación mediante configuración

La optimización de las compilaciones de Metro comienza con una configuración adecuada de la caché. Establezca maxWorkers al número de CPU menos 1. Para distribuciones, use resetCache en CI. Minimice sourceExts: las extensiones adicionales ralentizan la resolución de módulos. Para proyectos grandes, configure watchFolders solo para los directorios necesarios. Metro admite la minificación Hermes bytecode, que produce un tamaño de bundle menor que Terser estándar: use minifierPath: ‘metro-minify-terser’.

Hermes bundling: compilación a bytecode

Metro admite un modo de compilación directamente a Hermes bytecode — omitiendo la etapa de AST de JavaScript. Al compilar con HermesTransformer, los módulos se compilan en HBC (Hermes ByteCode) en lugar de JavaScript plano. Esto proporciona: menor tamaño de bundle (30-40%), inicio de aplicación más rápido (20-30%) y menor consumo de memoria. Para habilitarlo, configure hermesCommand en metro.config.js y active la bandera Hermes en build.gradle (Android) o Podfile (iOS). La compilación de bundles Hermes se realiza en dos etapas: primero Metro compila el bundle JavaScript, luego Hermes CLI lo convierte a HBC. A partir de React Native 0.70, Hermes es el motor predeterminado en Android; en iOS requiere habilitación explícita.

Metro vs Webpack: comparación de enfoques

La diferencia entre Metro y Webpack se debe a diferentes objetivos. Webpack es un agrupador universal para la web con un enorme ecosistema de plugins y loaders. Metro es un agrupador especializado para React Native donde la prioridad es la velocidad de compilación incremental y el trabajo correcto con módulos nativos. Webpack utiliza un grafo de módulos persistente con invalidación inteligente de caché: esto proporciona reconstrucciones rápidas en la web, pero crea problemas con las extensiones de plataforma. Metro no almacena en caché el grafo entre compilaciones, sino que lo construye cada vez: esto simplifica el manejo de extensiones de plataforma y módulos Haste. Webpack admite importaciones dinámicas con chunks, Metro también: a través de React.lazy() y Suspense, pero con la limitación de una solicitud activa. El ecosistema de Metro es significativamente menor: no hay reemplazo para style-loader, css-loader, file-loader: estas tareas se resuelven de manera diferente en React Native.

Cuándo elegir Metro

Metro es la única opción correcta para proyectos React Native. Webpack no admite la resolución con conocimiento de plataforma de forma nativa, y configurar React Native con Webpack requiere un esfuerzo significativo (haul bundler, expo web packager). Metro está integrado en React Native CLI, es compatible con el equipo oficial de Meta y recibe actualizaciones con cada versión de React Native. Para proyectos React Native Web, puede usar Webpack para compilaciones web mientras mantiene Metro para bundles móviles.