Cursor Agent NestJS: Practical Setup and Workflow

Cursor Agent is the terminal coding agent from Cursor. You start it in a NestJS repository by running cursor-agent in the project folder. This guide shows how to prepare a NestJS codebase, give useful instructions, iterate safely, verify tests, and run several agents in parallel.

Why Cursor Agent fits NestJS development

Cursor Agent is effective for NestJS because NestJS code is highly structural. A feature change usually touches a module file, a controller, one or more providers, DTOs, and a spec. The agent can inspect the existing module graph, follow the established naming, and create all files in one pass. The framework’s decorators and TypeScript types also give the model enough context to avoid many framework errors: it can see @Injectable, @Controller, @Module, constructor parameters, and class-validator annotations before editing. Because the agent runs in the terminal, it can execute Jest, ESLint, and the TypeScript compiler, so it can verify that its NestJS changes actually compile and pass the unit tests instead of guessing.

Prepare a NestJS repo for Cursor Agent

Put project-specific instructions in AGENTS.md at the repo root or in .cursor/rules. For a NestJS project, the agent needs the exact npm commands, the folder layout, and constraints that prevent it from breaking DI or validation.

# NestJS project rules

## Commands
- Install: `npm ci`
- Build: `npm run build`
- Lint: `npm run lint`
- Unit and integration tests: `npm run test`
- E2E tests: `npm run test:e2e`

## Layout
- `src/main.ts` bootstraps the app and loads global pipes/filters.
- `src/config/` contains environment validation and configuration.
- `src/modules/<feature>/` contains one module per feature.
- Each module folder has `<feature>.module.ts`, `<feature>.controller.ts`, `<feature>.service.ts`, `dto/`, and spec files.
- Shared code lives in `src/common/` and must not import feature modules.

## Rules
- One class per file. File names kebab-case, class names PascalCase.
- Use constructor injection with `private readonly` fields; do not use property injection.
- Keep controllers thin; put business logic in providers.
- Validate request bodies with class-validator DTOs. The global `ValidationPipe` is already enabled in `main.ts`; do not disable it.
- Return DTOs or mapped objects from controllers, never TypeORM or Prisma entities directly.
- Do not import `UsersModule` into `OrdersModule` just to use one service; export the provider from `UsersModule` or use a shared module.
- Avoid circular module dependencies. If needed, use `forwardRef()` only after confirmation.
- When changing any DTO or entity, update the corresponding spec file and run tests.

Keep the file short enough that it is read as context on every request. If the project uses Prisma, replace the TypeORM rules with Prisma-specific rules such as prisma generate, prisma migrate dev, and the schema file location.

How to run a safe change loop

Launch cursor-agent from the root and give it one focused task at a time. Do not ask for a giant refactor in one prompt. The loop that works best:

1. Ask for a plan before code. Say which files you expect it to touch and any constraints.
2. Have the agent implement one module, DTO change, or test at a time.
3. Immediately run npm run lint, npm run test, and npm run build after each change.
4. Review the diff before continuing. Look at module imports/exports, injection tokens, and validation pipes.
5. If a test fails, let the agent inspect the failure output and propose the smallest fix.

Example prompts for typical NestJS tasks:

• In src/modules/users, add UpdateUserDto with class-validator rules for email, name, and role. Add a PATCH endpoint in UsersController, update UsersService, and add Jest tests. Do not change the database schema.
• Enable global ValidationPipe with transform: true, whitelist: true, and forbidNonWhitelisted: true in main.ts. Then run lint and unit tests.
• Find all controllers that return a User entity directly. Create a UserResponseDto and map the entity to it. Keep all existing tests passing and add coverage for the mapping.
• Add a PostsModule that imports TypeOrmModule.forFeature([Post]), a PostsService, and a PostsController with create and list endpoints. Include DTOs and Jest unit tests.
• Prisma is used here. Add a Comment model with a relation to Post, generate migration, expose comments under GET /posts/:id/comments, and update affected tests.

Where Cursor Agent excels and what to verify

Cursor Agent handles the grunt work of NestJS well: generating modules, controllers, services, DTOs with class-validator, Jest unit tests, TypeORM or Prisma repository wiring, and pipes, filters, or interceptors. It is good at following existing naming conventions and refactoring repetitive code.

Watch it closely in these NestJS-specific areas:

• Module boundaries: the agent may import a module that does not export the required provider, or create circular imports. Always check imports, exports, and providers.
• DI registration: a new service must be in the right module’s providers array. Missing this is a common silent failure.
• Validation: class-validator decorators do nothing unless a global ValidationPipe is active. The agent may add DTO decorators but forget to enable or configure the pipe.
• Entity leakage: controllers may return ORM entities, which can leak password hashes or trigger JSON serialization issues. Check for DTO mapping.
• Decorator metadata: @Body, @Param, and @Query with wrong types or missing DTO classes can break validation and OpenAPI types.
• Configuration: agents sometimes hard-code env vars in services instead of using ConfigService or validation schemas.
• E2E setup: need correct test module configuration; otherwise tests pass or fail for the wrong reasons.

Testing and validation with Cursor Agent

Testing is the agent’s main feedback signal. Require the agent to run npm run test after every meaningful change. For NestJS, focus on three levels:

• Unit tests with Jest: mock injected providers with jest.fn() or use Test.createTestingModule.
• E2E tests with supertest: boot the app with the same modules and pipes as production; verify status codes and response shapes.
• Build and lint: npm run build and npm run lint catch TypeScript and decorator issues before runtime.

Give the agent the exact test command. Ask it to run a single spec file while iterating: npx jest src/modules/users/users.service.spec.ts --runInBand. Do not use watch mode inside the agent session because it blocks. When a test fails, ask for the failure output and the smallest fix, then require the full suite to pass. Check that new DTO tests cover both valid and invalid payloads. If the project uses TypeORM or Prisma, confirm the agent did not change the database schema unless asked; review generated migrations carefully.

Running several agents on one NestJS repo 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 NestJS codebase, the most useful parts are parallel agents in separate git worktrees, automatic code review when a turn ends, and Git and GitHub integration for commits and pull requests. Because NestJS work often touches multiple modules, you can let one agent work on users and another on posts without file conflicts. Code review helps catch missing providers, parameter decorators, and validation pipe mistakes. The parallel coding agents guide describes this workflow.

Final notes

Cursor Agent becomes a practical NestJS pair programmer when the repository has clear rules, tasks stay small, and every change is verified with Jest, ESLint, and TypeScript. Start with cursor-agent in the project root, keep AGENTS.md current, and watch module boundaries, DI, and validation pipes. For more on the CLI itself, see How to use Cursor CLI: a step-by-step guide. Over time, the agent will follow your module conventions and produce diffs that are safe to merge.