Guía de Mellowtel sin Bundlers para Extensiones de Navegador

Esta guía explica cómo integrar Mellowtel en tu extensión de navegador sin usar bundlers como Webpack o Vite. En su lugar, usarás un único archivo preempaquetado que funciona tanto en scripts de contenido como en service workers.

Configuración del Proyecto

Comienza con una estructura básica de extensión de navegador:

tu-extension/
├── icons/
├── popup/
│   ├── popup.html
│   └── popup.js
├── background.js           # Tu service worker
├── content_script.js
├── manifest.json
└── mellowtel.js           # Se añadirá en el siguiente paso

Obtener el Bundle de Mellowtel

Tienes dos opciones para obtener el archivo mellowtel.js para tu extensión:

Opción 1: Usar Archivo Preempaquetado

La forma más fácil de comenzar es usar el archivo preempaquetado mellowtel.js del repositorio mellowtel-bundled.

Ve al repositorio mellowtel-bundled
Descarga el archivo mellowtel.js
Cópialo en el directorio de tu extensión

Opción 2: Generar tu Propio Bundle

Si prefieres generar el bundle tú mismo, sigue estos pasos:

Crear un Directorio Temporal para el Bundling

Crea un directorio temporal para instalar Mellowtel y generar el bundle:

mkdir mellowtel-bundling
cd mellowtel-bundling
npm init -y
npm install mellowtel

Esto crea una carpeta separada con el paquete Mellowtel que usarás solo para el bundling.

Empaquetar Mellowtel con esbuild

Desde dentro del directorio mellowtel-bundling, crea un único bundle que funcione tanto en service workers como en scripts de contenido:

npx esbuild node_modules/mellowtel/dist/index.js --bundle --format=iife --global-name=Mellowtel --footer:js="globalThis.Mellowtel = Mellowtel.default" --platform=browser --outfile=mellowtel.js --minify --legal-comments=none

Este comando:

Toma el código fuente de Mellowtel desde node_modules/mellowtel/dist/index.js
Empaqueta todas las dependencias en un solo archivo
Usa el formato IIFE con un nombre global para compatibilidad universal
Añade un pie de página para hacer que la exportación por defecto esté disponible globalmente
Optimiza para el entorno del navegador y minimiza la salida
Crea mellowtel.js en el directorio de bundling

Copiar el Bundle a tu Extensión

Después de ejecutar el comando esbuild, copia el archivo generado a tu directorio de extensión:

cp mellowtel.js ../tu-extension/

Ahora puedes eliminar el directorio temporal de bundling ya que solo necesitabas el archivo de salida:

cd ..
rm -rf mellowtel-bundling

Tu carpeta de extensión ahora contiene el archivo Mellowtel empaquetado listo para usar.

Configurar tu Manifiesto (Ambas Opciones)

Independientemente de la opción que hayas elegido, configura tu manifest.json para incluir el bundle de Mellowtel en los scripts de contenido:

{
  "manifest_version": 3,
  "name": "Nombre de tu Extensión",
  "version": "1.0",
  "background": {
    "service_worker": "background.js",
    "type": "module"
  },
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["mellowtel.js", "content_script.js"]
    }
  ],
  "permissions": [
    "storage",
    "declarativeNetRequestWithHostAccess"
  ],
  "host_permissions": [
    "\u003Call_urls\u003E"
  ]
}

Importante:

El campo "type": "module" habilita las importaciones de módulos ES en tu service worker.
En el array de scripts de contenido, mellowtel.js debe cargarse antes que content_script.js para que la variable global Mellowtel esté disponible cuando se ejecute tu script de contenido.

Usar Mellowtel en tu Extensión

Para tu service worker (background.js), importa el archivo empaquetado:

// background.js
import './mellowtel.js';

(async () => {
    const mellowtel = new Mellowtel("<configuration_key>"); // Reemplaza con tu clave de configuración
    await mellowtel.initBackground();
})();

Para scripts de contenido, Mellowtel está disponible como una variable global (no se necesita importación, ya que se carga a través del manifiesto):

// content_script.js
// Mellowtel está disponible como una variable global desde mellowtel.js

(async () => {
  const mellowtel = new Mellowtel("<configuration_key>"); // Reemplaza con tu clave de configuración
  await mellowtel.initContentScript();
})();

Probar tu Extensión

Para probar tu extensión:

Ve a chrome://extensions/ en Chrome (o equivalente en otros navegadores)
Habilita el “Modo desarrollador”
Haz clic en “Cargar sin empaquetar” y selecciona tu carpeta de extensión

Este enfoque te brinda los beneficios de usar Mellowtel sin la complejidad de configurar un sistema de construcción completo como Webpack o Vite.

​Configuración del Proyecto

​Obtener el Bundle de Mellowtel

​Opción 1: Usar Archivo Preempaquetado

​Opción 2: Generar tu Propio Bundle

​Crear un Directorio Temporal para el Bundling

​Empaquetar Mellowtel con esbuild

​Copiar el Bundle a tu Extensión

​Configurar tu Manifiesto (Ambas Opciones)

​Usar Mellowtel en tu Extensión

​Probar tu Extensión