Dev

Cursor Composer: Refactor an Entire Project at Once

Back to Tutorials

I recently tested Cursor Composer on a messy legacy Node.js backend. Instead of editing files one by one and constantly context switching, I realized I could give Cursor instructions to overhaul multiple files simultaneously. Here's how I did it and the workflow I found to be the most effective.

The Power of Multi-File Edits

Standard AI coding assistants are great for single files, but when you need to change an API signature, you often have to touch a controller, a service, a route file, and several test files. Composer solves this by understanding your entire workspace.

My Composer Workflow

Before doing a massive refactor, I always make sure my git working tree is clean. If Composer messes up, I want an easy way out.

1. Select Context with Precision

I press Ctrl+I (or Cmd+I on Mac) to open Composer. Then, I explicitly tag the files I want it to focus on. While Composer can search the codebase, giving it specific files reduces hallucinations drastically.

@src/controllers/userController.js
@src/services/userService.js
@tests/userService.test.js

Task: We are migrating from standard callback-based database queries to async/await using Prisma. Refactor all methods in the user service to use Prisma, update the controller to handle async errors, and fix the corresponding tests.

2. Reviewing the Diff

Composer will generate a multi-file diff. This is where you need to be careful. I never hit "Accept All" blindly. I review file by file. For instance, I noticed Composer sometimes removes custom error classes if they aren't explicitly referenced in the prompt. I just reject that specific file chunk and prompt it to retain the error class.

Real-World Example: Migrating to TypeScript

I used Composer to kickstart a TypeScript migration. Here is the prompt I used to convert a large React component and its CSS module:

@Button.jsx
@Button.module.css

Convert Button.jsx to Button.tsx.
Add TypeScript interfaces for the props, ensuring `variant` is constrained to 'primary' | 'secondary'.
If any CSS class is missing from the module, create it.

The result was a perfectly typed component in seconds. Composer automatically renamed the file, added the interfaces, and wired it up correctly.

Gotchas I Found

  • Keep changes focused: Don't try to rewrite the entire architecture in one prompt. Stick to logical boundaries.
  • Context limits: If you tag 20 files, the model might get confused or output truncated code. I try to limit my Composer sessions to 3-5 heavily related files.