Next.js Entwicklungsumgebung Einrichtung (`nextjs-dev-setup`)

Einrichtung der Next.js Entwicklungsumgebung (nextjs-dev-setup)

Ein strukturiertes, durchgängiges Orchestrierungs-Runbook für das Entdecken, Konfigurieren und Verifizieren der Next.js App Router Entwicklungsumgebung, des Reverse-Proxy-Routings (Traefik / Nginx) und der einzigen Quelle der Wahrheit in docs/project.json.

---

Vorbedingungen & Erkundung

• Scan ohne Unterbrechung: Scanne vorhandene Repository-Dateien (package.json, Lockfiles, Stylesheets, docs/adr/*.md, docs/plan.md, CONTEXT.md), bevor Fragen gestellt werden.
• Konsultiere project-json-schema.md für die Metadatenstruktur und automatische Ableitungsregeln.

---

Phase 0: Mehrstufiges Einrichtungsinterview & Planerstellung

Führe das interaktive Interview in progressiven, adaptiven Runden durch (warte nach jeder Runde auf die Antwort des Benutzers), um die Einrichtung anzupassen:

1. Runde 1 (Umfang & Werkzeuge): Frage nach Ziel-Test-Suites (Jest, Playwright, Storybook), MCP-Servern und @shadcn/lint -Erzwingung.
2. Runde 2 (Reverse Proxy & Produktions-Hosting): Frage nach Domain-Namen, Port und Reverse-Proxy-Strategie:
   • Traefik via Docker Compose: Automatisierte Container-Erkennung mit Compose-Labels, die aus Umgebungsvariablen gelesen werden (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) mit Anti-Buffering.
   • Nginx via Host-System: Eigenständige Konfiguration in /etc/nginx/sites-available/<domain> mit Certbot SSL-Zertifikaten.
3. Runde 3 (CI/CD, Git Hooks & Registry): Frage nach Husky Pre-Push-Test-Suites, Commitlint und GitHub Actions Release Please / GHCR-Workflows.
4. Konsultiere setup-interview-rounds.md für vollständige Fragesätze und Verzweigungslogik.
5. Plan & Ausführung: Generiere und präsentiere ein implementation_plan.md-Artefakt, das alle geplanten Dateierstellungen, Konfigurationen und Pakete detailliert auflistet, bevor Änderungen angewendet werden, und fahre direkt mit der Ausführung fort, ohne auf eine manuelle Bestätigung zu warten.

---

Schritt-für-Schritt-Ausführungsablauf

Phase 1: Projekt-Metadaten & Entwicklerwerkzeuge (docs/project.json)

1. Initialisiere docs/project.json mit project.template.json basierend auf den Benutzerinterview-Auswahlen.
2. Konfiguriere .vscode/launch.json mit vscode-launch.json.template.
3. Erstelle app/providers.tsx mit <ProgressBarProvider> mit providers.tsx.template und zusammengesetztem <Link> mit Link.tsx.template.
4. Erstelle .env.example mit env.example.template für die Produktion und .env.local mit env.local.template für die lokale Entwicklung.
5. App Icons, Apple Icon & PWA Manifest: Stelle manifest.ts.template in app/manifest.ts bereit. Konfiguriere das vom Benutzer bereitgestellte Favicon in der Wurzel app/favicon.ico, app/icon.png und app/apple-icon.png (oder dynamisches ImageResponse-Icon). Konsultiere app-icons-and-pwa-guide.md.

Phase 2: Test-Suites (Jest, Playwright & Sofortnavigation)

[!WICHTIG] Keine Dummy-Testdateien (Regel 3): Erstelle keine Platzhalter-/Beispieltestdateien im Arbeitsbereich. Konfiguriere nur Framework-Dateien und Skripte. Beispielmuster sind verfügbar in sample-component.test.tsx, sample-navigation.spec.ts und sample-component.stories.tsx.

1. Jest Unit-Tests: Konfiguriere jest.config.ts.template und jest.setup.ts.template.
2. Playwright E2E & Sofortnavigation: Installiere @playwright/test und @next/playwright (pnpm add -D @playwright/test @next/playwright), konfiguriere playwright.config.ts.template und installiere Browser.
3. Next.js Sofortkonfiguration: Konfiguriere cacheComponents: true, partialPrefetching: true und Soforteinblicke in next.config.ts.
4. Storybook Workshop: Konfiguriere .storybook/main.ts und .storybook/preview.tsx.
5. Überprüfe Architekturen in testing-guide.md und storybook-guide.md.

Phase 3: Duale MCP-Server-Konfiguration

[!WICHTIG] Antigravity Global MCP Loading Rule: AG lädt nur MCP-Server, die global auf dem Host-System konfiguriert sind (~/.gemini/antigravity/mcp_config.json und ~/.gemini/config/mcp_config.json). Das Arbeitsbereichs-mcp.json wird für die Portabilität gepflegt. Beide müssen konfiguriert sein.

1. Konfiguriere next-devtools, playwright, storybook und codebase-memory-mcp.
2. Stottervermeidung: Setze auto_watch = false via codebase-memory-mcp config set auto_watch false und stelle die Wurzel .cbmignore bereit.
3. Überprüfe vollständige Spezifikationen in mcp-configuration-guide.md.

Phase 4: Agent-First Design System Linting (@shadcn/lint)

1. Installiere @shadcn/lint und konfiguriere die flache ESLint-Konfiguration mit eslint.config.mjs.template.
2. Überprüfe die Mechanismen in styling-and-linting-guide.md.

Phase 5: Eigenständiger Produktions-Docker & Reverse Proxy (Traefik / Nginx)

1. Löse in next.config.ts den Git-Commit-Hash auf (getGitCommitHash() mit CI-Fallbacks) und die Paketversion, injiziere NEXT_PUBLIC_APP_VERSION und NEXT_PUBLIC_GIT_COMMIT_HASH unter env, aktiviere output: "standalone", setze deploymentId für Versionsverschiebungsschutz (${pkg.version}-${gitHash}), konfiguriere headers mit X-Accel-Buffering: no und setze experimental.serverActions.allowedOrigins.
2. Dokumentiere NEXT_SERVER_ACTIONS_ENCRYPTION_KEY in .env.example und übergib ihn an Laufzeitumgebungen.
3. Stelle Dockerfile.template (mit STOPSIGNAL SIGTERM) und docker-compose.yml.template (mit stop_grace_period: 30s) bereit.
4. Reverse-Proxy-Konfiguration:
   • Traefik: Stelle docker-compose.prod.yml.template mit dynamischen Umgebungsvariablen-Labels (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) und Anti-Buffering-Middleware bereit.
   • Nginx: Stelle nginx-site.conf.template für /etc/nginx/sites-available/<domain> mit Certbot SSL-Zertifikaten bereit oder gib es aus.
5. Überprüfe die Architektur und den Hinweis auf Multi-Container-Cache-Drift in docker-containerization-guide.md.

Phase 6: Git Hooks & Kreditoptimierte CI/CD

1. Installiere husky, @commitlint/cli, @commitlint/config-conventional.
2. Konfiguriere commitlint.config.mjs.template, .husky/commit-msg und .husky/pre-push (pnpm run test:all).
3. Stelle .github/workflows/release-please.yml mit .next/cache Build-Caching und Multi-Arch-Matrix-Publishing bereit.
4. Überprüfe das Caching in cicd-and-release-automation-guide.md.

Phase 7: Abschlussbericht & Verifizierung

1. Führe das Konfigurationsverifizierungsskript aus und stelle sicher, dass alle Prüfungen bestanden werden.
2. Stage alle erstellten/geänderten Dateien in git (git add .) gemäß Regel 36.
3. Obligatorische Endausgabe: Gib die vollständige, strukturierte Next.js Dev Setup Execution Report Markdown-Tabelle aus, die alle implementierten Dateien, Verifizierungsergebnisse und nächste Entwicklungsschritte zusammenfasst.

---

Verifizierung & Plausibilitätsprüfung

• Führe das Konfigurationsverifizierungsskript aus:
  • 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
• Behebe alle gemeldeten Fehler und überprüfe erneut, bis alle Prüfungen bestanden sind.

---

Grenzfälle & Bekannte KI-Fallstricke

• Verkettete Befehle: Verkette niemals Befehle mit && oder ; in einer einzigen Zeile bei der Terminalausführung.
• MCP-Deaktivierung: In AG-Globalkonfigurationen ignoriert agy.exe "disabled": true innerhalb von mcpServers. Verschiebe deaktivierte Server außerhalb von mcpServers.
• Docker-Image-Namen: Die Docker OCI-Benennung erfordert streng genommen kleingeschriebene Repository-Namen (IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')).
• Storybook Intl-Kontext: Umwickle Storybook-Geschichten, die Link oder useTranslations rendern, immer mit NextIntlClientProvider.

---

Obligatorische Endausgabe: Berichtsvorlage

Gib diesen Bericht immer nach Abschluss des Skill-Workflows aus:

## 🛠️ Next.js Dev Setup Ausführungsbericht

| Schritt / Komponente                | Ziel-Datei(en) / Ressource                                                                             | Status                          | Notizen / Details                                                                |
| :---------------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------ | :------------------------------------------------------------------------------- |
| **1. Projekt-Metadaten**            | `docs/project.json`                                                                                    | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfigurierte Paketmanager, Verzeichnisse, Animations- & i18n-Metadaten.              |
| **2. App Icons & PWA Manifest**     | `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                             | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfiguriertes Root-Favicon, Apple Touch Icon und Web App Manifest mit Benutzer-Favicon. |
| **3. Kernabhängigkeiten**           | `package.json`, Lockfile                                                                               | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Überprüfte React-, Next.js-, Styling- und Animationsbibliotheken.                          |
| **4. Next.js Dev Server MCP**       | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json` | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfigurierter Next.js Dev Server (`next-devtools`) global für AG & im Arbeitsbereich.  |
| **5. Playwright & Soforttests**     | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Überprüfte Runner, Browser, Playwright MCP & `@next/playwright` Sofortnavigationshelfer. |
| **6. Codebase Memory & Stotterfix** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`                  | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Registrierter MCP, konfigurierte .cbmignore-Ausschlüsse und deaktivierter Sitzungsbeobachter.  |
| **7. Jest Unit-Tests**              | `jest.config.ts`, `jest.setup.ts`                                                                      | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfigurierter Next.js Jest-Transformer, jsdom-Umgebung & test-dom.               |
| **8. Storybook & Storybook MCP**    | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`    | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfiguriertes Storybook Vite, a11y, Themes & Storybook AI MCP global & Arbeitsbereich. |
| **9. Agent-First Tailwind Linter**  | `eslint.config.mjs`, `package.json`                                                                    | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfiguriertes `@shadcn/lint` für Agent-Überprüfung von Design-Tokens und Verträgen. |
| **10. Docker & Reverse Proxy**      | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                            | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Eigenständiger Container, Traefik-Labels / Nginx-HTTPS mit Certbot SSL.             |
| **11. Husky Git Hooks**             | `.husky/commit-msg`, `.husky/pre-push`                                                                 | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Erzwingt duale Pre-Push-Test-Suite (Jest + Playwright) & commitlint.              |
| **12. Commitlint-Konfiguration**    | `commitlint.config.mjs`                                                                                | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Konfiguriertes `@commitlint/config-conventional`.                                    |
| **13. Release & CI Build Caching**  | `.github/workflows/release-please.yml`                                                                 | `[IMPLEMENTIERT]` / `[UNVERÄNDERT]` | Next.js Build-Cache (.next/cache), SemVer Release PRs & GHCR Multi-Arch-Paket.     |
| **14. Umgebungsverifizierung**      | `scripts/verify-project-config.ps1` / `.sh`                                                            | `[BESTANDEN]`                      | Plausibilitätsprüfung ohne Fehler bestanden.                                     |

#### Status-Definitionen:
- **`[IMPLEMENTIERT]`**: Neu erstellt, installiert oder während dieses Einrichtungslaufs geändert.
- **`[UNVERÄNDERT]`**: Bereits vor der Ausführung des Skills korrekt konfiguriert; unverändert beibehalten.
- **`[ÜBERSPRUNGEN]`**: Aufgrund Benutzerpräferenz absichtlich ausgelassen.