AI agents index everything in your project for faster search. You don't want the AI context window to be bloated with irrelevant generated files and especially heavy folders: "node_modules" alone can be 100k+ files.

Why It Matters: The Hidden Token Drain

Every file the AI indexes costs tokens — both at indexing time and when it pulls context into a chat response. In a typical Next.js project, a large portion of those tokens come from files the AI has no business reading:

And that's before the security concern: .env files containing API keys and tokens can silently slip into the AI context and get sent to an LLM provider.

What is .cursorignore?

.cursorignore is a configuration file that tells your AI coding assistant which files and folders to skip — for indexing, tab completions, chat context, and @-mentions. It uses exactly the same syntax as .gitignore, so there's zero learning curve: glob patterns, negation with !, directory exclusions with trailing /.

Think of it this way: .gitignore protects your repository — .cursorignore protects your context window and your secrets.

The file lives in your project root. JetBrains AI Assistant (WebStorm, IntelliJ, etc.) also supports that format.

A Real-World Example for a Next.js App

Worth noting before diving in: Cursor already has sensible defaults. It automatically excludes node_modules/, .next/, lock files, .env* files, binaries, and anything listed in your .gitignore — without any configuration from you. So for Cursor users, many of the rules below are redundant but still worth keeping as explicit documentation of intent, and as a single source of truth that also works for JetBrains.

For JetBrains AI Assistant users, the full file matters — there are no built-in defaults.

Here's a complete .cursorignore for a Next.js project, with the reasoning behind each rule:

# AI ignore list to reduce token usage and speed up indexing

# Prevent API keys, tokens, and certificates from being sent to LLM providers (except examples)
.env
.env.*
!.env.example
!.env.template

The negation pattern (!) is doing something important here: you want the AI to know the shape of your environment variables — what keys exist and what they're named — just not their values. Whitelisting .env.example gives the AI useful context while keeping secrets out.

# Git internals
.git/

# Lock files are enormous (~10k+ lines), mostly resolved URLs and hashes — zero reasoning value for an AI;
# exclude unless debugging NPM dependency issues
yarn.lock
package-lock.json

The inline comment here is a pattern worth copying throughout your file. "Unless debugging NPM dependency issues" tells a future teammate (or yourself at 11pm) exactly when it's appropriate to temporarily remove this rule.

# Build output — compiled server/client JS, HTML, CSS chunks generated by `next build`
.next/

# Static export output — generated by `next export` into out/ by default
out/

# Test coverage reports — HTML/JSON rendered view of line hits, generated by `vitest --coverage`;
# AI gets better answers from reading source and test files directly
coverage/

The coverage reasoning is worth highlighting: a generated HTML coverage report is a rendered view of information that already exists in your source and test files. The AI gets more signal from reading those directly than from a post-processed artifact.

# Dependencies — ~100k files; AI knows these APIs from training, indexing them wastes tokens
node_modules/

# TypeScript incremental build cache — not used at runtime, safe to delete per TS docs
*.tsbuildinfo

# SWC compiler cache — generated by Next.js 15 during `next build` and `next dev`, not a source file
.swc/

# Generated Tailwind CSS output (~39k lines) — created by a build script, not a source file
test-output.css

# IDE workspace files and OS metadata — no value for AI context
.idea/
.vscode/
.DS_Store

# RSS feed — 3000+ lines of article metadata duplicated from data/ in XML format;
# exclude unless debugging feed generation specifically (scripts/generate-devto.js)
public/feed.xml

# Sitemap — pure list of URLs, only exists after build (scripts/generate-sitemap.js)
public/sitemap.xml

The last two are project-specific. Your project will have its own equivalents — any file that's generated from another source of truth is a candidate. When in doubt, ask: "is this file produced by a script from other source files?" If yes, exclude it.

How to Activate It in Cursor and WebStorm

Cursor supports .cursorignore natively — no setup required. Create the file in your project root and Cursor picks it up automatically. To force a re-index after creating or editing the file: Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows/Linux) → Cursor: Resync Index.

JetBrains AI Assistant (WebStorm, IntelliJ, etc.) support might to need to be enabled in the Settings. To do that:

1. Open Settings → Tools → AI Assistant → Project Settings
2. Enable the Use .aiignore file option

Other AI coding tools are adding similar support. Check your specific tool's documentation for its equivalent ignore file.

Ready-Made Templates for Other Stacks

You don't need to build your ignore list from scratch. The artem-kuchumov/cursorignore project collects ready-made templates for 20 languages and frameworks — including React, Next.js, Vue, Angular, Python/Django, Go, Rust, Laravel, Spring Boot, and Flutter.

A practical workflow: grab the template for your primary stack, then layer in your project-specific additions on top. Generated files like RSS feeds, sitemaps, or custom build outputs won't appear in any generic template — those you know about, so add them yourself with a comment explaining where they come from.

Tips for Keeping It Maintained

Treat .cursorignore like .gitignore — update it when you add new tooling. Install a new test runner? Add its output directory. Switch CSS frameworks? Add the generated output. The file rots quickly if you only create it once and forget it.

Always add a comment explaining why each rule exists. The rules themselves are obvious; the reasoning often isn't. "Exclude coverage/" is self-evident — but "AI gets better answers from source and test files directly" gives a future maintainer the context to decide whether to keep, remove, or scope the rule differently. The "unless debugging X" pattern is especially useful: it signals when it's intentional to temporarily remove a rule, rather than permanently deleting it.