# How to Use Cursor in a Monorepo

- Tool: Cursor
- Difficulty: Advanced
- Time required: 15-20 min
- Compatibility: Cursor Pro+, any monorepo tool (Turborepo, Nx, Lerna, pnpm workspaces)
- Last updated: March 2026

## TL;DR

Use Cursor effectively in a monorepo by configuring .cursorignore to exclude irrelevant packages, opening separate Cursor windows for different sub-projects, using @folder and @file to scope context precisely, and creating per-package .cursor/rules/ that auto-attach. Strategic context management prevents the AI from filling its context window with irrelevant code.

## Managing Cursor's Context in Large Monorepos

Monorepos with hundreds of thousands of files overwhelm Cursor's indexing and context window. When the AI has too much context, it becomes slow, inaccurate, and expensive. The core principle is: only send the model what it truly needs, in the sparsest form possible. This tutorial covers every technique for taming Cursor in large codebases: aggressive file exclusion, separate windows, strategic context scoping, and per-package rules.

## Before you start

- Cursor Pro or Business (needed for larger context windows)
- A monorepo with multiple packages or services
- Understanding of your monorepo's package structure
- Git initialized with proper .gitignore

## Step-by-step guide

### 1. Configure aggressive .cursorignore exclusions

Create a comprehensive .cursorignore that excludes build artifacts, dependencies, and unrelated packages from Cursor's indexing. Cursor indexes all files not in .gitignore or .cursorignore. In a monorepo, most packages are irrelevant to your current task.

```
# .cursorignore — Monorepo exclusions

# Dependencies (critical — these can be millions of files)
node_modules/
.pnpm-store/
vendor/

# Build outputs
dist/
build/
.next/
.turbo/
.nx/
coverage/

# Generated files
__generated__/
*.min.js
*.bundle.js
*.d.ts.map

# Large data files
*.csv
*.sql.gz
fixtures/large/

# Unrelated packages (uncomment when focused on specific packages)
# packages/legacy-app/
# packages/docs-site/
# packages/admin-dashboard/
```

> Pro tip: Use .cursorindexingignore instead of .cursorignore for packages you occasionally need. They are excluded from search but still accessible via explicit @file references.

**Expected result:** Cursor's indexing is limited to relevant source files, dramatically improving performance and context quality.

### 2. Open separate Cursor windows for sub-projects

For large monorepos, open separate Cursor windows rooted at the package level rather than the monorepo root. Each window indexes independently and has its own context scope. This is the single most effective technique for monorepo performance.

```
// Open terminal and launch Cursor for specific packages:
// cursor packages/frontend/
// cursor packages/backend-api/
//
// Each window:
// - Has its own independent index
// - Only sees files in that package
// - Loads .cursor/rules/ from that package
// - Does not waste context on other packages
//
// To reference shared packages, use @file with relative paths:
// @../../packages/shared/types/user.ts
```

> Pro tip: Create shell aliases for your most-used packages: alias cf='cursor packages/frontend/' and alias cb='cursor packages/backend-api/'

**Expected result:** Each Cursor window operates on a smaller codebase with faster indexing and more relevant AI suggestions.

### 3. Use precise @context scoping in prompts

In monorepo prompts, never use @codebase which searches the entire project. Instead, use @folder to scope searches to specific packages and @file for precise file references. This keeps context focused and prevents irrelevant code from consuming the context window.

```
// BAD — searches entire monorepo:
// @codebase How does our auth system work?

// GOOD — scoped to specific package:
// @packages/backend-api/src/auth/ How does our auth system work?

// BEST — precise file references:
// @packages/backend-api/src/auth/authService.ts
// @packages/shared/types/auth.ts
// Explain how the auth service validates JWT tokens.
```

> Pro tip: When you must search broadly, use Chat (Cmd+L) in Ask mode first to identify the relevant files, then reference those specific files in a follow-up Composer session.

**Expected result:** AI responses are faster and more accurate because context is limited to relevant files.

### 4. Create per-package auto-attaching rules

Place .cursor/rules/ directories inside each package with rules specific to that package's technology, conventions, and dependencies. These rules auto-attach based on file location, ensuring the correct context regardless of which monorepo window you use.

```
---
description: Frontend package context
globs: "packages/frontend/**"
alwaysApply: false
---

- Framework: Next.js 15 with App Router
- UI: shadcn/ui + Tailwind CSS
- State: Zustand for client state, React Query for server state
- Types: import shared types from @company/shared-types
- Tests: Vitest + React Testing Library
- Do NOT import from packages/backend-api/ directly — use API client
- API client: packages/frontend/src/lib/api.ts
```

**Expected result:** Package-specific rules auto-attach when editing files in that package.

### 5. Use Notepads for cross-package architecture context

Create Cursor Notepads for architectural documentation that spans multiple packages. Notepads serve as reusable context containers that you reference with @notepad-name when working on cross-cutting concerns. This is more efficient than loading multiple package files.

```
// Create a Notepad in Cursor (Ctrl+Shift+J or via sidebar):
// Name: monorepo-architecture
//
// Content:
// ## Package Dependencies
// frontend → shared-types, api-client
// backend-api → shared-types, database
// workers → shared-types, database, queue
//
// ## Shared Contracts
// API types: packages/shared-types/src/api/
// Database models: packages/shared-types/src/models/
// Event types: packages/shared-types/src/events/
//
// ## Inter-Package Communication
// Frontend → Backend: REST API via api-client package
// Backend → Workers: Message queue (BullMQ)
// Workers → Backend: Database writes + event bus

// Reference in prompts:
// @monorepo-architecture Generate a new API endpoint...
```

> Pro tip: Notepads persist across sessions and are referenced on demand with @notepad-name. They are ideal for architecture context that does not change frequently.

**Expected result:** Cross-package context is available on demand without loading large file trees into the context window.

## Complete code example

File: `.cursorignore`

```gitignore
# ===========================================
# Monorepo .cursorignore
# Only index source code relevant to current work
# ===========================================

# Dependencies — CRITICAL for monorepo performance
node_modules/
.pnpm-store/
.yarn/
vendor/

# Build and cache
dist/
build/
.next/
.turbo/
.nx/
.cache/
coverage/
.eslintcache

# Generated files
__generated__/
*.min.js
*.min.css
*.bundle.js
*.chunk.js
*.d.ts.map
src/**/*.generated.ts

# Large data files
*.csv
*.sql.gz
*.sqlite
fixtures/large/
seeds/data/

# DevOps (move to .cursorindexingignore if sometimes needed)
terraform/.terraform/
terraform/state/
helm/charts/

# Package-specific exclusions
# Uncomment packages you are NOT working on:
# packages/legacy-app/
# packages/docs-site/
# packages/mobile-app/
# packages/admin-panel/

# Logs and temp
logs/
tmp/
*.log
```

## Common mistakes

- **Using @codebase in a monorepo** — @codebase searches the entire indexed repository. In a monorepo with thousands of files, this fills the context window with irrelevant code and produces slow, inaccurate results. Fix: Use @folder scoped to the specific package or @file for precise references. Save @codebase for small, focused projects only.
- **Opening the monorepo root as a single Cursor window** — Cursor indexes everything in the window. A monorepo root with 400K+ files causes 7+ hour indexing, high memory usage, and poor AI suggestions. Fix: Open separate Cursor windows for each active package: cursor packages/frontend/ and cursor packages/backend/.
- **Not updating .cursorignore as focus shifts between packages** — Static ignore rules may exclude packages you need later. Context requirements change as you move between different monorepo tasks. Fix: Comment/uncomment package exclusions in .cursorignore as you shift focus. Use .cursorindexingignore for packages you occasionally need.

## Best practices

- Open separate Cursor windows for different monorepo packages for independent indexing
- Use .cursorignore aggressively: node_modules, build outputs, generated files, unrelated packages
- Use .cursorindexingignore for packages excluded from search but still accessible via @file
- Scope context with @folder and @file instead of @codebase in monorepo prompts
- Create per-package .cursor/rules/ that auto-attach based on file location
- Use Notepads for cross-package architecture context referenced with @notepad-name
- Start new chat sessions when switching between packages to reset context
- Create shell aliases for quick package-level Cursor window launching

## Frequently asked questions

### What is Cursor's context window size?

It depends on the model. Claude 3.5 Sonnet has ~200K tokens (~150K words). In practice, 3-4 large code files plus conversation history fills the window. MAX mode provides larger context but costs more credits. Strategic @file references are more effective than loading entire packages.

### How does Cursor handle large codebases efficiently?

Cursor creates embeddings of your codebase for semantic search. Files in .gitignore and .cursorignore are excluded. For monorepos, open separate windows per package, use aggressive .cursorignore, and scope @context to specific folders.

### Should I use one Cursor window or multiple for a monorepo?

Multiple. Open separate windows for each active package. Each window indexes independently with its own rules. This is the single most effective monorepo optimization.

### How long does Cursor take to index a large monorepo?

A monorepo with 8,800+ files can take 7-12 hours. Reducing indexed files with .cursorignore and opening package-level windows can cut this to minutes. Cursor only auto-indexes folders with fewer than 10,000 files.

### Can Cursor search across monorepo packages?

Yes, if you open from the root and all packages are indexed. But this is usually counterproductive. Use precise @file references to specific files in other packages instead of broad cross-package searches.

---

Source: https://www.rapidevelopers.com/cursor-tutorial/how-to-manage-cursor-ai-s-context-window-when-developing-large-monorepos-with-multiple-packages
© RapidDev — https://www.rapidevelopers.com/cursor-tutorial/how-to-manage-cursor-ai-s-context-window-when-developing-large-monorepos-with-multiple-packages