opencode NestJS: practical guide for coding agents

Start by running opencode in the root of your NestJS project and tell it what you want changed. opencode reads project instructions from AGENTS.md, so a well-prepared NestJS repo makes the agent much more effective. This guide covers a practical working loop, prompts, testing, and the NestJS-specific spots to watch.

Why opencode suits NestJS development

NestJS has a highly regular shape: modules, controllers, providers, DTOs, pipes, guards. That regularity is exactly what a terminal coding agent can use to make safe changes without guessing. opencode can read the existing module graph, follow your injection patterns, and produce new modules that match current conventions instead of generic examples. It also works well with class-validator DTOs and the Nest CLI layout because those are deterministic. When the project already has TypeORM or Prisma setup, opencode can extend entities, repositories, and PrismaService methods by finding existing patterns.

Preparing AGENTS.md for a NestJS repository

Keep a single AGENTS.md at the repo root. It should be command-first: exact build, test, lint, and e2e commands, folder conventions, module and provider rules, and DTO rules. Do not write a long essay; write constraints that prevent common NestJS mistakes. For the general setup of opencode, see How to use opencode: a step-by-step guide.

# AGENTS.md for NestJS

## Commands
- Install: npm ci
- Build: npm run build
- Unit tests: npm test -- --runInBand
- E2E tests: npm run test:e2e
- Lint: npm run lint
- Format check: npm run format:check

## Layout
- Keep one NestJS module per folder under `src/modules/<name>/`.
- Controllers only handle HTTP status and DTO mapping; business logic goes in services.
- Use `@nestjs/config` for secrets, never hard-code them.

## DTO rules
- All request DTOs must use `class-validator` decorators.
- Use `@IsString()`, `@IsEmail()`, `@IsOptional()`, `@IsInt()`, `@Min()`, `@Max()`, etc.
- Do not allow properties without validation unless another DTO explicitly extends them.
- Use `@Transform` from `class-transformer` only when needed for query parsing.

## Providers and modules
- Export a provider only if another module imports it.
- Avoid circular module references; split shared code into common modules.
- Use custom repository classes for TypeORM instead of injecting raw `Repository` everywhere.

## Testing
- Unit tests live next to the service in `*.spec.ts`.
- E2E tests go under `test/` and use the full application module.
- Mock repositories with `createMock<Repository<T>>()` helpers only if already present.

## Rules
- Do not generate code outside `src/` unless asked.
- Do not change existing module public APIs without a note in the diff.
- When adding Prisma calls, use the existing `PrismaService` from `PrismaModule`.

A step-by-step workflow for NestJS changes

Use small, verifiable steps. Let opencode propose a diff, review it, run the commands from AGENTS.md, and ask it to fix any failures. For NestJS, a safe loop is: plan the module boundary; generate only the module, controller, service, DTO, and tests; run unit tests; run e2e tests; review the diff. If the agent changes module imports, double-check the module graph.

Example prompts that work well:

• Create a UsersModule under src/modules/users with UsersController, UsersService, CreateUserDto, and UpdateUserDto. Use class-validator decorators matching the existing DTO style. Return typed service methods and keep the controller thin.
• Add global ValidationPipe with whitelist: true and transform: true in main.ts. If existing e2e tests expect invalid payloads to pass, update them to expect 400.
• Write unit tests for UsersService using Jest. Mock UsersRepository with a small in-memory helper. Cover create, findOne, update, and not-found cases.
• Add a PostsModule that uses Prisma through the existing PrismaService. Create CreatePostDto, UpdatePostDto, and paginated GET /posts with take and skip query DTOs. Add e2e tests for list and create.
• Refactor AuthModule to use ConfigService for the JWT secret and expiration. Add JwtStrategy and JwtAuthGuard, and export the guard from AuthModule.

Where opencode excels and where to watch it in NestJS

Scaffolding a resource, adding DTO validation, wiring providers, and writing tests are all strong fits. The table below shows where to be careful.

The agent often produces syntactically correct NestJS code, but the module graph and DI wiring are where a wrong change still compiles and fails at runtime or in e2e tests. Always inspect @Module imports and exports before accepting a larger refactor.

Testing and verifying NestJS changes with opencode

Make the agent run the exact project commands before declaring a task done. For NestJS, npm test -- --runInBand catches most DI and mock issues; npm run test:e2e catches module wiring, pipes, guards, and HTTP status bugs. Ask opencode to update tests when it changes a controller or service signature. If a test hangs, check for unresolved timers or Prisma connections and have the agent add afterAll hooks. Run npm run build to verify TypeScript and decorator metadata, and npm run lint to catch unused injections and bad imports before review.

Parallel opencode agents on a NestJS project with AgentVera

AgentVera is a desktop app that runs opencode and other coding agents side by side in real terminal panels. For a NestJS repo, the most useful bits are parallel worktrees, automatic code review, and checkpoints. You can put one agent on UsersModule, another on PostsModule, and they won’t overwrite each other because each can work in its own git worktree. When a turn ends, a second model reviews the diff and links findings to file:line, which catches missed @Module exports or DI mistakes. Checkpoints let you undo a bad refactor instantly and replay the step. See Best tools to run AI coding agents in parallel (2026).

Final thoughts on using opencode with NestJS

opencode works best in NestJS when the repo already encodes its conventions in AGENTS.md and the agent is asked to make one module-scale change at a time. Keep the loop tight: prompt, run unit and e2e tests, review the diff. If you delegate several modules at once, use separate worktrees and a review step to avoid crossing DI boundaries. The result is a coding agent that respects NestJS structure instead of fighting it.