Architecture d'application web
Lisez web-craft d'abord. Ne chargez que les références nécessaires à la tâche ; les adaptateurs de kit et de framework uniquement pour le kit et le framework choisis.
Plan
| Sujet | Référence |
|---|---|
| Composants serveur vs client, BFF, limite des secrets et variables d'environnement | references/server-client.md |
| Couche API, modèle d'erreur, propriété d'état, formulaires, UI optimiste, état d'URL | references/data-forms.md |
| Limites de chargement, d'erreur et de non trouvé, réessai, hors ligne, timing des squelettes | references/states.md |
| i18n : registre, résolution, URL, catalogues, formatage, en-tête backend | references/i18n.md |
| RTL, propriétés logiques, icônes directionnelles, portails | references/rtl.md |
| Authentification, autorisation, XSS, CSRF, cookies, isolation du cache, données personnelles | references/auth-security.md |
| Thème : préférence utilisateur vs thème appliqué, changements système, pas de flash | references/theming.md |
| SEO pour les pages publiques | references/seo.md |
| GEO : visibilité dans la recherche AI et les assistants | references/geo.md |
| Adaptateur Next.js App Router | references/fw-next.md |
| Adaptateur React + Vite | references/fw-vite.md |
| Adaptateur shadcn/ui | references/kit-shadcn.md |
| Adaptateur Ant Design | references/kit-antd.md |
| Adaptateur Material UI | references/kit-mui.md |
| Travailler avec un backend node-craft (ou tout OpenAPI) | references/node-craft-contract.md |
| Sources officielles et dates de révision | references/sources.md |
Règles qui s'appliquent partout
- Limites selon le besoin. Un composant est un composant client parce qu'il nécessite de l'interactivité, des API navigateur ou un état client, pas par défaut. Gardez les îlots interactifs petits. N'importez jamais de code serveur uniquement, de clients ORM ou de secrets dans le code client ; une variable d'environnement publique n'est pas un secret.
- Une seule couche API. Un seul client fetch, un seul modèle d'erreur typé indexé par des codes stables et un statut, un seul comportement d'authentification. Les fonctionnalités ne construisent pas leur propre fetch et réessai. Les données serveur vivent dans la couche de requête/cache, l'état global client dans un petit store ou contexte, l'état de formulaire dans l'outil de formulaire, l'état UI local dans le composant. Une source mock est activée par configuration pour le développement et les tests, jamais en modifiant les fonctionnalités ; les réponses non fiables sont analysées à l'exécution.
- Formulaires. react-hook-form + Zod sauf si le projet dispose d'un autre outil.
mode: 'onTouched',reValidateMode: 'onChange', focus et défilement sur la première erreur, erreurs de champ serveur viasetError, valeurs conservées après les erreurs, double soumission bloquée. Le serveur reste l'autorité en matière de validation. - Les états ont des limites. Limites de chargement et d'erreur au niveau de la route, plus Suspense local là où les données arrivent en continu ; un widget défaillant ne vide pas la page.
- L'i18n est une architecture. Un moteur réel, un registre de locales (balise BCP 47, direction, catalogue, nom d'affichage), repli sur l'anglais sauf choix contraire, locale par requête sur le serveur, même locale initiale sur le serveur et le client, catalogues chargés par locale et espace de noms, kit et locale de date mappés depuis la locale de l'application.
- La sécurité est côté serveur. Autorisation dans le backend. Sanitisez tout HTML que vous rendez. Les sessions par cookie nécessitent une protection CSRF. Les réponses personnelles ne vont jamais dans un cache partagé ; les réponses dépendantes de la locale et de l'utilisateur varient leurs clés de cache.
- Les pages publiques sont trouvables. Métadonnées correctes pour la locale rendues sur le serveur, canonique par langue, alternatives hreflang uniquement pour les vraies contreparties, plan du site, données structurées correspondant au contenu visible. GEO commence par cela : un contenu indexable et citable, et une politique explicite pour les robots d'AI. Aucune garantie de classement ou de citation.
- Les kits sont adaptés, pas enveloppés. Le thème et les tokens proviennent des décisions de conception du produit. Enveloppez un composant de kit uniquement pour un comportement produit répété ou pour figer une API. N'empilez pas un deuxième système d'animation sur les transitions propres d'un kit.
Terminé
Appliquez web-craft → terminé, plus : aucun bundle client ne contient un secret ou un module serveur uniquement ; deux requêtes simultanées dans des locales différentes ou pour des utilisateurs différents ne peuvent pas mélanger les données ; le premier rendu est dans la bonne langue et le bon thème ; chaque combinaison kit/framework revendiquée a été effectivement vérifiée.