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.