Regras de Arquitetura do Astro v6 (Modo Estrito)

# Regras de Arquitetura Astro v6 (Modo Estrito) ## 1. Filosofia Central - Siga o princípio "HTML-first / zero JavaScript por padrão" do Astro: - Tudo é HTML estático, a menos que interatividade seja explicitamente necessária. - JavaScript é um custo, adicione apenas quando criar valor real para o usuário. - Sempre pense em "Arquitetura de Ilhas": - A página é HTML estático - Partes interativas são ilhas isoladas - Nunca trate a página inteira como um aplicativo - Antes de escrever qualquer JavaScript, sempre pergunte: "Isso pode ser resolvido com HTML + CSS ou lógica no servidor?" ## 2. Modelo de Componentes - Use componentes `.astro` para: - Layout - Composição - UI estática - Busca de dados - Lógica no servidor (frontmatter) - Componentes `.astro`: - Executam em tempo de build ou no servidor - NÃO enviam JavaScript por padrão - Devem permanecer agnósticos a frameworks - NUNCA use hooks de React/Vue/Svelte dentro de `.astro` ## 3. Ilhas (Componentes Interativos) - Use apenas componentes de frameworks (React, Vue, Svelte, etc.) para interatividade. - Trate cada componente interativo como uma ilha isolada: - Independente - Autocontido - Escopo mínimo - NUNCA: - Hidrate páginas ou layouts inteiros - Envolva grandes árvores em uma única ilha - Crie muitas ilhas pequenas em loops desnecessariamente - Prefira: - Renderização de listas estáticas - Hidrate apenas a unidade interativa mínima ## 4. Estratégia de Hidratação (Crítico) - Sempre defina explicitamente a hidratação usando diretivas `client:*`. - Escolha a prioridade MAIS BAIXA possível: - `client:load` -> Apenas para interatividade crítica acima da dobra - `client:idle` -> Para UI secundária após o carregamento da página - `client:visible` -> Para componentes abaixo da dobra ou pesados - `client:media` -> Para UI responsiva / condicional - `client:only` -> SOMENTE quando SSR quebrar (window, localStorage, etc.) - Regra padrão: - Nunca use `client:load` por padrão - Prefira `client:visible` ou `client:idle` - Hidratação é um orçamento de performance: - Cada ilha adiciona JavaScript - Mantenha o total de JavaScript mínimo ## 5. Lógica no Servidor vs. no Cliente - Prefira lógica no servidor (dentro do frontmatter `.astro`) para: - Busca de dados - Transformações - Filtragem / ordenação - Valores derivados - Use apenas estado no cliente quando: - A interação do usuário exigir - Atualizações em tempo real forem necessárias - Evite: - Duplicar lógica no cliente - Mover lógica do servidor para ilhas ## 6. Gerenciamento de Estado - Evite estado no cliente, a menos que estritamente necessário. - Se necessário: - Escopo do estado dentro da ilha apenas - NÃO crie estado global de aplicativo, a menos que seja exigido - Para estado entre ilhas: - Use stores compartilhados leves (ex.: nano stores) - Evite sistemas pesados de estado global por padrão ## 7. Restrições de Performance (Regras Rígidas) - Minimize JavaScript enviado ao cliente: - Astro carrega JS apenas para componentes hidratados - Prefira: - Renderização estática - Hidratação parcial - Hidratação preguiçosa - Evite: - Hidratar listas grandes - Ilhas repetidas em loops - Uso excessivo de `client:load` - Cada ilha: - Tem seu próprio bundle - Carrega de forma independente - Deve permanecer pequena e focada ## 8. Estrutura de Arquivos e Projeto - `/pages` - Pontos de entrada (SSG/SSR), sem lógica no cliente - `/components` - UI compartilhada, ilhas vivem aqui - `/layouts` - Apenas wrappers estáticos - `/content` - Dados de Markdown / CMS - Mantenha arquivos `.astro` focados em composição, não em comportamento ## 9. Anti-Padrões (Estritamente Proibidos) - Usar hooks em `.astro` - Transformar Astro em arquitetura SPA - Hidratar layout/página inteiro - Usar `client:load` em todo lugar - Mapear listas em componentes hidratados - Usar JS no cliente para problemas estáticos - Substituir lógica do servidor por lógica no cliente ## 10. Padrões Preferidos - Renderização estática em primeiro lugar - Ilhas mínimas e isoladas - Hidratação preguiçosa (`visible`, `idle`) - Computação no servidor - HTML + CSS antes de JS - Melhoria progressiva ## 11. Estrutura de Decisão (MUITO IMPORTANTE) Para cada funcionalidade: 1. Isso pode ser HTML estático? -> SIM -> Use `.astro` 2. Requer interação? -> NÃO -> Permaneça estático 3. Requer JS? -> SIM -> Crie uma ilha 4. Quando deve carregar? -> Escolha a prioridade MAIS BAIXA `client:*` ## 12. Modelo Mental (Inegociável) - Astro NÃO é: - Next.js - Framework SPA - Sistema React-first - Astro É: - Renderizador estático em primeiro lugar - Sistema de hidratação parcial - Arquitetura performance-first - Pense: "Envie HTML + salpique JS"