BIGboss248/nextjs-wordpress

Configuration de l'environnement de développement Next.js (nextjs-dev-setup)

Un guide d'orchestration structuré de bout en bout pour découvrir, configurer et vérifier l'environnement de développement Next.js App Router, le routage par proxy inverse (Traefik / Nginx) et une source de vérité unique dans docs/project.json.

---

Pré-conditions et découverte

• Analyse sans interruption : Analysez les fichiers existants du dépôt (package.json, lockfiles, feuilles de style, docs/adr/*.md, docs/plan.md, CONTEXT.md) avant de poser des questions.
• Consultez project-json-schema.md pour la structure des métadonnées et les règles de déduction automatisées.

---

Phase 0 : Entretien de configuration multi-tours (approfondi) et génération du plan

Menez l'entretien interactif en tours progressifs et adaptatifs (en attendant la réponse de l'utilisateur après chaque tour) pour personnaliser la configuration :

1. Tour 1 (Périmètre et outils) : Interrogez sur les suites de test cibles (Jest, Playwright, Storybook), les serveurs MCP et l'application de @shadcn/lint.
2. Tour 2 (Proxy inverse et hébergement de production) : Interrogez sur le nom de domaine, le port et la stratégie de proxy inverse :
   • Traefik via Docker Compose : Découverte automatique des conteneurs à l'aide des labels Compose qui lisent les variables d'environnement (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) avec anti-buffering.
   • Nginx via le système hôte : Configuration autonome dans /etc/nginx/sites-available/<domain> utilisant les certificats SSL Certbot.
3. Tour 3 (CI/CD, hooks Git et registre) : Interrogez sur les suites de test Husky pre-push, Commitlint et les workflows GitHub Actions Release Please / GHCR.
4. Consultez setup-interview-rounds.md pour les ensembles de questions complets et la logique de branchement.
5. Plan et exécution : Générez et présentez un artefact implementation_plan.md détaillant tous les fichiers, configurations et paquets prévus avant d'appliquer les modifications, puis procédez directement à l'exécution sans attendre de confirmation manuelle.

---

Flux d'exécution étape par étape

Étape 1 : Métadonnées du projet et outils de développement (docs/project.json)

1. Initialisez docs/project.json en utilisant project.template.json en fonction des choix de l'utilisateur lors de l'entretien.
2. Configurez .vscode/launch.json en utilisant vscode-launch.json.template.
3. Échafaudez app/providers.tsx avec <ProgressBarProvider> en utilisant providers.tsx.template et le composant composite <Link> en utilisant Link.tsx.template.
4. Échafaudez .env.example en utilisant env.example.template pour la production et .env.local en utilisant env.local.template pour le développement local.
5. Icônes d'application, icône Apple et manifeste PWA : Déployez manifest.ts.template vers app/manifest.ts. Configurez le favicon fourni par l'utilisateur dans app/favicon.ico, app/icon.png et app/apple-icon.png (ou une icône dynamique ImageResponse). Consultez app-icons-and-pwa-guide.md.

Étape 2 : Suites de test (Jest, Playwright et navigation instantanée)

[!IMPORTANT] Aucun fichier de test factice (Règle 3) : Ne créez pas de fichiers de test factices ou d'exemple dans l'espace de travail. Configurez uniquement les fichiers et scripts du framework. Des exemples de modèles sont disponibles dans sample-component.test.tsx, sample-navigation.spec.ts et sample-component.stories.tsx.

1. Tests unitaires Jest : Configurez jest.config.ts.template et jest.setup.ts.template.
2. Playwright E2E et navigation instantanée : Installez @playwright/test et @next/playwright (pnpm add -D @playwright/test @next/playwright), configurez playwright.config.ts.template et installez les navigateurs.
3. Configuration instantanée Next.js : Configurez cacheComponents: true, partialPrefetching: true et les insights instantanés dans next.config.ts.
4. Atelier Storybook : Configurez .storybook/main.ts et .storybook/preview.tsx.
5. Passez en revue les architectures dans testing-guide.md et storybook-guide.md.

Étape 3 : Configuration du double serveur MCP

[!IMPORTANT] Règle de chargement global MCP d'Antigravity : AG ne charge que les serveurs MCP configurés globalement sur le système hôte (~/.gemini/antigravity/mcp_config.json et ~/.gemini/config/mcp_config.json). Le fichier mcp.json de l'espace de travail est conservé pour la portabilité. Les deux doivent être configurés.

1. Configurez next-devtools, playwright, storybook et codebase-memory-mcp.
2. Prévention du bégaiement : Définissez auto_watch = false via codebase-memory-mcp config set auto_watch false et déployez .cbmignore à la racine.
3. Passez en revue les spécifications complètes dans mcp-configuration-guide.md.

Étape 4 : Linting du système de conception axé sur l'agent (@shadcn/lint)

1. Installez @shadcn/lint et configurez la configuration plate ESLint en utilisant eslint.config.mjs.template.
2. Passez en revue les mécanismes dans styling-and-linting-guide.md.

Étape 5 : Docker de production autonome et proxy inverse (Traefik / Nginx)

1. Dans next.config.ts : résolvez le hash du commit Git (getGitCommitHash() avec des solutions de repli CI) et la version du paquet, injectez NEXT_PUBLIC_APP_VERSION et NEXT_PUBLIC_GIT_COMMIT_HASH sous env, activez output: "standalone", définissez deploymentId pour la protection contre les décalages de version (${pkg.version}-${gitHash}), configurez les headers avec X-Accel-Buffering: no et définissez experimental.serverActions.allowedOrigins.
2. Documentez NEXT_SERVER_ACTIONS_ENCRYPTION_KEY dans .env.example et transmettez-le aux environnements d'exécution.
3. Déployez Dockerfile.template (avec STOPSIGNAL SIGTERM) et docker-compose.yml.template (avec stop_grace_period: 30s).
4. Configuration du proxy inverse :
   • Traefik : Déployez docker-compose.prod.yml.template avec des labels de variables d'environnement dynamiques (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) et un middleware anti-buffering.
   • Nginx : Déployez ou générez nginx-site.conf.template pour /etc/nginx/sites-available/<domain> avec les certificats SSL Certbot.
5. Passez en revue l'architecture et l'avertissement de dérive du cache multi-conteneurs dans docker-containerization-guide.md.

Étape 6 : Hooks Git et CI/CD optimisé pour les crédits

1. Installez husky, @commitlint/cli, @commitlint/config-conventional.
2. Configurez commitlint.config.mjs.template, .husky/commit-msg et .husky/pre-push (pnpm run test:all).
3. Déployez .github/workflows/release-please.yml avec la mise en cache de la construction .next/cache et la publication matricielle multi-architecture.
4. Passez en revue la mise en cache dans cicd-and-release-automation-guide.md.

Étape 7 : Rapport d'exécution final et vérification

1. Exécutez le script de vérification de la configuration et assurez-vous que toutes les vérifications réussissent.
2. Staguez tous les fichiers créés/modifiés dans git (git add .) conformément à la Règle 36.
3. Sortie finale obligatoire : Affichez le tableau markdown complet et structuré du Rapport d'exécution de la configuration de l'environnement de développement Next.js résumant tous les fichiers implémentés, les résultats des vérifications et les prochaines étapes de développement.

---

Vérification et test de cohérence

• Exécutez le script de vérification de la configuration :
  • Windows (PowerShell) : powershell -ExecutionPolicy Bypass -File .agents/skills/nextjs-dev-setup/scripts/verify-project-config.ps1
  • Linux / macOS (Bash) : bash .agents/skills/nextjs-dev-setup/scripts/verify-project-config.sh
• Corrigez les éventuelles erreurs signalées et revérifiez jusqu'à ce que toutes les vérifications réussissent.

---

Cas limites et pièges IA connus

• Commandes chaînées : Ne chaînez jamais les commandes avec && ou ; sur une seule ligne dans l'exécution du terminal.
• Désactivation de MCP : Dans les configurations globales d'AG, agy.exe ignore "disabled": true à l'intérieur de mcpServers. Déplacez les serveurs désactivés en dehors de mcpServers.
• Noms d'images Docker : La dénomination OCI Docker exige strictement des noms de dépôt en minuscules (IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')).
• Contexte intl de Storybook : Enveloppez toujours les stories Storybook qui rendent Link ou useTranslations avec NextIntlClientProvider.

---

Modèle de rapport d'exécution final obligatoire

Générez toujours ce rapport à la fin du workflow de la compétence :

## 🛠️ Rapport d'exécution de la configuration de l'environnement de développement Next.js

| Étape / Composant                  | Fichier(s) cible(s) / Ressource(s)                                                                       | Statut                          | Notes / Détails                                                                  |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------- |
| **1. Métadonnées du projet**       | `docs/project.json`                                                                                      | `[IMPLEMENTED]` / `[UNTOUCHED]` | Gestionnaire de paquets configuré, répertoires, métadonnées d'animation et i18n. |
| **2. Icônes d'application et manifeste PWA** | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                               | `[IMPLEMENTED]` / `[UNTOUCHED]` | Favicon racine configuré, icône tactile Apple et manifeste d'application Web utilisant le favicon de l'utilisateur. |
| **3. Dépendances principales**     | `package.json`, Lockfile                                                                                 | `[IMPLEMENTED]` / `[UNTOUCHED]` | Bibliothèques React, Next.js, de style et de mouvement vérifiées.               |
| **4. Serveur de développement Next.js MCP** | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json`   | `[IMPLEMENTED]` / `[UNTOUCHED]` | Serveur de développement Next.js (`next-devtools`) configuré globalement pour AG et dans l'espace de travail. |
| **5. Playwright et tests instantanés** | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`          | `[IMPLEMENTED]` / `[UNTOUCHED]` | Exécuteur de Playwright, navigateurs, MCP Playwright et assistant de navigation instantanée `@next/playwright` vérifiés. |
| **6. Mémoire de codebase et correction du bégaiement** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`                   | `[IMPLEMENTED]` / `[UNTOUCHED]` | MCP enregistré, exclusions .cbmignore configurées et observateur de session désactivé. |
| **7. Tests unitaires Jest**        | `jest.config.ts`, `jest.setup.ts`                                                                        | `[IMPLEMENTED]` / `[UNTOUCHED]` | Transformateur Jest Next.js configuré, environnement jsdom et test-dom.          |
| **8. Storybook et MCP Storybook**   | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`       | `[IMPLEMENTED]` / `[UNTOUCHED]` | Storybook Vite configuré, a11y, thèmes et MCP IA Storybook globalement et dans l'espace de travail. |
| **9. Linter Tailwind axé sur l'agent** | `eslint.config.mjs`, `package.json`                                                                      | `[IMPLEMENTED]` / `[UNTOUCHED]` | `@shadcn/lint` configuré pour la vérification par agent des jetons de conception et des contrats. |
| **10. Docker et proxy inverse**      | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                                | `[IMPLEMENTED]` / `[UNTOUCHED]` | Conteneur autonome, labels Traefik / Nginx HTTPS avec Certbot SSL.                |
| **11. Hooks Git Husky**             | `.husky/commit-msg`, `.husky/pre-push`                                                                    | `[IMPLEMENTED]` / `[UNTOUCHED]` | Applique la double suite de test pre-push (Jest + Playwright) et commitlint.      |
| **12. Configuration Commitlint**    | `commitlint.config.mjs`                                                                                  | `[IMPLEMENTED]` / `[UNTOUCHED]` | `@commitlint/config-conventional` configuré.                                      |
| **13. Mise en cache des builds de release et CI** | `.github/workflows/release-please.yml`                                                                   | `[IMPLEMENTED]` / `[UNTOUCHED]` | Cache de build Next.js (.next/cache), PR de version SemVer et paquet multi-arch GHCR. |
| **14. Vérification de l'environnement** | `scripts/verify-project-config.ps1` / `.sh`                                                              | `[PASSED]`                      | Test de cohérence réussi avec zéro erreur.                                         |

#### Définitions des statuts :
- **`[IMPLEMENTED]`** : Créé, installé ou modifié lors de cette exécution de configuration.
- **`[UNTOUCHED]`** : Déjà correctement configuré avant l'exécution de la compétence ; conservé tel quel.
- **`[SKIPPED]`** : Volontairement omis en fonction de la préférence de l'utilisateur.