# Why Cursor Ignores Custom ESLint Rules

- Tool: Cursor
- Difficulty: Intermediate
- Time required: 10-15 min
- Compatibility: Cursor Pro+, ESLint, monorepo setups
- Last updated: March 2026

## TL;DR

Fix Cursor ignoring custom ESLint rules by migrating from legacy .cursorrules to .cursor/rules/ with proper glob patterns, referencing your ESLint config with @file in prompts, and adding explicit linting rules that list your custom plugin names and rule IDs. Cursor does not run ESLint directly but can follow your lint rules when they are documented in project rules.

## Why Cursor Does Not Follow Your ESLint Config by Default

Cursor does not execute ESLint or read your .eslintrc configuration. It generates code based on AI model knowledge and project rules, which means custom ESLint plugins, team-specific lint rules, and monorepo configurations are invisible to it. This tutorial shows you how to bridge the gap by encoding your most important lint rules into Cursor project rules, using @Lint Errors to catch violations, and structuring monorepo rules for per-package enforcement.

## Before you start

- Cursor installed (Pro recommended for monorepo context)
- ESLint configured with custom plugins or rules
- A monorepo or multi-package project structure
- Understanding of your team's ESLint rule set

## Step-by-step guide

### 1. Document critical ESLint rules in .cursorrules

Identify your most important custom ESLint rules and translate them into natural language instructions in .cursorrules. Focus on rules that Cursor violates most frequently rather than trying to encode your entire ESLint config.

```
# .cursorrules

## Linting Rules (from our ESLint config)
- No default exports — use named exports only (eslint: import/no-default-export)
- No console.log in production code (eslint: no-console) — use our logger utility
- Prefer const over let, never use var (eslint: prefer-const, no-var)
- Use explicit return types on all exported functions (eslint: @typescript-eslint/explicit-function-return-type)
- Maximum 1 component per file (eslint: react/no-multi-comp)
- No inline styles in React (eslint: react/no-inline-styles) — use sx prop or theme
- Import order: external → internal → relative (eslint: import/order)
- No unused variables — prefix intentionally unused with _ (eslint: @typescript-eslint/no-unused-vars)
```

> Pro tip: Include the ESLint rule ID in parentheses next to each instruction. This helps team members understand which lint rule each Cursor rule corresponds to.

**Expected result:** Cursor follows your most critical ESLint conventions in generated code.

### 2. Create per-package rules for monorepo ESLint configs

In a monorepo, different packages often have different ESLint configs. Create nested .cursor/rules/ directories in each package with rules matching that package's ESLint configuration.

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

- React rules apply: use functional components only, no class components
- Use React.FC type for all components
- Props must be defined as separate interface above the component
- No direct DOM manipulation (no document.querySelector)
- Use next/image instead of img tags
- All event handlers prefixed with 'handle': handleClick, handleSubmit
- Custom hooks must start with 'use' and be in hooks/ directory
```

> Pro tip: Create separate rule files for each package: packages/backend/.cursor/rules/lint.mdc, packages/shared/.cursor/rules/lint.mdc, etc.

**Expected result:** Different Cursor rules apply to different monorepo packages matching their ESLint configs.

### 3. Use @Lint Errors to catch violations after generation

After Cursor generates code, use the @Lint Errors context in Chat to identify ESLint violations. Open Chat (Cmd+L) and reference @Lint Errors to have Cursor read the current linting errors from the Problems panel and fix them.

```
// After generating code, if ESLint shows errors in the Problems panel:
// Open Chat (Cmd+L) and type:
// @Lint Errors
// Fix all linting errors in the current file.
// Follow our ESLint config rules for:
// - Import ordering (external → internal → relative)
// - Explicit return types on exported functions
// - Named exports only, no default exports
```

> Pro tip: @Lint Errors captures the current ESLint errors from the active file. This is the closest integration between Cursor and ESLint without a custom plugin.

**Expected result:** Cursor reads the lint errors and fixes each violation according to your ESLint rules.

### 4. Reference your ESLint config in complex prompts

For complex code generation where lint compliance is critical, reference your ESLint config file directly. This gives Cursor the actual rule definitions so it can follow them more precisely than natural language descriptions.

```
// Prompt to type in Cursor Composer (Cmd+I):
// @.eslintrc.js @packages/frontend/eslint.config.mjs
// Generate a new UserSettings page component in packages/frontend/.
// Follow ALL rules from the ESLint configs referenced above.
// Pay special attention to:
// - Named exports only
// - Explicit return types
// - React hook rules
// - Import ordering
```

**Expected result:** Cursor generates code that follows your actual ESLint configuration more closely.

### 5. Create a post-generation lint check command

Create a custom Cursor command that runs ESLint on generated files and feeds violations back to the AI for automatic fixing. Save it in .cursor/commands/ for team-wide use.

```
---
description: Lint and fix generated code
---

1. Run ESLint on the files that were just generated or modified
2. Read the ESLint output for any violations
3. Fix each violation following our project's ESLint rules
4. Re-run ESLint to verify all violations are resolved
5. If auto-fixable, apply eslint --fix first, then handle remaining issues

Common violations to watch for:
- Missing return types → add explicit TypeScript return type
- Default exports → convert to named exports
- console.log → replace with logger.info/error/debug
- Unused imports → remove them
- Wrong import order → reorder: external, internal, relative
```

> Pro tip: Team members can trigger this with /lint-fix after any code generation session.

**Expected result:** A reusable command that automatically lints and fixes generated code.

## Complete code example

File: `.cursor/rules/eslint-conventions.mdc`

```markdown
---
description: ESLint conventions for code generation
globs: "**/*.ts, **/*.tsx, **/*.js, **/*.jsx"
alwaysApply: false
---

# ESLint Rules for Cursor Code Generation

## Exports
- Use named exports ONLY (no default exports)
- Pattern: `export function MyComponent()` or `export const myUtil =`
- Exception: Next.js page components may use default export

## Types
- Explicit return types on all exported functions
- Props as separate interface above component: `interface MyComponentProps {}`
- Use `unknown` instead of `any`
- Prefer type aliases for unions, interfaces for objects

## Imports
- Order: 1) external packages, 2) @/ internal aliases, 3) relative paths
- Blank line between each group
- No unused imports
- Use import type for type-only imports

## React
- Functional components only (no class components)
- Event handlers prefixed with 'handle': handleClick, handleSubmit
- Custom hooks start with 'use', placed in hooks/ directory
- No inline styles — use sx prop or CSS modules

## General
- const over let, never var
- No console.log — use logger utility from @/lib/logger
- No magic numbers — extract to named constants
- Prefer early returns over nested conditionals
- Maximum 300 lines per file
```

## Common mistakes

- **Expecting Cursor to read and execute your .eslintrc automatically** — Cursor does not run ESLint or parse ESLint configs. It generates code based on AI training and project rules only. ESLint integration happens after code generation. Fix: Encode your most violated ESLint rules into .cursor/rules/ files and use @Lint Errors to fix violations post-generation.
- **Putting all monorepo ESLint rules in a single root .cursorrules** — Different monorepo packages have different ESLint configs. A single rules file creates conflicts between backend and frontend conventions. Fix: Use nested .cursor/rules/ directories in each package with package-specific lint rules.
- **Not referencing the ESLint config in complex generation prompts** — Natural language rules in .cursorrules cover common cases but miss nuanced ESLint plugin rules. Referencing the config gives Cursor the complete rule set. Fix: Add @.eslintrc.js or @eslint.config.mjs to prompts for critical code generation where lint compliance matters.

## Best practices

- Encode your top 10 most-violated ESLint rules in .cursorrules with the rule ID in parentheses
- Use nested .cursor/rules/ in monorepo packages for per-package lint conventions
- Reference @Lint Errors in Chat after code generation to catch and fix violations
- Reference your actual ESLint config file with @file for complex generation prompts
- Create a /lint-fix custom command for automated post-generation lint compliance
- Focus on rules Cursor violates most often rather than encoding your entire config
- Update Cursor rules when ESLint config changes to keep them in sync

## Frequently asked questions

### Why does Cursor ignore my custom ESLint rules?

Cursor does not run ESLint or read .eslintrc files. It generates code based on AI training and .cursorrules only. Encode your critical ESLint rules into .cursor/rules/ files and reference @Lint Errors post-generation to catch violations.

### Can Cursor run ESLint automatically after generating code?

In Agent mode with YOLO enabled, Cursor can run eslint --fix as a terminal command. Add it to your YOLO allowed commands. Alternatively, if your editor has ESLint auto-fix on save, violations are caught when Cursor saves files.

### How do I handle different ESLint configs in a monorepo?

Create nested .cursor/rules/ directories in each package with rules matching that package's ESLint config. These auto-attach when editing files in the respective package.

### Does Cursor support Prettier formatting rules?

Cursor respects your editor's Format On Save setting. If Prettier is configured as your formatter, files are auto-formatted when Cursor saves them. Add formatting preferences to .cursorrules for generation-time compliance.

### Should I encode ALL ESLint rules in .cursorrules?

No. Focus on the 10-15 rules that Cursor violates most often. Standard rules like no-unused-vars are usually followed by default. Custom plugin rules and team-specific conventions need explicit documentation.

---

Source: https://www.rapidevelopers.com/cursor-tutorial/how-to-fix-cursor-ai-ignoring-custom-eslint-plugin-rules-in-a-monorepo
© RapidDev — https://www.rapidevelopers.com/cursor-tutorial/how-to-fix-cursor-ai-ignoring-custom-eslint-plugin-rules-in-a-monorepo