Développement de Composants & Skeletons Next.js

Développement de Composants & Skeletons Next.js (nextjs-component-dev)

Workflow spécialisé pour créer des composants React Server (RSC) et Client prêts pour la production avec des skeletons Suspense, des tests TDD en double couche (tests unitaires Jest + RTL et tests d'intégration/hydratation/visuels Playwright), des traductions basées sur les dictionnaires next-intl, des tokens de thème sémantiques et des diagnostics runtime en direct via le serveur MCP next-devtools.

[!TIP] Actifs et Modulaires :

• Recherche et Contexte dans la Documentation Next.js : references/nextjs-docs-lookup.md
• Architecture de Test et Vérification : references/testing-architecture-guide.md
• Standards Storybook et Séparation : references/storybook-reference.md
• Navigation Instantanée et Préchargement : references/instant-navigation-and-prefetching.md
• Guide de Débogage Next DevTools : references/next-devtools-debugging.md
• Mise en Cache et Revalidation : references/caching-and-revalidation.md
• Modèles de Code : resources/templates/ (Composant, Skeleton, Test Unitaire Jest, Spécification Playwright)
• Implémentations de Référence : examples/
• Scripts de Vérification : scripts/verify-dev.ps1 (Windows) / scripts/verify-dev.sh (Linux)

---

Règles Architecturales et Standards

1. Contexte de Planification et Chemins

• Lire docs/project.json pour résoudre package_manager, new_component_dir, style_file_dir, component_library, dictionaries_dir (par défaut : "messages") et supported_languages.
• Toutes les routes internes DOIVENT utiliser ROUTES de @/lib/routes.
• Toutes les métadonnées d'auteur/site DOIVENT utiliser SITE_CONFIG de @/lib/site-config.
• Hiérarchie du chemin cible : <new_component_dir>/<page_or_global>/<NomDuComposant>/
  • Catégorie : global/ pour les éléments partagés du layout ; <nom-de-page>/ (ex. home/, about/, lab/) pour les sections propres à une page.

2. Recherche dans la Documentation Interne de Next.js (node_modules/next/dist/docs)

• Recherche dans la Documentation Locale via le MCP Codebase Memory : Pour toute création de composant, interroger et inspecter activement la documentation locale de la distribution Next.js dans node_modules/next/dist/docs/ à l'aide des outils MCP codebase-memory (search_code, search_graph, get_code_snippet) pour les signatures d'API pertinentes, les directives ('use cache', 'use client', 'use server'), les composants intégrés (next/image, next/link, next/font, <Form>), les hooks de navigation (useRouter, usePathname) et les politiques de caching (cacheLife, cacheTag).
• Éliminer les Dépréciations et Hallucinations : Ne jamais se fier à des hypothèses ou à des patterns Next.js obsolètes ; la documentation locale node_modules/next/dist/docs correspondant à la version installée du paquet est la source de vérité principale. Consulter references/nextjs-docs-lookup.md.

3. Serveur de Développement et Protocole Next DevTools

• Vérification du Serveur de Développement et Connexion : Avant/pendant le développement du composant, vérifier si le serveur de développement Next.js est en cours d'exécution via le serveur MCP next-devtools (nextjs_index).
• Si le serveur est en cours d'exécution : Se connecter immédiatement au serveur et au port en cours d'exécution ; ne pas redémarrer.
• Si le serveur n'est pas en cours d'exécution : Démarrer le serveur de développement en arrière-plan (pnpm dev, IsDaemon: true) et vérifier la connexion via nextjs_index.
• Débogage Runtime : Après l'implémentation des composants, interroger next-devtools (nextjs_call) pour inspecter les erreurs, vérifier l'état de la compilation et diagnostiquer immédiatement les problèmes d'exécution. Consulter references/next-devtools-debugging.md.

4. Limites RSC et Push-Down des Composants Client Feuilles

1. Composants Serveur par Défaut : Garder les composants rendus côté serveur (async function).
2. Pousser "use client" vers le bas : Isoler les gestionnaires interactifs (boutons, interrupteurs, entrées de formulaire) dans de petits composants Client feuilles.
3. Composition RSC : Passer les composants Serveur en tant que children ou props dans des wrappers Client. Ne jamais importer de composants Serveur à l'intérieur de fichiers "use client".

5. Style, Propriétés Logiques et Tokens de Thème

• Tokens Sémantiques : Utiliser exclusivement les variables CSS sémantiques définies dans app/globals.css (bg-background, text-foreground, border-border, text-muted-foreground). Les couleurs hexadécimales en dur (#FAFAFA) ou les échelles de couleurs brutes (bg-blue-500) sont INTERDITES.
• Fusion de Classes : Toujours fusionner les classes en utilisant cn(...) (clsx + tailwind-merge).
• Propriétés Logiques (BiDi) : Utiliser exclusivement les propriétés logiques Tailwind (ms-, pe-, ps-, me-, start, end). Les classes directionnelles physiques (ml-, mr-, pl-, pr-, left-, right-) sont INTERDITES.
• Liens de Progression : Utiliser <Link> de @vercel/react-transition-progress pour la navigation principale, les CTA des héros et les cartes interactives ; utiliser next/link standard pour les liens utilitaires statiques.
• Images : Toujours utiliser next/image avec des dimensions explicites ou fill, des sizes responsives et priority pour les actifs LCP au-dessus de la ligne de flottaison.

6. Navigation Instantanée, Suspense Granulaire et Architecture de Caching

• Les Trois Leviers pour des Composants Instantanés :
  1. Pousser vers le bas : Extraire les opérations asynchrones spécifiques à la requête (await params, await searchParams, cookies(), headers(), appels DB/API non mis en cache) dans des sous-composants feuilles enveloppés dans <Suspense>. Les parents et frères statiques sont remontés directement dans le Shell/App statique.
  2. Cache : Associer 'use cache' avec cacheLife et cacheTag au niveau de la fonction/composant. Utiliser les patterns de pontage de session :
     • Pattern A (Extraire et Passer) : Extraire les attributs de session (ex. team_id, role, tier) de cookies() à l'extérieur et les passer comme arguments aux fonctions 'use cache' afin que les données mises en cache soient partagées entre tous les utilisateurs ayant des attributs correspondants (le coût évolue avec le nombre d'équipes/attributs, pas avec le nombre de sessions utilisateur).
     • Pattern B ("use cache: private") : Pour les recherches de session strictement spécifiques à l'utilisateur, utiliser la mise en cache de session uniquement côté navigateur avec stale >= 5m qui voyage avec le Shell de l'application.
  3. Stratégie de Préchargement et Grilles Denses :
     • Préchargement par Défaut du Shell d'Application (<Link> / prefetch={null}) : Précharge un Shell/App statique partagé par route. Coût limité ($O(\text{routes})$), zéro invocation serveur par lien. Utiliser pour les flux denses, les grilles de cartes (50+ cartes) et la navigation en bloc.
     • Préchargement par Lien (<Link prefetch={true}>) : Résout les données d'URL dynamiques (params, searchParams) avant la navigation avec 1 invocation serveur par lien visible. Utiliser avec parcimonie pour les CTA principaux à forte intention, les actions de héros ou les éléments de liste maître-détail où le flash de skeleton doit être éliminé.
     • Grilles de Cartes Denses : NE JAMAIS utiliser prefetch={true} de manière générale sur des dizaines de cartes dans des flux. Conserver le <Link> par défaut ou utiliser le préchargement basé sur le survol/le focus (router.prefetch()).
• États de Chargement Granulaires (Anti-Flash Pleine Page) : Ne jamais envelopper un composant ou une page entier dans une seule limite <Suspense> de niveau supérieur qui ferait apparaître des squelettes complets. Garder les titres, les cadres de mise en page et le contenu mis en cache visibles immédiatement ; placer <Suspense> strictement autour des emplacements de streaming dynamiques.
• Directives de Caching Natifs Next.js 16 : Consulter references/instant-navigation-and-prefetching.md et references/caching-and-revalidation.md.

7. TanStack Query et Préchargement Serveur

• Contrat de Cache Unifié : Définir key, tag et queryOptions avec un staleTime explicite (ex. 30_000 ms).
• Préchargement Serveur : Déclencher un préchargement non attendu (void queryClient.prefetchQuery(...)) appelant directement les fonctions DB internes (zéro fetch relatif sur le serveur). Déshydrater avec <HydrationBoundary>.
• Composants Streamés : Utiliser useSuspenseQuery à l'intérieur de <Suspense fallback={<[NomDuComposant]Skeleton />}>.
• Mutations Optimistes : Utiliser useMutation avec des instantanés de cache onMutate et des rollbacks onError ; appeler les Actions Serveur avec updateTag(cache.tag).

8. Division du Travail de Test en Double Couche (Jest vs. Playwright)

• Jest + RTL ([NomDuComposant].test.tsx) :
  • Boucle de feedback rapide dans jsdom.
  • Permutations de props, éléments d'interface conditionnels et états vides/nuls.
  • Interactions utilisateur via @testing-library/user-event (jamais fireEvent).
  • Mocks de routage Next.js (useRouter, usePathname, useSearchParams de next/navigation).
  • Vérifications d'interpolation et de pluralisation du dictionnaire next-intl à l'intérieur de NextIntlClientProvider.
  • Requêtes de rôles accessibles (screen.getByRole) et vérifications d'accessibilité automatisées (jest-axe).
• Playwright ([NomDuComposant].spec.ts ou spécifications au niveau de la page) :
  • Exécution dans un vrai navigateur (Chromium/WebKit/Firefox).
  • Assertions de Shell Instantané (@next/playwright) : Utiliser le helper instant(page, ...) pour affirmer que les shells statiques et les shells d'application préchargés s'affichent immédiatement avant la résolution du streaming dynamique du serveur.
  • Zéro Défaut d'Hydratation : Écouter les événements de la console du navigateur (page.on('console')) pour détecter et faire échouer les tests en cas d'avertissements d'hydratation SSR React.
  • Régression Visuelle et BiDi : Utiliser expect(page).toHaveScreenshot() à travers les thèmes (variables OKLCH clair vs. sombre) et les directions de texte (dir="ltr" vs. dir="rtl").
  • Résilience Réseau : Utiliser page.route() pour tester les réponses réseau lentes (vérifier que les squelettes Suspense correspondent à la géométrie pour éviter le CLS) et les limites d'erreur 500.
• Standards de Test Détaillés : Consulter references/testing-architecture-guide.md.

---

Phase 0 : Plan d'Implémentation et Porte d'Approbation

[!IMPORTANT] Planifier Avant d'Exécuter : Toujours générer et présenter un artefact implementation_plan.md détaillant toutes les créations de fichiers prévues, les modifications, les contrats TypeScript, les ajouts aux dictionnaires de traduction et les cas de test TDD avant d'exécuter des opérations d'écriture, de modifier des dictionnaires ou de créer des composants dans le dépôt. Attendre la confirmation/l'approbation de l'utilisateur avant de procéder à l'exécution.

Le plan d'implémentation doit couvrir :

1. Architecture et Chemin Cibles : Répertoire cible complet (<new_component_dir>/<page_or_global>/<NomDuComposant>/) et classification (composant RSC vs. Client feuille).
2. Documentation Locale Next.js Consultée : Chemins de docs spécifiques vérifiés sous node_modules/next/dist/docs/ (ex. 04-api-reference/04-components/image.md, 03-directives/use-cache.md, 04-api-reference/02-functions/use-router.md).
3. Contrats TypeScript : Interfaces de props et types avec des annotations TSDoc strictes en anglais.
4. Stratégie de Dictionnaire : Espaces de noms et clés de traduction explicites à ajouter à messages/[locale].json dans toutes les supported_languages de docs/project.json (zéro chaîne en dur ou dictionnaires simulés dans les fichiers).
5. Tokens de Thème et Style : Variables CSS OKLCH sémantiques identifiées et classes de mise en page logiques.
6. Stratégie de Test et Diagnostic :
   • Tests Unitaires Jest ([NomDuComposant].test.tsx) : Configurations de mock (next/navigation), variations de props, assertions de callback, intégration NextIntlClientProvider et requêtes de rôles d'accessibilité.
   • Scénarios d'Intégration Playwright ([NomDuComposant].spec.ts) : Cibles de capture d'écran visuelles (tokens de thème clair/sombre, mises en page logiques LTR vs. RTL), vérifications de géométrie des squelettes avec limitation de bande passante et écouteurs de vérification d'hydratation.
   • Diagnostics Next DevTools : Vérifications des erreurs runtime et de compilation via next-devtools.
7. Porte de Vérification : Commandes de vérification exactes à exécuter (verify-dev.ps1, tests unitaires ciblés et spécifications e2e Playwright).

---

Étapes du Workflow

• Étape 0 : Génération du Plan d'Implémentation et Porte d'Approbation

  • Rechercher et inspecter node_modules/next/dist/docs via le MCP codebase-memory (search_code, search_graph) pour toutes les API, directives, hooks ou composants Next.js utilisés par le composant prévu afin de garantir un contexte à jour.
  • Synthétiser les exigences du composant, analyser docs/project.json et générer implementation_plan.md documentant les docs et contrats consultés.
  • Définir request_feedback = true et user_facing = true sur l'artefact.
  • Attendre la revue et l'approbation explicite de l'utilisateur avant d'écrire du code.

• Étape 1 : Vérification du Serveur de Développement et Connexion Next DevTools

  • Interroger le MCP next-devtools via nextjs_index pour détecter les instances de serveur de développement Next.js en cours d'exécution.
  • Si le serveur de développement est en cours d'exécution : Se connecter au port et à l'instance serveur actifs ; continuer le développement sans redémarrer.
  • Si le serveur de développement n'est PAS en cours d'exécution : Démarrer le serveur de développement en arrière-plan (pnpm dev, IsDaemon: true) et vérifier la découverte avec nextjs_index.

• Étape 2 : Peuplement du Dictionnaire et Définition du Contrat TypeScript

  • Lire docs/project.json pour résoudre dictionaries_dir (messages est la valeur par défaut) et supported_languages.
  • Définir l'espace de noms et les clés de traduction du composant.
  • Peupler tous les fichiers de dictionnaire (messages/en.json, messages/fa.json, etc.) avec des traductions authentiques pour chaque langue prise en charge avant d'écrire du JSX.
  • Définir les interfaces de props avec des annotations TSDoc en anglais strictes (@param, @defaultValue, @returns).
  • S'il y a plus d'une langue prise en charge, le composant doit d'abord récupérer la traduction et, en cas d'échec, utiliser des valeurs de repli.

• Étape 3 : Tests Unitaires de Base TDD ([NomDuComposant].test.tsx via Jest + RTL)

  • Écrire [NomDuComposant].test.tsx AVANT d'implémenter le composant.
  • Mocker les hooks next/navigation (useRouter, usePathname, useSearchParams).
  • Envelopper les composants rendus dans NextIntlClientProvider en fournissant les messages du dictionnaire et la locale active.
  • Tester les attributs directionnels (dir="rtl" vs. dir="ltr"), les props par défaut, les callbacks interactifs (@testing-library/user-event), les fallbacks des skeletons Suspense et les rôles ARIA sémantiques.

• Étape 4