# Gemini CLI in Next.js-Projekten: Praktischer Leitfaden

URL: https://agentvera.dev/de/blog/gemini-cli-fuer-nextjs/ · Veröffentlicht: 2026-11-01

So nutzt du Gemini CLI effektiv in Next.js-Projekten: GEMINI.md, Arbeitsabläufe, typische Aufgaben, Testing und Fallstricke bei Server- und Client-Komponenten.

**Kurz gesagt:**

- GEMINI.md ist die zentrale Steuerdatei für Gemini CLI im Next.js-Projekt; dort stehen Build-, Test- und Lint-Befehle sowie Ordnerregeln.
- Arbeite in kleinen Schritten, lass den Agenten Tests ausführen und prüfe vor jedem Commit das Diff, um Client-/Server-Grenzen nicht zu verletzen.
- Gemini CLI eignet sich besonders für Data Fetching, Route Handlers und UI-Iterationen; Vorsicht bei RSC und Hydration.

Der Coding-Agent [Gemini CLI](/de/agents/gemini-cli/) startet im Next.js-Projektordner mit `gemini`. Er liest die Projektdateien, befolgt die Regeln aus GEMINI.md und führt selbst Befehle wie `npm run lint`, `npm test` oder `npm run build` aus. Damit eignet er sich für Next.js-Arbeit, die viele Dateien und Konventionen berührt – von Route Handlers bis zu Server Components. Dieser Leitfaden zeigt, wie du ihn im Alltag mit App Router, Server Components, Testing und Fallstricken einsetzt.

## Warum Gemini CLI für Next.js-Arbeit passt
Next.js-Projekte bestehen aus vielen kleinen Dateien mit starken Konventionen: `app/` oder `pages/`, `layout.tsx`, `page.tsx`, Route Handlers, Server Actions, Server- und Client Components. Ein Terminal-Agent hat den ganzen Projektbaum im Kontext und kann Änderungen über mehrere Dateien hinweg konsistent ausführen. Er kennt TypeScript- und React-Muster, liest die `next.config`-Datei und kann die Next.js-Befehle direkt im Projekt ausführen. Dadurch sieht er Lint-Fehler, Build-Ausgaben und Testresultate selbst und korrigiert sich, ohne dass du jede Meldung manuell kopierst. Für wiederkehrende Aufgaben wie das Anlegen eines neuen Route Handlers samt Validierung, das Umwandeln einer Komponente in eine Client Component oder das Beheben von Hydration-Fehlern spart das spürbar Zeit. Gerade bei der Arbeit mit App Router und Server Components, wo Änderungen oft mehrere Dateien betreffen – eine Server Component für Daten, eine Client Component für Interaktion, ein Route Handler für die API –, ist die integrierte Sicht des Agenten wertvoll. Wichtig ist, dass du ihm die Projektregeln in GEMINI.md gibst; sonst arbeitet er mit generischen Annahmen und übersieht Next.js-Spezifika.

## Projekt für den Agenten einrichten
Die zentrale Steuerdatei ist GEMINI.md im Projektstamm. Sie sollte kurz und verbindlich sein: Befehle, Ordnerkonventionen und Next.js-spezifische Regeln. Je präziser diese Datei ist, desto weniger muss der Agent raten. Eine gute Vorlage sieht so aus:

```markdown
# GEMINI.md für Next.js

## Befehle
- Installieren: npm install
- Dev-Server: npm run dev
- Build: npm run build
- Lint: npm run lint
- Tests: npm run test (Vitest)
- E2E: npm run test:e2e (Playwright)

## Ordnerkonventionen
- App Router: app/ mit page.tsx, layout.tsx, loading.tsx, error.tsx
- Komponenten: components/ (nur wiederverwendbare UI)
- Server-Aktionen: app/actions.ts oder actions/
- Route Handlers: app/api/**/route.ts

## Regeln
- Server Components sind Default; `'use client'` nur wenn nötig.
- Keine Datenbankzugriffe in Client Components.
- Nutze next/link statt <a>.
- Halte API-Antworten schlank; verwende Route Handlers für JSON.
- Prüfe immer die Hydration: keine dynamischen Werte in Server- und Client-Rendering.
```

Ergänze bei Bedarf Abschnitte für Authentication, Datenbankzugriffe oder Deployment. Trage die tatsächlich genutzten Befehle ein – etwa `npm run test` für Vitest oder `npx playwright test` für Playwright. Enthält dein Projekt einen `src/`-Ordner oder ein Monorepo, beschreibe den Pfad eindeutig. Auch Regeln wie „Keine `any`-Typen“ oder „Server Actions nur in `app/actions.ts`“ helfen. Vermeide es, in GEMINI.md allgemeine Programmierregeln wie „Schreibe sauberen Code“ zu wiederholen; das bläht die Datei auf und verwässert die wichtigen Punkte. Die ausführliche [Schritt-für-Schritt-Anleitung](/de/blog/how-to-use-gemini-cli/) zeigt, wie du GEMINI.md weiter schärfst und den Agenten schrittweise einrichtest.

## Ein tragfähiger Arbeitsablauf
Bewährt hat sich ein Loop aus Planen, kleinem Schritt, Tests und Diff-Review. Lass den Agenten zuerst den Plan formulieren, dann eine überschaubare Änderung umsetzen, danach `npm run lint`, `npm test` und `npm run build` ausführen und zeige dir am Ende den Diff mit `git diff`. Erst wenn Build und Tests grün sind, committest du. Dieser Ablauf ähnelt dem [Pair Programming mit KI](/de/blog/ai-pair-programming/), nur dass der Agent die Ausführung übernimmt. Halte die Schritte bewusst klein: Eine neue Route plus Tests ist okay; ein komplettes Redesign nicht. So bleiben Fehler lokalisierbar und der Diff überschaubar.

Beispielprompts für typische Next.js-Aufgaben:
- „Erstelle einen Route Handler unter `app/api/feedback/route.ts`, der POST-Anfragen validiert und in eine SQLite-Tabelle speichert.“
- „Wandle `components/UserProfile.tsx` in eine Client Component um; nutze `useEffect` für das Laden und zeige einen Skeleton.“
- „Behebe alle ESLint-Fehler in `app/dashboard/page.tsx`, ohne die Server-Client-Grenze zu verletzen.“
- „Schreibe einen Vitest-Test für `lib/api.ts`, der den Auth-Token Header prüft.“
- „Ergänze eine Lade- und Fehler-UI für die Route `/products` mit `loading.tsx` und `error.tsx`.“

Diese Prompts sind bewusst auf eine Datei oder einen Aspekt begrenzt.

## Typische Aufgaben und Fallstricke
Gemini CLI ist stark bei klar abgegrenzten, musterhaften Aufgaben. Besonders gut gelingt das Erstellen von Route Handlers mit Validierung, das Einrichten von Server Actions für Formulare, das Umwandeln von Komponenten in Client Components mit passenden Props und das Schreiben von Tests für Utilities und APIs. Auch Datenabrufe in Server Components direkt in der Datenbank oder über `fetch` mit Caching sind dank klarer Muster gut machbar.

Vorsicht ist bei drei Stellen geboten. Erstens die Server-/Client-Grenze: Der Agent setzt manchmal `'use client'` zu großzügig und macht aus einer Server Component unnötig eine Client Component, oder er übersieht, dass eine importierte Komponente client-seitig sein muss. Zweitens Hydration-Fehler: Dynamische Werte wie `Date.now()` oder zufällige IDs ohne `suppressHydrationWarning` führen zu inkonsistentem Rendering. Drittens Build-Fehler durch nicht abgedeckte Importe oder falsche `next.config`-Einstellungen. Der Agent bemerkt sie oft erst, wenn `npm run build` ausgeführt wird – deshalb gehört der Build immer in den Loop. Auch das Refactoring von Seiten, die stark auf `getServerSideProps` im Pages Router basieren, kann schiefgehen, wenn der Agent nicht erkennt, dass der Wechsel zu App Router ein anderes Datenabrufmodell erfordert.

| Aufgabe | Empfohlener Prompt |
|---|---|
| Neuen Route Handler anlegen | „Erstelle `app/api/feedback/route.ts` mit POST, validiere den Body und speichere in SQLite.“ |
| Client Component isolieren | „Extrahiere den interaktiven Teil aus `app/profile/page.tsx` nach `components/ProfileForm.tsx` mit `'use client'`.“ |
| Hydration-Fehler beheben | „Finde und behebe den Hydration-Fehler in `app/page.tsx`; zeige mir die betroffenen Zeilen.“ |
| E2E-Test ergänzen | „Schreibe einen Playwright-Test, der sich einloggt und `/dashboard` aufruft.“ |

## Testen und Verifizieren mit Gemini CLI in Next.js
Die wichtigste Verifikation ist der Produktions-Build. `npm run build` prüft Server-/Client-Imports, Typen und statische Optimierung. Der Dev-Server allein reicht nicht, weil er viele Fehler erst zur Laufzeit zeigt. Lass den Agenten nach jeder Änderung mindestens `npm run lint` und `npm test` ausführen. Unit-Tests mit Vitest oder Jest sollten vor allem Logik in `lib/`, `utils/` und Server Actions abdecken. Für Integrationstests eignen sich Route Handler mit Supertest oder MSW. Führe Playwright-Tests für kritische Nutzerpfade aus, besonders nach Änderungen an Auth, Navigation oder Formularen. Der Agent kann die Tests selbst starten und auf Fehler reagieren – aber prüfe das Diff immer selbst, bevor du committest. Achte darauf, dass er keine Tests löscht oder nur oberflächlich anpasst, um sie grün zu bekommen. Ein rotes Build trotz grüner Tests ist ein Warnsignal.

## Mehrere Agenten auf einem Next.js-Projekt mit AgentVera
AgentVera ist eine Desktop-App, die echte CLI-Agenten wie Gemini CLI, Claude Code und andere in eigenen Terminal-Panels parallel ausführt. Für Next.js-Arbeit ist besonders wertvoll, dass jeder Agent in einem eigenen Git-Worktree arbeiten kann – so überschreiben sich parallele Änderungen an App Router-Dateien nicht. Die automatische Codeüberprüfung durch ein zweites Modell nach jeder Agenten-Runde hilft, subtile Server-/Client-Fehler früh zu erkennen. Checkpoints erlauben es, einen fehlgeschlagenen Schritt per Klick zurückzunehmen und die Sitzung erneut abzuspielen – praktisch, wenn der Agent versehentlich Hydration-Fehler einbaut. Token-Budgets pro Agent und Tag begrenzen die Kosten, ohne die Konversation zu verlieren. So lassen sich mehrere Features gleichzeitig vorantreiben, ohne ständig manuell Branches zu wechseln. Weitere Muster dazu beschreibt der Beitrag zur [KI-Agenten-Orchestrierung beim Coden](/de/blog/ai-coding-agent-orchestration/).

## Fazit
Gemini CLI ist ein nützlicher Pair-Programmierer für Next.js, wenn du ihn mit klaren Regeln aus GEMINI.md fütterst und in kleinen Schritten mit Build- und Test-Gate vorankommen lässt. Die typischen Fallstricke an Server-/Client-Grenze und Hydration sind beherrschbar, solange du den Diff prüfst und den Produktions-Build als oberste Instanz behandelst. Mit einem disziplinierten Loop und gelegentlich mehreren parallelen Worktrees wird der Agent zu einer echten Arbeitshilfe statt zu einem Risiko.

## Häufige Fragen

**Wie starte ich Gemini CLI in einem Next.js-Projekt?** Wechsle in das Projektverzeichnis und führe gemini aus. Lege zuvor eine GEMINI.md mit den Next.js-spezifischen Befehlen und Regeln an, damit der Agent die Konventionen kennt.

**Kann Gemini CLI zwischen Server- und Client Components unterscheiden?** Ja, wenn die Regeln in GEMINI.md klar sind und der Agent den Projektcode analysiert. Er benötigt explizite Hinweise, dass Server Components der Default sind und 'use client' nur bei Bedarf gesetzt wird.

**Welche Befehle sollte ich in GEMINI.md für Next.js hinterlegen?** Mindestens Install, Lint, Test und Build: npm install, npm run lint, npm run test, npm run build. Sinnvoll sind auch Dev-Server und Playwright-Befehle für E2E-Tests.

**Wie teste ich Änderungen von Gemini CLI in Next.js?** Lass den Agenten nach jeder Änderung Lint, Unit-Tests und npm run build ausführen. Der Produktions-Build deckt viele Server-/Client-Fehler auf, die der Dev-Server nicht zeigt.

---

**Über AgentVera.** AgentVera ist eine Desktop-App für macOS, Windows und Linux, entwickelt von Solviera Teknoloji. Sie führt 18 KI-Coding-Agenten (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) nebeneinander aus, pro Projekt, in echten Terminals mit den eigenen CLI-Installationen und Logins des Nutzers. Der kostenlose Plan hat unbegrenzt viele Agenten. Download: https://agentvera.dev/de/download/ · Preise: https://agentvera.dev/de/pricing/