Codex is most useful in a Next.js project when you give it the project-specific context it needs and then run it in short, verification-heavy loops. It can generate App Router routes, server actions, route handlers, client boundaries, and Playwright specs, but the output is only safe when you review server/client boundaries and run the build. This guide covers setup, prompts, testing, and parallel execution for App Router and Pages Router work. If you are new to the CLI itself, How to use Codex CLI: a step-by-step guide covers the basics.
Why Codex fits Next.js work
Codex is not a black-box generator; it is an agent that reads files, follows AGENTS.md, runs commands, and iterates on command output. That is exactly what Next.js work needs because many Next.js errors come from file placement and build-time rules rather than from logic. An agent that can run npm run lint, npx tsc —noEmit, npm run test, and npm run build can catch and fix the mechanical issues itself: a missing ‘use client’, a server-only import in a client component, a route handler that returns an improper shape, or a next/link misuse.
It also works well for cross-file refactors. When you change a data-fetching pattern or rename a route parameter, Codex can update imports, tests, and route files together. The main constraint is that you must be explicit about whether the project uses App Router or Pages Router, because the two have different directories and data-fetching rules. Codex can handle either one, but mixing instructions without context leads to generated files in the wrong place.
Setting up the project for Codex
Start codex in the project root, not in a subdirectory, so it sees package.json, next.config, and AGENTS.md. The most important file is AGENTS.md at the repository root; Codex reads it as persistent project instructions. Keep it short and command-focused. For a Next.js project, it should list build, test, lint, and typecheck commands; describe the router and folder conventions; and state the rules that prevent the most common mistakes.
# AGENTS.md
## Commands
- Install: npm install
- Dev: npm run dev
- Build: npm run build
- Lint: npm run lint
- Typecheck: npx tsc --noEmit
- Unit tests: npm run test
- E2E tests: npm run test:e2e
## Folders
- App Router project: use app/ for routes, layouts, and pages; no pages/ directory.
- Reusable components live in components/.
- Server utilities live in lib/.
- Server actions live in app/actions/.
- Route handlers live in app/api/.
## Next.js rules
- Components are server components by default; add 'use client' only when needed.
- Do not import server-only modules or Node APIs into client components.
- Use next/link for internal navigation and next/image for images.
- Route handlers export only HTTP methods such as GET, POST, PUT, or DELETE.
- After a mutation, call revalidatePath or revalidateTag instead of relying on cache.
- Metadata exports stay in server components or layout files.If the project uses Pages Router, change the folder conventions to pages/ and pages/api/, and add rules for getServerSideProps and getStaticProps. The example above is for an App Router project, but the structure is the same: commands first, then folders, then Next.js-specific rules.
A working loop that keeps Next.js changes safe
Use plan, small step, verify, review. First ask Codex to read AGENTS.md, package.json, and relevant route files. Then ask for one change, not a whole feature. After each step, run lint, typecheck, and the test subset. Review the diff before moving on. Typical prompts:
- ‘Read AGENTS.md and the current app directory, then propose a three-step plan for adding a contact form with a server action.’
- ‘Create app/contact/page.tsx as a server component with a form that calls a server action in app/actions/contact.ts. Validate input with zod and call revalidatePath after success.’
- ‘Add a Vitest test for the contact server action and run npm run test; fix only failures caused by the new test.’
- ‘Run npm run lint and npx tsc —noEmit, then correct any issues you introduced.’
- ‘Summarize the git diff and identify any file that should be a client component but currently is not, or that should be server-only but is not.’
Tasks Codex handles well and where to watch closely
The table shows where Codex is reliable and what to inspect before accepting a change.
| Task | What Codex handles well | Watch closely |
|---|---|---|
| App Router route creation | Creates page, layout, loading, and error files in app/ with correct exports | Combining app/ and pages/ routers, missing async searchParams, wrong metadata placement |
| Server actions | Writes async server actions with form validation and revalidation | Putting ‘use server’ at the wrong level or using server actions in client event handlers without a form |
| Route handlers | Adds app/api/…/route.ts with typed responses and status codes | Caching defaults, missing dynamic behavior, using Node APIs that do not run on edge runtime |
| Client components | Adds ‘use client’ and isolates interactive islands | Making everything client-side, importing server-only code, or passing non-serializable props |
| E2E specs | Writes Playwright navigations, form submissions, and hydration checks | Hard-coded selectors, port conflicts, starting the dev server incorrectly, too broad assertions |
The most common Next.js-specific failures to review are server/client boundary violations, hydration mismatches from using Date.now or Math.random during render, and missing revalidation after mutations. Codex may also choose a suboptimal caching strategy, so check route handler and fetch behavior against your intended freshness. Keep next/image for optimized images and next/font for fonts; do not accept plain <img> tags in Next.js components unless there is a deliberate reason. For Pages Router work, tell Codex explicitly which data-fetching method to use and where to put getServerSideProps or getStaticProps, because the agent will not always infer it from context.
Testing and verification with Codex
Make npm run build the final gate for every change. In Next.js, the production build catches type errors, ESLint issues, and many server/client boundary problems that dev mode does not. Before accepting a Codex diff, run:
- npm run lint
- npx tsc —noEmit
- npm run test
- npm run build
- npm run test:e2e for route-level or browser-level changes
Codex can run these commands itself and fix issues it introduced, but keep the loop small so a failed build points to one decision. For Playwright, configure webServer in playwright.config to start npm run dev or npm run build && npm run start, and ask Codex to use semantic selectors or data-testid attributes instead of brittle CSS paths. Unit tests for server actions and route helpers give the best return on effort because those functions can be tested without a browser.
When Codex edits a server action, ask it to add a test covering empty input, invalid input, and a successful mutation with revalidation. When it edits a client component, run the existing component test suite or at least the build to catch imports that leak between server and client. If you use Jest instead of Vitest, keep the same principle: the agent should run the project’s chosen runner from AGENTS.md and not introduce a second test setup.
Running several agents on one Next.js project with AgentVera
AgentVera is a desktop app that runs coding agents’ real command line tools side by side in one window, each in its own real terminal panel. For Next.js work, the most useful facts are that many agents can work in parallel in their own git worktrees, so route, server action, and test changes do not overwrite each other; automatic code review after each turn catches server/client boundary and hydration mistakes; and checkpoints let you undo a bad refactor or replay a turn step by step. This is especially helpful when one agent works on a route handler while another updates Playwright specs. AI code review: check what your agents write explains the review loop.
Wrap-up
Codex is not a replacement for understanding Next.js; it is a force multiplier when you give it precise project context and enforce a tight verify loop. Keep AGENTS.md current, use small prompts, run the full build, and review the diff with server/client boundaries in mind. With that discipline, Codex can handle a large share of route, action, and test work in both App Router and Pages Router projects.