# opencode for Next.js: A Practical Developer Guide

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

Practical guide to using opencode with Next.js: project setup, AGENTS.md, prompt loops, testing, and avoiding common App Router pitfalls with examples.

**In short:**

- opencode works from the project folder and reads AGENTS.md, so a clear Next.js-specific instruction file keeps it on track.
- Use server components by default, explicit client boundaries, and Next.js-aware prompts for route handlers, caching, and testing.
- Verify every change with lint, unit tests, and Playwright; watch for accidental client boundaries and cache invalidation mistakes.

[opencode](/en/agents/opencode/) runs from your project root and works directly on the filesystem, so it fits Next.js development without extra indirection. It reads project instructions from AGENTS.md, which means you can encode Next.js-specific rules once and keep the agent aligned with your router, component boundaries, and test commands. This guide covers setup, prompt loops, pitfalls, and verification for both App Router and Pages Router work.

## Why opencode fits Next.js development

opencode is a terminal-based coding agent that operates on the repository as a regular developer would: it reads files, edits them, and runs shell commands like `pnpm lint`, `pnpm test`, and `pnpm build`. For Next.js that matters because many changes span multiple files: a data-fetching server component, a client component for interactivity, a route handler for mutation, and a test. opencode can plan and apply those coordinated edits in one session.

One concrete advantage is that opencode respects AGENTS.md, so you can codify "use server components by default" and "do not touch next.config.ts without asking." Another is that it works with whatever model provider you already use, without changing your Next.js toolchain. You still run the same linter, test runner, and build; opencode just drives them.

## Setting up a Next.js project for opencode

Before starting, make sure the repo has clear scripts. Then create or update AGENTS.md in the project root. opencode reads it on startup and uses it as a persistent instruction set, so keep it short but specific. A good AGENTS.md for Next.js includes commands, folder conventions, and rules that prevent common mistakes.

Here is a realistic example:

```md
# AGENTS.md

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Lint: pnpm lint
- Test: pnpm test
- E2E: pnpm test:e2e

## Project layout
- app/ App Router; colocate server components and route handlers.
- components/ shared components; mark client components with "use client".
- lib/ server utilities, data access, auth.
- public/ static assets.
- tests/ Vitest unit and component tests.
- e2e/ Playwright tests.

## Rules
- Use App Router unless the ticket says Pages Router.
- Server components by default; add "use client" only for event handlers, state, or browser APIs.
- Data fetching happens in server components or route handlers; avoid client-side fetch for initial data.
- Use route handlers for mutations and third-party callbacks.
- After mutations, call revalidatePath or revalidateTag instead of force-dynamic.
- ESLint with next/core-web-vitals must pass.
- Run Vitest for unit/component tests and Playwright for user flows before marking work complete.
- Do not change next.config.ts, middleware.ts, or tsconfig.json without asking.
```

This file is enough to prevent many Next.js-specific failures: the agent won’t accidentally turn a pure server component into a client component, and it will use the project’s test commands instead of inventing new ones. If you’re new to opencode, see [How to use opencode: a step-by-step guide](/en/blog/how-to-use-opencode/).

## A practical working loop

Work with opencode the same way you would with a thoughtful colleague: agree on the contract, let it implement in small steps, run checks, and review the diff. A loop that works well:

1. Start with the desired behavior and acceptance criteria.
2. Ask opencode to inspect the relevant files and propose a plan, not code yet.
3. Approve the plan, then ask for a minimal implementation.
4. Have it run the relevant linter and tests.
5. Review `git diff` yourself before committing.

Example prompts for typical Next.js tasks:

- "Add a server component that fetches the latest posts from the database and renders them as cards; keep the card a server component and use a separate client component only for the save button."
- "Create a route handler at /api/contact that validates JSON with Zod, sends email, and returns { ok: true } or a structured error."
- "The settings form currently reloads the page. Convert the form to use a server action, then call revalidatePath('/settings') after the update."
- "Write a Playwright test for the checkout flow using the existing fixtures; mock the payment provider in the test environment."
- "Refactor the dashboard from a single page to parallel routes with loading.tsx boundaries, and keep the sidebar shared."

These prompts give opencode enough Next.js context to choose the right primitives without micromanaging every line.

## What opencode handles well and where to watch closely

opencode is strong at boilerplate-heavy Next.js work: route handlers, server actions, data fetching functions, and component splits. It can also add loading.tsx, error.tsx, and not-found.tsx boundaries in the right places. It usually respects existing folder conventions when they are in AGENTS.md.

Watch it closely in these areas:

- Client/server boundaries: opencode may add `"use client"` to a component that uses server-only imports, or put a client component in a server-only module. Ask for a diff review after every change.
- Caching and revalidation: Next.js caching behavior is subtle. opencode might add `export const dynamic = 'force-dynamic'` when a `revalidatePath` would be enough, or forget to invalidate after a mutation.
- Route handler signatures: In App Router, route handlers use `export async function GET(request: Request)`; opencode may revert to Pages Router style `req, res` if context is unclear. Spell out the router in the prompt.
- Metadata and SEO: It may import `metadata` from the wrong segment or place it in a client component. Remind it that metadata must be in a server component.

Use this table as a quick reference:

| Task | Good prompt | Pitfall to check |
|------|-------------|------------------|
| Data fetching | "Fetch posts in a server component and pass only serializable props to the client card." | Client component gets a Date or function prop. |
| Mutations | "Use a server action in app/settings/actions.ts and revalidatePath('/settings')." | Forgetting revalidation leaves stale UI. |
| Route handler | "Create app/api/webhook/route.ts with POST, verify signature, return 200." | Pages Router style `(req, res)` instead of Web Request. |
| Testing | "Write a Playwright test for signup using existing test helpers." | Test bypasses auth fixture and fails in CI. |

## Testing and verification

opencode can run the project’s scripts, but you should define exactly what "done" means. Minimum for a Next.js change:

- `pnpm lint` must pass with the project’s ESLint config, including next/core-web-vitals.
- `pnpm test` or `pnpm test:unit` runs Vitest/Jest for logic and component tests.
- `pnpm test:e2e` runs Playwright against a local build when UI flows changed.

Ask opencode to run these commands after each step, not just at the end. If a test fails, have it read the failure, fix only that, and rerun the single test when possible. For Playwright, use the existing test fixtures and auth setup instead of having opencode invent login steps. Also verify the production build when server/client boundaries changed, because Next.js catches some issues only during `next build`, not in dev.

A typical verification prompt: "Run pnpm lint, pnpm test, and pnpm build. If something fails, fix the smallest part and rerun only the failed check." This keeps the agent from making large speculative edits after a red build.

## Running several agents with AgentVera

AgentVera runs real command line agents like opencode side by side in one desktop window, each in its own terminal panel. For a Next.js project, the useful parts are [parallel work in separate git worktrees](/en/blog/best-tools-parallel-ai-coding-agents/), so one agent can work on a route handler while another updates a client component without overwriting files; automatic code review that links findings to file:line, which catches missing `revalidatePath` or bad client/server splits; and checkpoints that let you undo a broken session and replay steps. Token budgets per agent, turn, and day also keep spending predictable when you run several agents on one repo.

## Wrapping up

opencode becomes a reliable Next.js pair programmer when you put the project’s rules in AGENTS.md, use small prompts that name the router and component boundary, and verify every change with lint, unit tests, and Playwright. Watch the diff for client/server mistakes and cache invalidation, and the agent will handle most of the boilerplate while you focus on product logic.

## Frequently asked questions

**How do I start opencode with a Next.js project?** Run opencode in the project folder. It reads AGENTS.md for instructions, so make sure that file exists with your build, test, and lint commands; then describe the Next.js change you want in plain English.

**What should AGENTS.md contain for opencode and Next.js?** Include commands for install, dev, build, lint, test, and e2e; the project folder layout; and rules like server components by default, when to use client components, and when to call revalidatePath. Keep it concise and update it when the project changes.

**Can opencode edit both server and client components correctly?** Yes, if you give clear boundaries. Put the client/server rules in AGENTS.md and name the component type in the prompt, then review the diff for accidental "use client" additions or server-only imports in client components.

**How do I get opencode to run tests on a Next.js project?** Tell it to run the exact scripts from AGENTS.md, such as pnpm lint, pnpm test, and pnpm test:e2e. Ask it to fix failures one at a time and rerun only the failing test when 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/