# GitHub Copilot CLI and Next.js: Practical Agent Workflow

URL: https://agentvera.dev/en/blog/copilot-cli-for-nextjs/ · Published: 2026-11-01

Practical guide to using GitHub Copilot CLI in a Next.js project: setup, prompts, testing, and pitfalls for App Router and Pages Router.

**In short:**

- Start copilot in your Next.js repo and give it explicit build, lint, and test commands to avoid wasted steps.
- Use .github/copilot-instructions.md to document server/client boundaries, route handler rules, and package scripts.
- Treat Copilot CLI output like a PR: run the full test suite and review diffs before accepting changes.

GitHub Copilot CLI is a terminal coding agent that works well in a Next.js repository when you start it with `copilot` in the project folder. This guide shows a concrete setup and working loop for App Router and Pages Router projects, including instructions, prompts, testing, and common failure points. It assumes you already know Next.js and want reliable, reviewable changes from the agent.

## Why a Next.js repo benefits from Copilot CLI

Next.js projects have many conventions that are easy to get wrong: server and client component boundaries, route handler signatures, caching, and strict build-time checks. [GitHub Copilot CLI](/en/agents/copilot-cli/) can read the whole repo, run package scripts, edit files, and rerun failing tests in the same loop. That makes it useful for mechanical but multi-file Next.js tasks like adding a route, splitting a client component, or fixing a Playwright failure. The key is giving it explicit project context. The agent reads .github/copilot-instructions.md or AGENTS.md at the root, so you can encode your router choice, test commands, and server-only rules once.

## Give the agent your project rules up front

Create either `.github/copilot-instructions.md` or `AGENTS.md` in the repo root. Keep the file short and factual. Include package manager, build/lint/test commands, router choice, folder structure, and Next.js-specific rules. For example:

```text
# Next.js project instructions for GitHub Copilot CLI

- Package manager: pnpm
- Build: pnpm build
- Lint: pnpm lint
- Unit tests: pnpm test (Vitest)
- E2E tests: pnpm e2e (Playwright)
- Use App Router under `app/` for all new routes.
- Keep `src/lib/` for shared server utilities; never import them in client components.
- Client components must be at leaves and include `"use client"`.
- Use route handlers in `app/api/` for external data mutations; do not call the database from client components.
- TypeScript strict mode is on; do not add `any`.
- Follow existing import order; ESLint with next/core-web-vitals is configured.
```

This gives the agent enough to avoid the most common Next.js mistakes. If you still use Pages Router, add a separate bullet saying `pages/` is only for legacy routes and new work goes in `app/`. For more on running the agent, see [How to use GitHub Copilot CLI: a step-by-step guide](/en/blog/how-to-use-copilot-cli/).

## Run a tight loop of plan, change, test, and review

Start with a small, well-defined task, not a vague feature request. Ask the agent to inspect the relevant files first, then make the change, then run the specific tests you name. After it finishes, review `git diff` before accepting. Do not let it run a full test suite unless the change is large; targeted runs keep the loop fast.

Example prompts for typical Next.js tasks:

- Add a new `/dashboard` route in the App Router that reads the current user from the session and shows a server-rendered list of recent projects. Use the existing auth helper and `prisma` client. Do not add client-side data fetching.
- Convert the `ProductCard` component from a server component to a client component only for the add-to-cart button. Keep the card as a server component and extract the button into a new `AddToCartButton` client component. Run ESLint after.
- Create a route handler at `app/api/projects/route.ts` that handles POST with zod validation and returns a typed JSON response. Add unit tests with Vitest for the validation function.
- Fix the failing Playwright test `checkout.spec.ts`: the checkout button is not visible after adding an item to the cart. Investigate and update the client state and component logic, then run only that spec.
- Refactor the `lib/fetcher.ts` utility to use the native `fetch` with Next.js cache options. Remove the old axios import and update all call sites under `app/` and `components/`.

## Where Copilot CLI shines and where it stumbles with Next.js

GitHub Copilot CLI is good at generating route files, adding API route handlers with validation, splitting server and client components, writing unit tests, and fixing TypeScript or ESLint errors. It is less reliable when a change touches Next.js caching semantics, static/dynamic rendering, or middleware. Review those diffs manually.

| Pitfall | What to check in the diff |
|---------|---------------------------|
| Client component imports a server-only module | Look for `"use client"` files that import from `src/lib/server/` or use `server-only`; build will fail. |
| Route handler returns a plain object instead of a `NextResponse` | Check `app/api/**/route.ts` return types; use `NextResponse.json()` with explicit status. |
| Pages Router and App Router files mixed | Verify new files land in the intended router directory; a `pages/api` handler and `app/api` handler can conflict. |
| `useSearchParams` used without a `<Suspense>` boundary | Build output or a Playwright navigation will warn; wrap the component in Suspense. |

If you see one of these patterns, ask for a fix with a specific instruction, not just 'make it work'.

## Verify the agent’s work with your own commands

Always verify the agent’s claim that tests passed. Run the commands yourself in a clean terminal, at least the ones affected by the change. In a Next.js repo, `pnpm build` catches many server/client boundary mistakes and static generation issues that lint alone misses. Use Vitest or Jest for unit and component tests, and Playwright for browser flows. Have the agent run a single failing spec first, then widen. For browser checks, see [AI agent browser testing: let the agent check your app](/en/blog/ai-agent-browser-testing/). After a change, inspect `git diff --stat` and then the full diff; do not accept a large diff without reading it.

## Run parallel agents safely with AgentVera

AgentVera is a desktop app that runs coding agents’ real command line tools side by side, each in its own terminal panel. For a Next.js project, parallel agents in separate git worktrees prevent one experiment from overwriting another, so one agent can prototype an App Router route while another fixes a Pages Router bug. Automatic code review after each turn links findings to file:line, which helps catch client/server import mistakes. Token budgets stop agents from over-running on a complex refactor, and checkpoints let you undo a bad turn instantly.

## Keep the edit loop small and explicit

The agent is most useful when you treat it like a junior developer with good tooling: give clear context, ask for small diffs, and verify every change with the project’s own build, lint, and test commands. With a short instructions file and a review-first loop, GitHub Copilot CLI can handle a large share of routine Next.js work without turning the codebase into a black box.

## Frequently asked questions

**How do I start GitHub Copilot CLI in a Next.js project?** Open a terminal in the project root and run copilot. Describe the change you want. Put project-specific rules in .github/copilot-instructions.md or AGENTS.md so the agent follows your Next.js conventions.

**Can GitHub Copilot CLI handle both App Router and Pages Router?** Yes, but it needs explicit context. State in the instructions file which router is used for new files and where existing pages live. Without that, it may mix conventions and create duplicated or conflicting routes.

**What should I check after Copilot CLI changes Next.js files?** Run the full lint, type/build, and test suite yourself. Review the git diff for server/client boundary violations, route handler response types, and unintended changes to caching or data fetching.

**Does GitHub Copilot CLI understand Next.js server and client components?** It understands the general model, but real projects need reminders. Add a rule to keep server-only imports out of client components and to keep client components as leaf nodes where possible.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/