GitHub Copilot CLI and Next.js: Practical Agent Workflow

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 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:

# 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.

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.

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. 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.