Arquitectura de aplicaciones web
Primero lee web-craft. Carga solo las referencias que la tarea necesite; los adaptadores de kit y framework solo para el kit y framework elegidos.
Mapa
| Tema | Referencia |
|---|---|
| Componentes servidor vs. cliente, BFF, límite de entorno y secretos | references/server-client.md |
| Capa de API, modelo de errores, propiedad del estado, formularios, UI optimista, estado de URL | references/data-forms.md |
| Límites de carga, error y no encontrado, reintento, sin conexión, temporización de esqueleto | references/states.md |
| i18n: registro, resolución, URL, catálogos, formato, cabecera de backend | references/i18n.md |
| RTL, propiedades lógicas, iconos direccionales, portales | references/rtl.md |
| Autenticación, autorización, XSS, CSRF, cookies, aislamiento de caché, datos personales | references/auth-security.md |
| Tema: preferencia del usuario vs. tema aplicado, cambios del sistema, sin destello | references/theming.md |
| SEO para páginas públicas | references/seo.md |
| GEO: visibilidad en búsqueda AI y asistentes | 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 |
| Trabajar con un backend node-craft (o cualquier OpenAPI) | references/node-craft-contract.md |
| Fuentes oficiales y fechas de revisión | references/sources.md |
Reglas que aplican en todas partes
- Límites por necesidad. Un componente es un componente cliente porque necesita interactividad, APIs del navegador o estado del cliente, no por defecto. Mantén las islas interactivas pequeñas. Nunca importes código solo de servidor, clientes ORM o secretos en código cliente; una variable de entorno pública no es un secreto.
- Una capa de API. Un cliente de fetch, un modelo de errores tipado con códigos estables y estado, un comportamiento de autenticación. Las funcionalidades no construyen su propio fetch y reintento. Los datos del servidor viven en la capa de consulta/caché, el estado global del cliente en un store pequeño o contexto, el estado del formulario en la herramienta de formularios, el estado local de la UI en el componente. Una fuente mock se activa mediante configuración para desarrollo y pruebas, nunca editando funcionalidades; las respuestas no confiables se analizan en tiempo de ejecución.
- Formularios. react-hook-form + Zod a menos que el proyecto tenga otra herramienta.
mode: 'onTouched',reValidateMode: 'onChange', enfoque y desplazamiento al primer error, errores de campo del servidor mediantesetError, valores mantenidos después de errores, doble envío bloqueado. El servidor sigue siendo la autoridad en validación. - Los estados tienen límites. Límites de carga y error a nivel de ruta más Suspense local donde los datos fluyen; un widget que falla no deja la página en blanco.
- i18n es arquitectura. Un motor real, un registro de locales (etiqueta BCP 47, dirección, catálogo, nombre visible), fallback a inglés a menos que se elija otra cosa, local por solicitud en el servidor, el mismo local inicial en servidor y cliente, catálogos cargados por local y espacio de nombres, kit y locale de fecha mapeados desde el local de la aplicación.
- La seguridad es del lado del servidor. Autorización en el backend. Sanitiza cualquier HTML que renderices. Las sesiones con cookies necesitan protección CSRF. Las respuestas personales nunca entran en una caché compartida; las respuestas que dependen del local y del usuario varían sus claves de caché.
- Las páginas públicas son encontrables. Metadatos correctos según el local renderizados en el servidor, canonical por idioma, alternativas hreflang solo para contrapartes reales, sitemap, datos estructurados que coincidan con el contenido visible. GEO comienza con eso: contenido indexable y citable, y una política explícita para rastreadores de IA. Sin garantías de ranking o citación.
- Los kits se adaptan, no se envuelven. El tema y los tokens provienen de las decisiones de diseño del producto. Envuelve un componente del kit solo para comportamiento repetido del producto o para fijar una API. No apiles un segundo sistema de animación sobre las transiciones propias del kit.
Hecho
Aplica web-craft → hecho, más: ningún bundle del cliente contiene un secreto o módulo solo de servidor; dos solicitudes concurrentes en diferentes locales o de diferentes usuarios no pueden mezclar datos; el primer renderizado está en el idioma y tema correctos; cada combinación kit/framework indicada fue realmente verificada.