Cursor Multi-Repo
Work with multiple repositories and monorepo structures in Cursor. Covers multi-root workspaces, selective indexing, cross-project context, and rule inheritance patterns.
Multi-Root Workspaces
Open multiple project roots in a single Cursor window:
Creating a Workspace
- Open first project:
File > Open Folder > select project A
- Add second project:
File > Add Folder to Workspace... > select project B
- Save workspace:
File > Save Workspace As... > mywork.code-workspace
Workspace File Structure
{
"folders": [
{ "path": "/home/dev/api-service" },
{ "path": "/home/dev/web-frontend" },
{ "path": "/home/dev/shared-lib" }
],
"settings": {
"editor.tabSize": 2,
"files.exclude": {
"**/node_modules": true,
"**/dist": true
}
}
}
Open workspace: cursor mywork.code-workspace or double-click the file.
How Indexing Works with Multi-Root
- Each folder root is indexed independently
@Codebase searches across all open roots@Files paths include the root name: @api-service/src/routes/users.ts- Closing a folder removes it from the index
Monorepo Patterns
Opening Full Monorepo
cursor /path/to/monorepo
Pros: @Codebase searches everything, cross-package references work naturally
Cons: Slow indexing on large monorepos, lots of irrelevant search results
Focused Opening (Recommended)
cursor /path/to/monorepo/packages/api
Pros: Fast indexing, focused search results
Cons: No automatic cross-package context
Hybrid: Focused + Selective .cursorignore
cursor /path/to/monorepo
# .cursorignore at monorepo root
# Only index packages you're actively working on
# Exclude everything in packages/
packages/*/
# Except the ones you want indexed:
!packages/api/
!packages/shared/
# Always exclude
node_modules/
dist/
build/
.turbo/
This indexes only packages/api/ and packages/shared/, keeping search focused.
Cross-Project Context
Referencing Files Across Roots
In a multi-root workspace, use the root folder name as prefix:
@api-service/src/types/user.ts @web-frontend/src/hooks/useAuth.ts
The User type in the API doesn't match the frontend hook.
Show me the differences and suggest how to share the type.
Sharing Types Between Projects
Use project rules to guide cross-project imports:
---
description: "Monorepo import conventions"
globs: ""
alwaysApply: true
---
- Shared types: import from @myorg/shared (never relative paths across packages)
- Shared UI: import from @myorg/ui
- Never import directly from another app package (apps/api → apps/web is forbidden)
- Each package declares its own dependencies in package.json
Rules Inheritance
Monorepo: Root + Package Rules
monorepo/
├── .cursor/rules/
│ ├── global.mdc # alwaysApply: true (applies everywhere)
│ └── security.mdc # alwaysApply: true
├── packages/
│ ├── api/
│ │ └── .cursor/rules/
│ │ └── api-patterns.mdc # Scoped to api/ files
│ ├── web/
│ │ └── .cursor/rules/
│ │ └── react-patterns.mdc # Scoped to web/ files
│ └── shared/
Behavior:
- Root rules apply to all files in the monorepo
- Package-level rules apply only when editing files in that package
- If both match, both are included in context
Multi-Root: Independent Rules
In a multi-root workspace, each root has its own .cursor/rules/:
# Workspace contains:
api-service/
.cursor/rules/express-patterns.mdc # Only applies to api-service files
web-frontend/
.cursor/rules/react-patterns.mdc # Only applies to web-frontend files
Rules do NOT cross workspace roots. Each project's rules are independent.
Selective Indexing Strategies
Strategy 1: Single Package Focus
cursor packages/api/
Strategy 2: Related Packages
# .cursorignore at monorepo root
packages/*/
!packages/api/
!packages/shared/
!packages/config/
Strategy 3: Full Monorepo with Heavy Exclusions
# .cursorignore
node_modules/
dist/
build/
.turbo/
.next/
coverage/
*.lock
*.min.js
**/*.test.ts # Optional: exclude tests from indexing
**/fixtures/ # Test fixtures
**/migrations/ # Database migrations (reference via @Files)
Performance Optimization
Memory Management
Each open workspace root consumes memory for indexing. Minimize open roots:
# Instead of opening 5 repos:
cursor repo1/ repo2/ repo3/ repo4/ repo5/ # Heavy
# Open only what you need:
cursor repo1/ # Light
# Add repo2/ only when needed via File > Add Folder
Large Monorepo Tips
1. Use .cursorignore aggressively
2. Open specific packages, not the root
3. Close workspace folders you're not actively editing
4. Start new chats when switching between packages
5. Use @Files for cross-package references instead of @Codebase
Enterprise Considerations
- Repository access: Multi-root workspaces respect filesystem permissions. Cursor cannot index repos the user cannot read.
- Indexing scope: Only open workspace folders are indexed. Opening a shared drive or network mount may be slow.
- Rule governance: In monorepos, root-level rules serve as team-wide governance. Package-level rules add specificity.
- CI alignment:
.cursor/rules/ should be reviewed in PRs like any other configuration change.
Resources
