Escrevendo service workers como módulos ES
Converta um service worker em módulo ES: imports estáticos, código compartilhado, opções de build, cache de atualizações e alternativa para navegadores antigos.
Para executar um service worker como módulo ES, chame navigator.serviceWorker.register('/sw.js', { type: 'module' }). Sem essa opção, o navegador carrega o arquivo como script clássico, e import e export geram erros de sintaxe.
A maioria das equipes chega a este ponto pelo mesmo caminho. A aplicação inteira é ESM, construída com Vite, e o service worker continua sendo um script clássico que chama importScripts() em um arquivo de configuração copiado manualmente, que acaba ficando dessincronizado da aplicação. Converter o worker em módulo resolve isso, mas workers de módulo seguem regras diferentes, e o suporte dos navegadores só ficou completo com o Firefox 147. Este artigo aborda a mudança no registro, o compartilhamento de código com a página, as regras que quebram workers de módulo, como as atualizações se comportam, a saída do build e um fallback. Para os fundamentos do ciclo de vida, consulte A Practical Guide to Service Workers.
Principais pontos
- Passar
{ type: 'module' }pararegister()transforma o service worker em um módulo ES. O tipo padrão é'classic'. - Chamar
importScripts()em um worker de módulo lança umTypeError, então toda chamada precisa virar umimportestático. import()dinâmico e import maps não funcionam em service workers, então todo especificador precisa ser resolvido para uma URL real em tempo de build.- Service workers de módulo funcionam no Chrome e no Edge 91+, no Safari 15+ e no Firefox 147+.
- A configuração padrão
updateViaCache: 'imports'permite que as verificações de atualização sirvam os módulos importados a partir do cache HTTP, então use URLs com hash ou tempos de cache curtos para os módulos compartilhados.
Como converter um service worker em módulo ES?
Converter um service worker em módulo ES exige duas mudanças: passar a opção type no registro e trocar importScripts() por import. Segundo a referência de register() no MDN, type aceita 'classic' (o padrão) ou 'module'.
Esta é a versão clássica:
// config.js (classic)
self.CACHE_NAME = 'app-v3';
// sw.js (classic)
importScripts('/config.js');
console.log(self.CACHE_NAME);
E esta é a versão em módulo:
// config.js (module)
export const CACHE_NAME = 'app-v3';
// sw.js (module)
import { CACHE_NAME } from './config.js';
console.log(CACHE_NAME);
Scripts de módulo são carregados com CORS, executam em strict mode e precisam ser servidos com um MIME type de JavaScript, como text/javascript, conforme explica a página do construtor Worker() no MDN para workers de módulo.
Compartilhando código entre a página e o worker
O principal motivo para escrever um service worker como módulo ES é que um único módulo pode atender tanto a página quanto o worker. Coloque o nome do cache e a lista de precache em um único arquivo:
// config.js
export const CACHE_NAME = 'app-v3';
export const PRECACHE_URLS = ['/', '/index.html', '/offline.html'];
O worker importa os dois valores e usa chamadas padrão da 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)))
)
);
});
A página importa o mesmo arquivo:
// 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' });
Agora você atualiza a string de versão em um único lugar, e os dois lados enxergam a mudança.
Três regras que quebram service workers de módulo
Três regras causam a maioria das falhas ao converter um service worker clássico em módulo ES.
- Sem
importScripts(). Os passos deimportScripts()na especificação HTML lançam umTypeErrorquando o tipo do escopo global é"module", e a referência deimportScripts()no MDN orienta workers de módulo a usarimportno lugar. Se o seu worker carrega uma biblioteca viaimportScripts(), você precisa de uma versão ESM dessa biblioteca. - Sem
import()dinâmico. A páginaServiceWorkerno MDN informa que a especificação proíbeimport()dinâmico em service workers e que chamá-lo lança uma exceção. Carregue antecipadamente, com um import estático, qualquer código que você precisaria carregar condicionalmente. - Sem import maps. Import maps não se aplicam dentro de service workers, e o suporte a eles em workers ainda é uma proposta em aberto (whatwg/html #8173). Todo especificador precisa ser uma URL relativa ou absoluta. Um nome simples (bare specifier) como
'idb'não será resolvido como especificador de módulo, então uma etapa de build precisa reescrevê-lo ou incorporá-lo (inline).
Como os módulos importados afetam as atualizações do service worker
Em um service worker de módulo, os módulos importados fazem parte da verificação de atualização. Uma alteração em um arquivo importado estaticamente, como config.js, pode iniciar o fluxo de atualização mesmo quando sw.js não mudou, da mesma forma como as dependências de importScripts() são tratadas, conforme observa o anúncio do Chrome sobre service workers de módulo.
A opção updateViaCache define se essas verificações podem usar o cache HTTP:
| Valor | Script principal | Módulos importados |
|---|---|---|
'imports' (padrão) | Sempre da rede | Cache HTTP permitido |
'all' | Cache HTTP permitido | Cache HTTP permitido |
'none' | Sempre da rede | Sempre da rede |
Com o padrão, um módulo compartilhado servido a partir de uma URL sem hash e com um max-age longo pode continuar desatualizado ao longo das verificações de atualização. Você pode servir módulos compartilhados a partir de URLs com hash de conteúdo, definir tempos de cache curtos para eles ou registrar com updateViaCache: 'none'. Replays de sessão de usuários que continuam vendo a interface antiga após um deploy, ou que fazem requisições para assets com hash que não existem mais, costumam indicar esse tipo de bug de atualização. Debugging service workers mostra como confirmar qual versão do worker está no controle.
Ferramentas de build: ESM sem bundle ou arquivo único
O Vite trata um service worker como qualquer outro arquivo de saída: ele precisa ser gerado como um entry próprio, em uma URL estável e sem hash, como /sw.js. Se a URL mudar a cada build, o registro apontará para um script diferente a cada vez. O diretório public do Vite copia arquivos sem processá-los, o que atende a um worker escrito à mão, mas não resolve os imports dele.
Você pode gerar um service worker de módulo de duas formas:
- ESM sem bundle. O
sw.jse seus módulos compartilhados são distribuídos como arquivos separados com especificadores de URL, e você registra comtype: 'module'. Cada import é um fetch separado e entra na verificação de atualização. - Um único arquivo com bundle. O bundler incorpora tudo, incluindo pacotes referenciados por bare specifiers, em um único script. Se essa saída não contiver nenhuma instrução
import, ela também roda como worker clássico, o que a torna seu fallback.
Fallback para navegadores sem suporte a módulos
Os quatro principais engines suportam service workers de módulo, segundo os dados do MDN browser-compat-data no caniuse:
| Navegador | Primeira versão com type: 'module' |
|---|---|
| Chrome | 91 |
| Edge | 91 |
| Safari (macOS e iOS) | 15 |
| Firefox | 147, conforme as notas de versão do Firefox 147 |
Você só precisa de um build clássico para navegadores mais antigos: Chrome e Edge 90 e anteriores, Safari 14.1 e anteriores, e Firefox 146 e anteriores. Nenhuma API padrão detecta suporte a módulos, como mostra a solicitação de detecção de recurso em w3c/ServiceWorker #1582. Um navegador antigo não rejeita a opção type logo de início. Ele baixa o script, falha ao avaliá-lo, e register() é rejeitada. Você pode capturar essa rejeição:
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');
}
}
Esse fallback com try/catch tem dois custos. Navegadores antigos baixam o script de módulo à toa. E o catch também esconde erros reais do worker de módulo em navegadores com suporte, então registre o erro em log antes de recorrer ao fallback.
Conclusão
Converter um service worker em módulo se resume à opção type mais três regras: apenas imports estáticos, nada de importScripts() e nada de bare specifiers. Para começar, mova as constantes duplicadas entre o worker e a página para um único módulo compartilhado, registre com { type: 'module' } e verifique como esse módulo é armazenado em cache, para que uma alteração nele chegue aos usuários pela verificação de atualização.
Perguntas frequentes
Posso usar top-level await em um service worker de módulo?
Não. Top-level await não é permitido em service workers, porque a avaliação inicial precisa terminar de forma síncrona para que listeners como install e fetch sejam registrados a tempo. O Chromium rejeita o registro com um TypeError. Isso também vale quando o await está em um módulo importado estaticamente, porque ele torna todo o grafo de módulos assíncrono. Mova a configuração assíncrona para um handler de install ou activate envolvido em event.waitUntil().
Converter um service worker existente de clássico para módulo na mesma URL dispara uma atualização?
Sim. A especificação de Service Workers trata uma mudança no tipo do worker como uma atualização, mesmo quando a URL do script e seu conteúdo são idênticos. Chamar register('/sw.js', { type: 'module' }) sobre um registro clássico existente instala um novo worker, que então passa pelo ciclo de vida normal de espera e ativação. Uma chamada a register() com a mesma URL, o mesmo type e o mesmo valor de updateViaCache é resolvida sem buscar nada.
Um service worker de módulo pode importar módulos de uma CDN ou de outra origem?
Sim, se a outra origem permitir. Imports de módulos são buscados com CORS, então um módulo de outra origem precisa ser servido com um cabeçalho Access-Control-Allow-Origin que permita a sua origem. Caso contrário, o import falha e register() é rejeitada. Chamadas clássicas a importScripts() não precisam disso, porque carregam scripts no modo no-cors. O script do service worker em si ainda precisa ter a mesma origem da página que o registra.