Arquitetura de aplicação web
Leia web-craft primeiro. Carregue apenas as referências que a tarefa precisa; adaptadores de kit e framework apenas para o kit e framework escolhidos.
Mapa
| Tópico | Referência |
|---|---|
| Componentes servidor vs cliente, BFF, limite de env e segredos | references/server-client.md |
| Camada de API, modelo de erros, propriedade de estado, formulários, UI otimista, estado de URL | references/data-forms.md |
| Limites de carregamento, erro e não encontrado, retry, offline, temporização de skeleton | `references/states.md`` |
| i18n: registro, resolução, URL, catálogos, formatação, cabeçalho de backend | references/i18n.md |
| RTL, propriedades lógicas, ícones direcionais, portais | references/rtl.md |
| Autenticação, autorização, XSS, CSRF, cookies, isolamento de cache, dados pessoais | references/auth-security.md |
| Tema: preferência do usuário vs tema aplicado, mudanças no sistema, sem flash | references/theming.md |
| SEO para páginas públicas | references/seo.md |
| GEO: visibilidade em busca de IA e assistentes | references/geo.md |
| Adaptador Next.js App Router | references/fw-next.md |
| Adaptador React + Vite | references/fw-vite.md |
| Adaptador shadcn/ui | references/kit-shadcn.md |
| Adaptador Ant Design | references/kit-antd.md |
| Adaptador Material UI | references/kit-mui.md |
| Trabalhando com um backend node-craft (ou qualquer OpenAPI) | references/node-craft-contract.md |
| Fontes oficiais e datas de revisão | references/sources.md |
Regras que valem em toda parte
- Limites por necessidade. Um componente é um componente cliente porque precisa de interatividade, APIs de navegador ou estado do cliente, não por padrão. Mantenha ilhas interativas pequenas. Nunca importe código exclusivo do servidor, clientes ORM ou segredos para código cliente; uma variável de ambiente pública não é um segredo.
- Uma camada de API. Um cliente fetch, um modelo de erros tipado chaveado por códigos e status estáveis, um comportamento de autenticação. Funcionalidades não constroem seu próprio fetch e retry. Dados do servidor vivem na camada de consulta/cache, estado global do cliente em um store ou contexto pequeno, estado de formulário na ferramenta de formulário, estado de UI local no componente. Uma fonte mock é ativada por configuração para desenvolvimento e testes, nunca editando funcionalidades; respostas não confiáveis são analisadas em tempo de execução.
- Formulários. react-hook-form + Zod a menos que o projeto tenha outra ferramenta.
mode: 'onTouched',reValidateMode: 'onChange', foco e rolagem para o primeiro erro, erros de campo do servidor através desetError, valores mantidos após erros, envio duplo bloqueado. O servidor permanece a autoridade em validação. - Estados têm limites. Limites de carregamento e erro no nível de rota, mais Suspense local onde dados são transmitidos; um widget com falha não apaga a página.
- i18n é arquitetura. Um mecanismo real, um registro de localidade (tag BCP 47, direção, catálogo, nome de exibição), fallback para inglês a menos que escolhido de outra forma, localidade por escopo de requisição no servidor, a mesma localidade inicial no servidor e cliente, catálogos carregados por localidade e namespace, kit e localidade de data mapeados a partir da localidade da aplicação.
- Segurança é no lado do servidor. Autorização no backend. Sanitize qualquer HTML que você renderizar. Sessões de cookies precisam de proteção CSRF. Respostas pessoais nunca vão para um cache compartilhado; respostas dependentes de localidade e usuário variam suas chaves de cache.
- Páginas públicas são encontráveis. Metadados corretos para a localidade renderizados no servidor, canônico por idioma, alternativas hreflang apenas para contrapartes reais, sitemap, dados estruturados que correspondem ao conteúdo visível. GEO começa com isso: conteúdo indexável, citável e uma política explícita de rastreadores de IA. Sem garantias de classificação ou citação.
- Kits são adaptados, não encapsulados. Tema e tokens vêm das decisões de design do produto. Encapsule um componente de kit apenas para comportamento repetido do produto ou para fixar uma API. Não empilhe um segundo sistema de animação sobre as transições próprias de um kit.
Feito
Aplique web-craft → feito, além de: nenhum bundle do cliente contém um segredo ou módulo exclusivo do servidor; duas requisições concorrentes em localidades diferentes ou para usuários diferentes não podem misturar dados; a primeira renderização está no idioma e tema corretos; toda combinação de kit/framework declarada foi realmente verificada.