Como este site funciona

Este site não usa framework. São arquivos HTML, CSS e JavaScript que rodam direto no navegador, mais um script de build pequeno que só existe para o deploy. Aqui estão as peças e como elas se encaixam.

O código-fonte roda sem build

Em desenvolvimento, npm run dev sobe um servidor em Node que monta cada página a cada requisição. Não tem bundler nem cache: salvo o arquivo e recarrego a página. Os scripts são clássicos, carregados com defer numa ordem fixa, e os de dados (config.js, dev-content.js, i18n.js) só declaram uma constante global.

Essa escolha tem um efeito útil: o mesmo arquivo de dados serve ao navegador e ao Node. O build lê o dev-content.js com node:vm e escreve a página Dev em HTML simples, para buscadores e prévias de link que não executam JavaScript. Quando o script carrega, ele troca essa versão pela interativa.

O build só otimiza

O build.mjs faz poucas coisas:

• junta os arquivos CSS num <style> inline e minificado, para nada bloquear a renderização;
• minifica cada script com esbuild e põe um hash no nome, o que permite cache imutável de um ano;
• minifica o HTML;
• monta a versão em inglês a partir do mesmo index.html;
• transforma as notas em Markdown, como esta, em páginas;
• calcula a Content Security Policy.

Uma CSP sem unsafe-inline

Depois da minificação, o build calcula o SHA-256 de cada <script> e <style> inline e põe esses hashes numa CSP dentro de uma tag <meta>. Qualquer outro script inline é bloqueado pelo navegador.

O preço é uma regra que precisa ser lembrada: nada de atributo style no HTML nem em strings de innerHTML. Quando preciso de uma variável CSS por elemento, uso el.style.setProperty() no JavaScript, que a CSP permite.

Dois idiomas, um HTML

A versão em inglês não é outro arquivo. Uma lista de pares, com o texto em português e o texto em inglês, é aplicada ao index.html no build. Se um trecho da lista não for encontrado, o build falha em vez de publicar uma página meio traduzida.

Testes que pegam o que importa

Os testes são de fumaça, com Playwright, contra o build de produção, num desktop e num celular emulado. Eles conferem que as páginas abrem nos dois idiomas, que o terminal responde, que o HTML sem JavaScript tem o conteúdo e que nenhum erro aparece no console. Esse último cobre a CSP: se algo for bloqueado, o teste falha.

No CI, o Lighthouse exige nota mínima de 90 em performance e boas práticas, e de 95 em acessibilidade e SEO.

O que fica de lição

Começar sem framework e só acrescentar ferramenta quando um problema aparece. Fazer o build falhar alto quando uma suposição quebra. E testar o artefato que vai para produção, não o ambiente de desenvolvimento.