0

immutable + ES modules: o import sem versão que deixa seu JS velho por até 1 ano

Você troca o ?v= da página, faz o deploy e acha que todo mundo recebeu o código novo. Se o seu JS usa import com caminho relativo e o servidor manda immutable, quem já visitou o site pode continuar rodando o módulo antigo por até um ano.

Quando fui contar, eram 9 módulos importados por URL sem versão. Um deles tinha 60 KB com toda a lógica de varredura do site.

Eu criei o MyIPScan, um site de ferramentas de IP e privacidade. Se esse módulo mudasse, quem já tinha visitado o site podia continuar rodando a versão antiga, e o código que mais importa seria justamente o que não atualiza.

Por que isso é grave

Os assets do site são servidos com este cabeçalho:

Cache-Control: max-age=31536000, immutable

max-age=31536000 são 365 dias. E o immutable, segundo a RFC 8246, diz que o servidor não vai alterar a representação durante o prazo de validade (freshness lifetime), e que o cliente não deve nem mandar requisição condicional nesse período, inclusive num recarregamento normal. Só o recarregamento forçado do usuário (Ctrl+Shift+R) passa por cima.

A MDN descreve essa combinação no padrão de cache busting: conteúdo novo precisa ter URL nova. A regra é ótima. O problema é quando uma parte das URLs não muda.

O palpite errado

A suposição natural é que, ao trocar o token no <script>, o navegador baixa o entry point novo e, junto, os módulos dele. Baixa o entry point novo. Os módulos, não.

A causa exata

O HTML carrega o entry point com versão (nomes e números de exemplo):

<script type="module" src="/js/app.js?v=8"></script>

E dentro do app.js:

// app.js
import { runScan } from './scan.js';

A MDN sobre módulos explica que, no navegador, o especificador é resolvido como URL relativa à URL do módulo atual, como o href de um <a>. E a resolução de URL relativa (RFC 3986, seção 5.2.2) não herda a query string de quem importa. Então ./scan.js, a partir de /js/app.js?v=8, vira simplesmente:

/js/scan.js

Sem ?v=. Sempre a mesma URL, deploy após deploy.

O cache HTTP do navegador guarda a resposta pela URL. Mesma URL, mesma resposta guardada. Com immutable e um ano de max-age, o navegador nem pergunta ao servidor se mudou.

A correção: subir a versão em cascata

Primeiro passo: versionar o próprio import.

// antes
import { runScan } from './scan.js';

// depois
import { runScan } from './scan.js?v=9';

O detalhe que faltava: mudar o import muda o conteúdo do app.js. Mas o app.js também é immutable. Se a URL dele continuar /js/app.js?v=8, o visitante recorrente nunca vai ver o import novo. Então o token do importador também precisa subir, e o do importador dele, até chegar no HTML.

scan.js        ?v=9   (conteúdo mudou)
  ↑ importado por
app.js         ?v=9   (o import mudou, então o arquivo mudou)
  ↑ carregado por
index.html            (<script src="/js/app.js?v=9">)

No meu caso, versionar os 9 módulos arrastou junto 5 entry points. Cada módulo alterado obriga a subir o token de todos os arquivos que o importam, direta ou indiretamente, até o HTML.

Como conferir no seu projeto

  • procure imports relativos sem versão, por exemplo: grep -rnE "(from|import\()\s*['\"]\./[^'\"?]+['\"]" js/;
  • no DevTools > Network, com o cache ativo, recarregue depois do deploy: módulo com URL antiga vindo de (disk cache) é módulo congelado.

Alternativa: import map

Se a cascata manual cansar, um import map desacopla o nome do módulo da URL real. O código importa um nome estável e o mapeamento fica no HTML:

<script type="importmap">
  {
    "imports": {
      "scan": "/js/scan.js?v=9"
    }
  }
</script>
import { runScan } from 'scan';

Mudou o scan.js? Você troca uma linha no HTML, e o app.js não precisa mudar. A cascata para no import map. O custo é manter esse mapa em dia, o que um passo de build com hash no nome do arquivo resolve melhor do que edição manual.

A regra que fica

Com immutable, cada arquivo precisa da própria versão na URL, e todo arquivo que referencia uma URL versionada também passa a ser versionado. O token do HTML não desce pelos import. Se um módulo é importado por caminho fixo, ele está congelado no navegador de quem já visitou, pelo tempo do max-age.

Antes de colocar immutable num diretório de ES modules, rode uma busca por imports relativos sem versão. Se aparecer algum, é ali que o seu próximo deploy vai falhar em silêncio.

Carregando publicação patrocinada...