Como resolver o problema de tela branca causado pela falha ao carregar arquivos estáticos ao fazer deploy com AWS S3 + CloudFront

Este é um artigo sobre como resolver, com AWS S3 + CloudFront, o problema de tela branca causado pela falha ao carregar arquivos estáticos durante o deploy. Espero que seja útil para quem está pensando em uma distribuição estável de arquivos estáticos com AWS S3 + CloudFront.

[Contexto do problema]

• Operação de um serviço de frontend baseado em React + Vite
• Após o deploy, ocorria ocasionalmente uma tela branca → os arquivos estáticos não eram carregados
• Erro no console: incompatibilidade de tipo MIME (text/html retornado)

[Análise do problema]

• Incompatibilidade de tipo MIME: retorno de resposta HTML em vez de arquivo estático
• Hipótese de remoção da instância ECS após cancelamento do Github Actions
• Descompasso entre o momento do deploy e o serving dos arquivos estáticos
• O index.html da versão anterior referenciava novos arquivos estáticos, mas esses arquivos haviam sido removidos

[Solução]

• Uso de CloudFront + S3 (decisão final)
• Uso de caminho absoluto do S3 para manter os arquivos estáticos da versão anterior
• Ao fazer o build com Vite, adição de commitHash e timestamp ao nome do arquivo → manutenção da unicidade
• Configuração de S3 Lifecycle para excluir automaticamente arquivos desnecessários
• Integração com CloudFront para servir arquivos estáticos de forma rápida e estável
• Configuração separada para os ambientes Local, Dev e Prod

[Resultado da validação]

• Confirmação de funcionamento normal da abordagem CloudFront + S3
• Aplicação de estratégia de cache: verificação do cache do navegador (Cache-Control, max-age)
• Não há necessidade de invalidação de cache, graças à unicidade dos arquivos
• Possibilidade de deploy estável sem o problema de arquivos estáticos ausentes como antes

[Lições aprendidas]

• Em ambientes de deploy, o gerenciamento de arquivos estáticos pode ter grande impacto na UX.
• Ao validar hipóteses, uma abordagem rápida e simples é importante
• Experiência de otimização do ambiente de deploy com S3 + CloudFront
• Necessidade de diferenciar a estratégia de deploy por ambiente (Local, Dev, Prod)
• É essencial entender o funcionamento do cache do navegador (Cache-Control, from disk cache)

[cnaa97]

Como é rolling, claro que dá problema. Dá para reduzir o tempo de deploy ou separar o deploy e concentrar o tráfego em um lado com uma estratégia blue-green.

Ou então também dá para capturar o erro no React e forçar um reload.