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.
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' }aregister()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 unTypeError, por lo que cada llamada debe sustituirse por unimportestá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.
- Nada de
importScripts(). Los pasos deimportScripts()en la especificación HTML lanzan unTypeErrorcuando el tipo del ámbito global es"module", y la referencia deimportScripts()de MDN indica que los workers de tipo módulo deben usarimporten su lugar. Si tu worker carga una librería medianteimportScripts(), necesitas una versión ESM de esa librería. - Nada de
import()dinámico. La página deServiceWorkerde MDN señala que la especificación prohíbe elimport()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. - 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:
| Valor | Script principal | Módulos importados |
|---|---|---|
'imports' (predeterminado) | Siempre desde la red | Se permite la caché HTTP |
'all' | Se permite la caché HTTP | Se permite la caché HTTP |
'none' | Siempre desde la red | Siempre 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.jsy sus módulos compartidos se distribuyen como archivos separados con especificadores de URL, y el registro se hace contype: '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:
| Navegador | Primera versión con type: 'module' |
|---|---|
| Chrome | 91 |
| Edge | 91 |
| Safari (macOS e iOS) | 15 |
| Firefox | 147, 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.