0
# Lint Executor
1

2
Executor for running ESLint operations on projects with comprehensive configuration options, supporting both legacy and flat config formats with advanced caching and output capabilities.
3

4
## Core Imports
5

6
```typescript
7
import type { ExecutorContext } from '@nx/devkit';
8
import type { ESLint } from 'eslint';
9
```
10

11
## Capabilities
12

13
### Main Executor Function
14

15
The primary executor function that runs ESLint on specified files with configurable options.
16

17
```typescript { .api }
18
/**
19
 * Runs ESLint on a project with specified configuration
20
 * @param options - ESLint execution options
21
 * @param context - Nx executor context with workspace information
22
 * @returns Promise resolving to execution result
23
 */
24
function run(options: Schema, context: ExecutorContext): Promise<{ success: boolean }>;
25

26
interface ExecutorContext {
27
  /** Workspace root directory */
28
  root: string;
29
  /** Name of the project being executed */
30
  projectName: string;
31
  /** All project configurations in the workspace */
32
  projectsConfigurations: {
33
    projects: Record<string, ProjectConfiguration>;
34
  };
35
}
36

37
interface ProjectConfiguration {
38
  root: string;
39
  projectType?: string;
40
  targets?: Record<string, any>;
41
}
42
```
43

44
### Executor Schema
45

46
Complete configuration schema for the lint executor with all available options.
47

48
```typescript { .api }
49
interface Schema {
50
  /** Path to ESLint configuration file */
51
  eslintConfig?: string;
52
  /** File patterns to lint */
53
  lintFilePatterns: string[];
54
  /** Output format for lint results */
55
  format: 'stylish' | 'compact' | 'codeframe' | 'unix' | 'visualstudio' | 'table' | 'checkstyle' | 'html' | 'jslint-xml' | 'json' | 'json-with-metadata' | 'junit' | 'tap';
56
  /** Continue execution even if linting fails */
57
  force: boolean;
58
  /** Suppress most output except errors */
59
  silent: boolean;
60
  /** Automatically fix problems where possible */
61
  fix: boolean;
62
  /** Enable result caching */
63
  cache: boolean;
64
  /** Cache location for storing results */
65
  cacheLocation?: string;
66
  /** Output file for lint results */
67
  outputFile?: string;
68
  /** Maximum number of warnings allowed */
69
  maxWarnings: number;
70
  /** Only show errors, suppress warnings */
71
  quiet: boolean;
72
  /** Path to ignore file */
73
  ignorePath?: string;
74
  /** Disable use of .eslintrc files */
75
  noEslintrc: boolean;
76
  /** Whether configuration uses type-aware rules */
77
  hasTypeAwareRules?: boolean;
78
  /** Cache strategy to use */
79
  cacheStrategy: 'metadata' | 'content';
80
  /** Additional rules directories */
81
  rulesdir: string[];
82
  /** Resolve plugins relative to this path */
83
  resolvePluginsRelativeTo?: string;
84
  /** Report unused disable directives */
85
  reportUnusedDisableDirectives?: 'off' | 'warn' | 'error';
86
  /** Print configuration for a file */
87
  printConfig?: string;
88
  /** Error on unmatched file patterns */
89
  errorOnUnmatchedPattern?: boolean;
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import { ExecutorContext } from '@nx/devkit';
97

98
// Basic linting
99
const result = await run({
100
  eslintConfig: null, // Use default config resolution
101
  lintFilePatterns: ['src/**/*.ts'],
102
  format: 'stylish',
103
  force: false,
104
  silent: false,
105
  fix: false,
106
  cache: true,
107
  noEslintrc: false,
108
  outputFile: null,
109
  cacheLocation: null,
110
  maxWarnings: -1,
111
  quiet: false,
112
  ignorePath: null,
113
  hasTypeAwareRules: false,
114
  cacheStrategy: 'metadata',
115
  rulesdir: [],
116
  resolvePluginsRelativeTo: null,
117
  reportUnusedDisableDirectives: null
118
}, context);
119

120
// Linting with fixes and JSON output
121
const result = await run({
122
  eslintConfig: 'eslint.config.js',
123
  lintFilePatterns: ['src/**/*.{ts,tsx}', 'tests/**/*.ts'],
124
  format: 'json',
125
  force: false,
126
  silent: false,
127
  fix: true,
128
  cache: true,
129
  outputFile: 'lint-results.json',
130
  maxWarnings: 0,
131
  quiet: false,
132
  hasTypeAwareRules: true,
133
  cacheStrategy: 'content',
134
  errorOnUnmatchedPattern: true
135
}, context);
136
```
137

138
### Executor Registration
139

140
The executor is registered in `executors.json`:
141

142
```json
143
{
144
  "executors": {
145
    "lint": {
146
      "implementation": "./src/executors/lint/lint.impl",
147
      "schema": "./src/executors/lint/schema.json",
148
      "hasher": "./src/executors/lint/hasher",
149
      "description": "Run ESLint on a project."
150
    }
151
  }
152
}
153
```
154

155
## Output Formats
156

157
### Available Formatters
158

159
The executor supports all standard ESLint formatters:
160

161
```typescript { .api }
162
type Formatter = 
163
  | 'stylish'        // Default human-readable format
164
  | 'compact'        // Compact format similar to GCC
165
  | 'codeframe'      // Output like a snippet of code
166
  | 'unix'           // Unix style format
167
  | 'visualstudio'   // Visual Studio format
168
  | 'table'          // Table format
169
  | 'checkstyle'     // Checkstyle XML format
170
  | 'html'           // HTML format
171
  | 'jslint-xml'     // JSLint XML format  
172
  | 'json'           // JSON format
173
  | 'json-with-metadata' // JSON with metadata
174
  | 'junit'          // JUnit XML format
175
  | 'tap';           // TAP format
176
```
177

178
**Usage Examples:**
179

180
```typescript
181
// JSON output for CI/CD integration
182
await run({
183
  // ... other options
184
  format: 'json',
185
  outputFile: 'eslint-results.json'
186
}, context);
187

188
// JUnit XML for test reporting
189
await run({
190
  // ... other options  
191
  format: 'junit',
192
  outputFile: 'eslint-results.xml'
193
}, context);
194

195
// HTML report for viewing in browser
196
await run({
197
  // ... other options
198
  format: 'html', 
199
  outputFile: 'eslint-report.html'
200
}, context);
201
```
202

203
## Configuration Resolution
204

205
### Config File Resolution
206

207
The executor resolves ESLint configuration in the following order:
208

209
1. Explicit `eslintConfig` option
210
2. Flat config files (`eslint.config.js`, `eslint.config.mjs`, `eslint.config.cjs`)
211
3. Legacy config files (`.eslintrc.*`)
212

213
```typescript { .api }
214
interface ConfigResolution {
215
  /** Explicit configuration file path */
216
  explicitConfig?: string;
217
  /** Automatically resolved flat config */
218
  flatConfig?: string;
219
  /** Legacy configuration file */
220
  legacyConfig?: string;
221
  /** Final resolved configuration path */
222
  resolvedConfig: string | null;
223
}
224
```
225

226
### Environment Variables
227

228
The executor respects ESLint environment variables:
229

230
- `ESLINT_USE_FLAT_CONFIG`: Force flat config usage
231
- `ESLINT_CONFIG_FILE`: Override config file path
232

233
## Caching
234

235
### Cache Strategies
236

237
```typescript { .api }
238
type CacheStrategy = 'content' | 'metadata';
239

240
interface CacheOptions {
241
  /** Enable caching */
242
  cache: boolean;
243
  /** Cache location directory */
244
  cacheLocation?: string;
245
  /** Strategy for cache invalidation */
246
  cacheStrategy?: CacheStrategy;
247
}
248
```
249

250
**Cache Strategy Details:**
251

252
- **`content`**: Cache based on file content hashes (more accurate, slower)
253
- **`metadata`**: Cache based on file modification times (faster, less accurate)
254

255
### Cache Location
256

257
Cache files are stored in:
258
1. Specified `cacheLocation` 
259
2. `node_modules/.cache/eslint/` (default)
260
3. Per-project subdirectories when using project-specific caching
261

262
## Error Handling
263

264
### Type-Aware Rules Error
265

266
Special handling for TypeScript ESLint parser configuration errors:
267

268
```typescript { .api }
269
interface TypeAwareRulesError {
270
  /** Error message indicating missing parserOptions.project */
271
  message: string;
272
  /** Rule name that triggered the error */
273
  ruleName?: string;
274
  /** File being linted when error occurred */
275
  reportedFile?: string;
276
  /** Resolved configuration file path */
277
  configPath?: string;
278
}
279
```
280

281
**Example Error Output:**
282

283
```
284
Error: You have attempted to use the lint rule "@typescript-eslint/no-unused-vars" 
285
which requires the full TypeScript type-checker to be available, but you do not have 
286
"parserOptions.project" configured to point at your project tsconfig.json files in 
287
the relevant TypeScript file "overrides" block of your ESLint config "eslint.config.js"
288

289
Occurred while linting src/main.ts
290

291
Please see https://nx.dev/recipes/tips-n-tricks/eslint for full guidance on how to resolve this issue.
292
```
293

294
### Execution Results
295

296
```typescript { .api }
297
interface ExecutionResult {
298
  /** Whether execution completed successfully */
299
  success: boolean;
300
}
301

302
interface LintResults {
303
  /** Total number of errors found */
304
  errors: number;
305
  /** Total number of warnings found */
306
  warnings: number;
307
  /** Number of fixable errors */
308
  fixableErrors: number;
309
  /** Number of fixable warnings */
310
  fixableWarnings: number;
311
}
312
```