12k
All articles

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.

OpenReplay Team
OpenReplay Team
Escrevendo service workers como módulos ES

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' } para register() transforma o service worker em um módulo ES. O tipo padrão é 'classic'.
  • Chamar importScripts() em um worker de módulo lança um TypeError, então toda chamada precisa virar um import está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.

  1. Sem importScripts(). Os passos de importScripts() na especificação HTML lançam um TypeError quando o tipo do escopo global é "module", e a referência de importScripts() no MDN orienta workers de módulo a usar import no lugar. Se o seu worker carrega uma biblioteca via importScripts(), você precisa de uma versão ESM dessa biblioteca.
  2. Sem import() dinâmico. A página ServiceWorker no MDN informa que a especificação proíbe import() 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.
  3. 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:

ValorScript principalMódulos importados
'imports' (padrão)Sempre da redeCache HTTP permitido
'all'Cache HTTP permitidoCache HTTP permitido
'none'Sempre da redeSempre 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.js e seus módulos compartilhados são distribuídos como arquivos separados com especificadores de URL, e você registra com type: '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:

NavegadorPrimeira versão com type: 'module'
Chrome91
Edge91
Safari (macOS e iOS)15
Firefox147, 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.

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.