12k
All articles

Cómo escribir service workers como módulos ES

Convierte un service worker en módulo ES: imports estáticos, código compartido, opciones de compilación, caché de actualizaciones y alternativa para navegadores antiguos.

OpenReplay Team
OpenReplay Team
Cómo escribir service workers como módulos ES

Para ejecutar un service worker como módulo ES, llama a navigator.serviceWorker.register('/sw.js', { type: 'module' }). Sin esa opción, el navegador carga el archivo como un script clásico, por lo que import y export provocan errores de sintaxis.

La mayoría de los equipos llega a este punto por el mismo camino. Toda la aplicación usa ESM y se compila con Vite, pero el service worker sigue siendo un script clásico que llama a importScripts() sobre un archivo de configuración copiado a mano, que termina desincronizándose de la aplicación. Convertir el worker en un módulo resuelve el problema, pero los workers de tipo módulo siguen reglas distintas, y el soporte en navegadores no fue completo hasta Firefox 147. Este artículo cubre el cambio en el registro, cómo compartir código con la página, las reglas que rompen los workers de tipo módulo, el comportamiento de las actualizaciones, la salida de la compilación y una alternativa de respaldo. Para los fundamentos del ciclo de vida, consulta A Practical Guide to Service Workers.

Conclusiones clave

  • Pasar { type: 'module' } a register() convierte el service worker en un módulo ES. El tipo predeterminado es 'classic'.
  • Llamar a importScripts() en un worker de tipo módulo lanza un TypeError, por lo que cada llamada debe sustituirse por un import estático.
  • El import() dinámico y los import maps no funcionan en los service workers, así que cada especificador debe resolverse a una URL real en tiempo de compilación.
  • Los service workers de tipo módulo funcionan en Chrome y Edge 91+, Safari 15+ y Firefox 147+.
  • La configuración predeterminada updateViaCache: 'imports' permite que las comprobaciones de actualización sirvan los módulos importados desde la caché HTTP, así que asigna URL con hash a los módulos compartidos o dales tiempos de caché cortos.

¿Cómo se convierte un service worker en un módulo ES?

Convertir un service worker en un módulo ES requiere dos cambios: pasar la opción type al registrarlo y sustituir importScripts() por import. Según la referencia de register() de MDN, type admite 'classic' (el valor predeterminado) o 'module'.

Esta es la versión clásica:

// config.js (classic)
self.CACHE_NAME = 'app-v3';

// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);

Y esta, la versión como módulo:

// config.js (module)
export const CACHE_NAME = 'app-v3';

// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);

Los scripts de tipo módulo se cargan con CORS, se ejecutan en modo estricto y deben servirse con un tipo MIME de JavaScript como text/javascript, tal como explica la página del constructor Worker() de MDN para los workers de tipo módulo.

Compartir código entre la página y el worker

La principal razón para escribir un service worker como módulo ES es que un mismo módulo puede servir tanto a la página como al worker. Coloca el nombre de la caché y la lista de precaché en un único archivo:

// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];

El worker importa ambos valores y utiliza llamadas estándar a la Cache API:

// sw.js
import { CACHE_NAME, PRECACHE_URLS } from './config.js';

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(PRECACHE_URLS))
  );
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
});

La página importa el mismo archivo:

// main.js, loaded via <script type="module">
import { CACHE_NAME } from './config.js';

console.debug('Expected cache:', CACHE_NAME);
navigator.serviceWorker.register('/sw.js', { type: 'module' });

Ahora basta con cambiar la cadena de versión en un solo lugar para que ambos lados vean el cambio.

Tres reglas que rompen los service workers de tipo módulo

Tres reglas provocan la mayoría de los fallos al convertir un service worker clásico en un módulo ES.

  1. Nada de importScripts(). Los pasos de importScripts() en la especificación HTML lanzan un TypeError cuando el tipo del ámbito global es "module", y la referencia de importScripts() de MDN indica que los workers de tipo módulo deben usar import en su lugar. Si tu worker carga una librería mediante importScripts(), necesitas una versión ESM de esa librería.
  2. Nada de import() dinámico. La página de ServiceWorker de MDN señala que la especificación prohíbe el import() dinámico en los service workers y que llamarlo lanza una excepción. Carga por adelantado, con un import estático, cualquier código que necesites de forma condicional.
  3. Nada de import maps. Los import maps no se aplican dentro de los service workers, y su soporte en workers sigue siendo una propuesta abierta (whatwg/html #8173). Cada especificador debe ser una URL relativa o absoluta. Un nombre sin ruta (bare specifier) como 'idb' no se resolverá como especificador de módulo, por lo que un paso de compilación debe reescribirlo o integrarlo en línea.

Cómo afectan los módulos importados a las actualizaciones del service worker

En un service worker de tipo módulo, los módulos importados forman parte de la comprobación de actualizaciones. Un cambio en un archivo importado estáticamente, como config.js, puede iniciar el flujo de actualización aunque sw.js no haya cambiado, del mismo modo que se gestionan las dependencias de importScripts(), como señala el anuncio de Chrome sobre los service workers de tipo módulo.

La opción updateViaCache determina si esas comprobaciones pueden usar la caché HTTP:

ValorScript principalMódulos importados
'imports' (predeterminado)Siempre desde la redSe permite la caché HTTP
'all'Se permite la caché HTTPSe permite la caché HTTP
'none'Siempre desde la redSiempre desde la red

Con el valor predeterminado, un módulo compartido servido desde una URL sin hash y con un max-age largo puede quedar obsoleto a lo largo de las comprobaciones de actualización. Puedes servir los módulos compartidos desde URL con hash de contenido, asignarles tiempos de caché cortos o registrar el worker con updateViaCache: 'none'. Las grabaciones de sesión (session replays) de usuarios que siguen viendo la interfaz antigua tras un despliegue, o que solicitan recursos con hash que ya no existen, suelen apuntar a este tipo de error de actualización. En Debugging service workers se explica cómo confirmar qué versión del worker tiene el control.

Herramientas de compilación: ESM sin empaquetar o un único archivo

Vite trata un service worker como cualquier otro archivo de salida: debe emitirse como una entrada independiente en una URL estable y sin hash, como /sw.js. Si la URL cambia en cada compilación, el registro apunta cada vez a un script distinto. El directorio public de Vite copia los archivos sin procesarlos, lo que encaja con un worker escrito a mano, pero no resuelve sus imports.

Puedes compilar un service worker de tipo módulo de dos maneras:

  • ESM sin empaquetar. sw.js y sus módulos compartidos se distribuyen como archivos separados con especificadores de URL, y el registro se hace con type: 'module'. Cada import es una petición independiente y queda cubierto por la comprobación de actualizaciones.
  • Un único archivo empaquetado. El bundler integra todo en un solo script, incluidos los paquetes referenciados con especificadores sin ruta. Si esa salida no contiene sentencias import, también se ejecuta como worker clásico, lo que la convierte en tu alternativa de respaldo.

Alternativa para navegadores sin soporte de módulos

Los cuatro motores principales admiten service workers de tipo módulo, según los datos de compatibilidad de MDN en caniuse:

NavegadorPrimera versión con type: 'module'
Chrome91
Edge91
Safari (macOS e iOS)15
Firefox147, según las notas de la versión de Firefox 147

Solo necesitas una compilación clásica para navegadores antiguos: Chrome y Edge 90 o anteriores, Safari 14.1 o anteriores y Firefox 146 o anteriores. No existe ninguna API estándar que detecte el soporte de módulos, como muestra la solicitud de detección de funcionalidad en w3c/ServiceWorker #1582. Un navegador antiguo no rechaza la opción type de entrada: descarga el script, no consigue evaluarlo y register() se rechaza. Puedes capturar ese rechazo:

async function registerSW() {
  if (!('serviceWorker' in navigator)) return;
  try {
    return await navigator.serviceWorker.register('/sw.js', { type: 'module' });
  } catch (err) {
    console.warn('Module service worker failed, falling back to classic:', err);
    return navigator.serviceWorker.register('/sw-classic.js');
  }
}

Esta alternativa basada en try/catch tiene dos costes. Los navegadores antiguos descargan el script de tipo módulo para nada. Además, el catch también oculta errores reales del worker de tipo módulo en los navegadores compatibles, así que registra el error antes de recurrir a la alternativa.

Conclusión

Convertir un service worker en un módulo se reduce a la opción type más tres reglas: solo imports estáticos, nada de importScripts() y nada de especificadores sin ruta. Para empezar, traslada a un único módulo compartido las constantes que tu worker y tu página tienen duplicadas, registra el worker con { type: 'module' } y revisa cómo se almacena en caché ese módulo para que cualquier cambio en él llegue a los usuarios a través de la comprobación de actualizaciones.

Preguntas frecuentes

¿Puedo usar top-level await en un service worker de tipo módulo?

No. El top-level await no está permitido en los service workers porque la evaluación inicial debe completarse de forma síncrona para que listeners como install y fetch se registren a tiempo. Chromium rechaza el registro con un TypeError. Esto también se aplica cuando el await se encuentra en un módulo importado estáticamente, ya que vuelve asíncrono todo el grafo de módulos. Traslada la configuración asíncrona a un handler de install o activate envuelto en event.waitUntil().

¿Cambiar un service worker existente de clásico a módulo en la misma URL desencadena una actualización?

Sí. La especificación de Service Workers trata un cambio de tipo de worker como una actualización, aunque la URL del script y su contenido sean idénticos. Llamar a register('/sw.js', { type: 'module' }) sobre un registro clásico existente instala un nuevo worker, que después pasa por el ciclo de vida normal de espera y activación. Una llamada a register() con la misma URL, el mismo type y el mismo valor de updateViaCache se resuelve sin descargar nada.

¿Puede un service worker de tipo módulo importar módulos desde una CDN u otro origen?

Sí, siempre que el otro origen lo permita. Los imports de módulos se obtienen con CORS, por lo que un módulo de otro origen debe servirse con una cabecera Access-Control-Allow-Origin que autorice tu origen. De lo contrario, el import falla y register() se rechaza. Las llamadas clásicas a importScripts() no lo necesitan porque cargan los scripts en modo no-cors. El script del service worker en sí debe seguir teniendo el mismo origen que la página que lo registra.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — self-hosted, with full data ownership.

Star on GitHub

We use cookies to improve your experience. By using our site, you accept cookies.