Sebastian Gomez

Jul 21, 2024

Updated: Jun 25, 2026

Explorando la Construcción de Extensiones de Chrome con Esbuild

En esta ocasión quería aprender cómo funciona esbuild para extensiones de Chrome, así que hice una búsqueda rápida en Google y encontré un repositorio muy interesante creado por Marton Lederer. Decidí clonarlo y ver qué pasaba al ejecutarlo. Aquí comparto mi experiencia y algunos aprendizajes clave, paso a paso, para que puedas seguirla conmigo.

El repositorio está disponible en GitHub: martonlederer/esbuild react chrome extension.

Nota sobre Manifest V3. Toda extensión nueva debe usar Manifest V3. Manifest V2 quedó descontinuado y Chrome ya dejó de cargar extensiones MV2, así que es un punto que no podemos saltarnos. Este repositorio es anterior a esa migración, por lo que conviene revisar su manifest.json: si todavía declara "manifest_version": 2, tendrás que migrarlo a MV3 antes de que la extensión cargue en un Chrome actual.

Clonando el repositorio

Primero cloné el repositorio con git clone. Una vez en mi máquina, ejecuté yarn install para instalar todas las dependencias necesarias. Después cargué la extensión en el navegador para ver cómo funcionaba.

Estructura del proyecto

Hay una carpeta pública que contiene el archivo popup.html y el manifest.json. Al cargar la extensión apareció al principio un error que decía "could not load content scripts". Después de investigar, descubrí que había un content script que no era necesario para esta demostración, así que lo eliminé y volví a cargar la extensión.

Proceso de construcción

Para construir la extensión usé el comando yarn build, que genera los archivos necesarios en la carpeta de compilación. Luego cargué estos archivos sin empaquetar en Chrome a través de la página de extensiones (chrome://extensions/). La extensión se cargó correctamente y pude ver un pop up que decía "React Pop up".

Explorando el código

El archivo package.json incluye dependencias como Babel, esbuild, Prettier, React y TypeScript. También hay una dependencia llamada Yorkie, similar a Husky, que se utiliza para ejecutar comandos de pre commit y mantener el código limpio.

El punto de entrada para esbuild incluye archivos como background.ts, content_script.ts, popup.ts e injected.ts. En la carpeta pública, el manifest.json define los recursos accesibles y las URLs a las que se aplica la extensión.

Configuración de esbuild

En el archivo de configuración de esbuild se especifican varias opciones importantes como bundle, minify y sourcemap. Además, se define el entorno de ejecución objetivo y el directorio de salida para los archivos compilados.

Aquí un ejemplo de configuración de esbuild:

const esbuild = require('esbuild');

esbuild.build({
  entryPoints: ['src/background.ts', 'src/content_script.ts', 'src/popup.ts', 'src/injected.ts'],
  bundle: true,
  minify: true,
  sourcemap: process.env.NODE_ENV !== 'production',
  target: ['chrome120'],
  outdir: 'public/build',
  define: {
    'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),
  },
}).catch(() => process.exit(1));

Una nota sobre target: esa opción le dice a esbuild a qué nivel de sintaxis de JavaScript debe reducir tu código (lo que se conoce como down leveling). El repositorio original usaba ['chrome58'], una versión de abril de 2017, lo que obligaba a transformar sintaxis moderna sin necesidad. Como las extensiones corren sobre un Chrome evergreen que se actualiza solo, podemos usar una base mucho más reciente como ['chrome120'], o incluso ['esnext'] si queremos emitir el JavaScript más moderno posible. El resultado es un bundle más limpio y, normalmente, más pequeño.

Nota sobre CommonJS vs ESM. El ejemplo usa require('esbuild'), que sigue siendo una API válida y vigente. Si tu proyecto está configurado como módulo ESM, la forma equivalente es import * as esbuild from 'esbuild'. La llamada esbuild.build({... }) es idéntica en ambos casos.

Conclusión

Aprender a usar esbuild para construir extensiones de Chrome puede ser un proceso enriquecedor y bastante eficiente en comparación con otras herramientas de construcción. Este repositorio en particular ofrece una buena base para empezar y explorar más a fondo las capacidades de esbuild.

Quiero agradecer a Marton Lederer por compartir su trabajo. Si te interesa aprender más sobre cómo construir extensiones de Chrome con esbuild, te recomiendo revisar su repositorio: martonlederer/esbuild react chrome extension.

Ejercicios propuestos

1. Clona el repositorio, revisa su manifest.json y, si todavía es MV2, migra los campos básicos a Manifest V3 (por ejemplo, service_worker en lugar de background.scripts y action en lugar de browser_action).
2. Cambia el target de esbuild de ['chrome120'] a ['esnext'] y compara el tamaño del bundle resultante con yarn build.
3. Añade un nuevo entry point al arreglo entryPoints (por ejemplo un options.ts) y comprueba que aparece compilado en public/build.

Resumen en 3 puntos

1. esbuild es una forma rápida y eficiente de empaquetar extensiones de Chrome, y un repositorio base como el de Marton Lederer es un buen punto de partida.
2. Toda extensión nueva debe usar Manifest V3; verifica el manifest.json del repo antes de cargarlo en un Chrome actual.
3. La opción target controla el down leveling de la sintaxis de JavaScript; con un Chrome evergreen puedes apuntar a una base moderna como ['chrome120'] o ['esnext'].

Eso es todo, espero que este post te sea de utilidad y lo puedas aplicar a algún proyecto que tengas en mente. Déjame un comentario si te sirvió o si tienes alguna duda, y recuerda que si te gustó también puedes compartirlo usando los links a las redes sociales aquí abajo. ¡Buena suerte y a seguir construyendo!