0
# Plugin Integration
1

2
Nx plugin functionality for automatic ESLint project inference and target creation, enabling seamless integration of ESLint into Nx workspace build systems.
3

4
## Core Imports
5

6
```typescript
7
import { createNodes, createNodesV2, EslintPluginOptions } from '@nx/eslint/plugin';
8
import type { CreateNodes, CreateNodesV2, CreateNodesResult, TargetConfiguration } from '@nx/devkit';
9
```
10

11
## Capabilities
12

13
### Create Nodes V2 (Recommended)
14

15
Modern plugin function for creating Nx project nodes from ESLint configurations with improved performance and caching.
16

17
```typescript { .api }
18
/**
19
 * Creates Nx project nodes from ESLint configurations (V2 API)
20
 * @param configFiles - Array of configuration file paths
21
 * @param options - Plugin configuration options
22
 * @param context - Nx creation context with workspace information
23
 * @returns Promise resolving to array of creation results
24
 */
25
const createNodesV2: CreateNodesV2<EslintPluginOptions>;
26

27
type CreateNodesV2<T> = [
28
  configGlob: string,
29
  fn: (
30
    configFiles: readonly string[],
31
    options: T | undefined,
32
    context: CreateNodesContextV2
33
  ) => Promise<CreateNodesResult[]>
34
];
35

36
interface CreateNodesResult {
37
  projects?: Record<string, ProjectConfiguration>;
38
}
39

40
interface ProjectConfiguration {
41
  targets?: Record<string, TargetConfiguration>;
42
}
43

44
interface TargetConfiguration {
45
  command?: string;
46
  executor?: string;
47
  options?: Record<string, any>;
48
  cache?: boolean;
49
  inputs?: string[];
50
  outputs?: string[];
51
  metadata?: {
52
    technologies?: string[];
53
    description?: string;
54
    help?: {
55
      command?: string;
56
      example?: Record<string, any>;
57
    };
58
  };
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
// Plugin registration in nx.json
66
{
67
  "plugins": [
68
    {
69
      "plugin": "@nx/eslint/plugin",
70
      "options": {
71
        "targetName": "lint",
72
        "extensions": ["ts", "tsx", "js", "jsx"]
73
      }
74
    }
75
  ]
76
}
77

78
// Programmatic usage
79
import { createNodesV2 } from '@nx/eslint/plugin';
80

81
const [configGlob, createNodesFn] = createNodesV2;
82
const results = await createNodesFn(
83
  ['eslint.config.js', 'packages/*/eslint.config.js'],
84
  { targetName: 'lint' },
85
  context
86
);
87
```
88

89
### Create Nodes (Legacy)
90

91
Legacy plugin function for backward compatibility (deprecated).
92

93
```typescript { .api }
94
/**
95
 * Creates Nx project nodes (Legacy API - deprecated)
96
 * @param configFilePath - Path to ESLint configuration file
97
 * @param options - Plugin options
98
 * @param context - Creation context
99
 * @returns Creation result with project configurations
100
 */
101
const createNodes: CreateNodes<EslintPluginOptions>;
102

103
type CreateNodes<T> = [
104
  configGlob: string,
105
  fn: (
106
    configFilePath: string,
107
    options: T | undefined,
108
    context: CreateNodesContext
109
  ) => CreateNodesResult
110
];
111
```
112

113
### Plugin Options
114

115
Configuration options for the ESLint plugin.
116

117
```typescript { .api }
118
interface EslintPluginOptions {
119
  /** Name for the generated lint target */
120
  targetName?: string;
121
  /** File extensions to include in linting */
122
  extensions?: string[];
123
}
124
```
125

126
**Default Configuration:**
127

128
```typescript
129
const defaultOptions: EslintPluginOptions = {
130
  targetName: 'lint',
131
  extensions: ['ts', 'cts', 'mts', 'tsx', 'js', 'cjs', 'mjs', 'jsx', 'html', 'vue']
132
};
133
```
134

135
## Plugin Behavior
136

137
### Target Generation
138

139
The plugin automatically creates lint targets for projects based on ESLint configuration files:
140

141
```typescript { .api }
142
interface GeneratedTarget {
143
  command: string;
144
  cache: boolean;
145
  options: {
146
    cwd: string;
147
    env?: Record<string, string>;
148
  };
149
  inputs: string[];
150
  outputs: string[];
151
  metadata: {
152
    technologies: ['eslint'];
153
    description: 'Runs ESLint on project';
154
    help: {
155
      command: string;
156
      example: {
157
        options: Record<string, any>;
158
      };
159
    };
160
  };
161
}
162
```
163

164
### Configuration File Detection
165

166
The plugin detects and processes various ESLint configuration formats:
167

168
- `eslint.config.js` (Flat config)
169
- `eslint.config.mjs` (Flat config ES modules)
170
- `eslint.config.cjs` (Flat config CommonJS)
171
- `.eslintrc.json` (Legacy format)
172
- `.eslintrc.js` (Legacy format)
173
- `.eslintrc.yml` / `.eslintrc.yaml` (Legacy format)
174

175
### Project Inference
176

177
The plugin automatically infers project configurations based on:
178

179
```typescript { .api }
180
interface InferenceFactors {
181
  /** ESLint configuration files in the project */
182
  configFiles: string[];
183
  /** Lintable files matching specified extensions */
184
  lintableFiles: string[];
185
  /** ESLint ignore patterns from .eslintignore */
186
  ignorePatterns: string[];
187
  /** Project metadata from project.json or package.json */
188
  projectMetadata: Record<string, any>;
189
}
190
```
191

192
**Usage Examples:**
193

194
```typescript
195
// Automatic target creation for project with eslint.config.js
196
// Results in:
197
{
198
  "targets": {
199
    "lint": {
200
      "command": "eslint .",
201
      "cache": true,
202
      "options": {
203
        "cwd": "packages/my-lib"
204
      },
205
      "inputs": [
206
        "default",
207
        "^default",
208
        "{workspaceRoot}/eslint.config.js",
209
        "{workspaceRoot}/tools/eslint-rules/**/*",
210
        { "externalDependencies": ["eslint"] }
211
      ],
212
      "outputs": ["{options.outputFile}"]
213
    }
214
  }
215
}
216
```
217

218
### Plugin Integration Points
219

220
The plugin integrates with Nx at several points:
221

222
```typescript { .api }
223
interface PluginIntegration {
224
  /** File glob patterns for configuration detection */
225
  configGlob: string;
226
  /** Caching mechanisms for performance */
227
  projectsCache: Record<string, any>;
228
  /** Hash calculation for cache invalidation */
229
  hashCalculation: (context: any) => Promise<string>;
230
  /** Project root detection logic */
231
  projectRootInference: (files: string[]) => string[];
232
}
233
```
234

235
## Advanced Configuration
236

237
### Custom Extensions
238

239
```typescript
240
// Register plugin with custom file extensions
241
{
242
  "plugins": [
243
    {
244
      "plugin": "@nx/eslint/plugin", 
245
      "options": {
246
        "extensions": ["ts", "tsx", "vue", "svelte"]
247
      }
248
    }
249
  ]
250
}
251
```
252

253
### Custom Target Names
254

255
```typescript
256
// Use custom target name
257
{
258
  "plugins": [
259
    {
260
      "plugin": "@nx/eslint/plugin",
261
      "options": {
262
        "targetName": "eslint-check"
263
      }
264
    }
265
  ]
266
}
267
```
268

269
### Environment Variables
270

271
The plugin respects several environment variables:
272

273
- `ESLINT_USE_FLAT_CONFIG`: Force flat config mode
274
- `NX_ADD_PLUGINS`: Control automatic plugin addition
275
- `NX_CACHE_PROJECT_GRAPH`: Enable/disable project graph caching