0
# ESLint Checker
1

2
ESLint integration for JavaScript and TypeScript linting with customizable rules, file watching, and separate development and build configurations.
3

4
## Capabilities
5

6
### ESLint Configuration
7

8
Enable and configure ESLint linting with flexible options for different environments and use cases.
9

10
```typescript { .api }
11
/**
12
 * ESLint checker configuration
13
 * - Set to `false` to disable ESLint checking
14
 * - Provide configuration object for custom setup
15
 */
16
type EslintConfig = false | EslintConfigObject;
17

18
interface EslintConfigObject {
19
  /** Configure path to watch files */
20
  watchPath?: string | string[];
21
  
22
  /** 
23
   * Lint command executed in build mode and used as default for dev mode 
24
   * when dev.overrideConfig is not provided
25
   */
26
  lintCommand: string;
27
  
28
  /** 
29
   * Use ESLint flat config format 
30
   * @default false 
31
   */
32
  useFlatConfig?: boolean;
33
  
34
  /** Development-specific configuration */
35
  dev?: Partial<EslintDevConfig>;
36
}
37

38
interface EslintDevConfig {
39
  /** Override options translated from lintCommand for development mode */
40
  overrideConfig: ESLint.Options;
41
  
42
  /** Which diagnostic levels to emit from the plugin */
43
  logLevel: ('error' | 'warning')[];
44
}
45
```
46

47
**Usage Examples:**
48

49
```typescript
50
// Basic ESLint configuration
51
checker({
52
  eslint: {
53
    lintCommand: 'eslint "./src/**/*.{ts,tsx,js,jsx}"',
54
  },
55
});
56

57
// Advanced configuration with custom paths and dev options
58
checker({
59
  eslint: {
60
    watchPath: ['src', 'test'],
61
    lintCommand: 'eslint "./src/**/*.{ts,tsx}" --max-warnings 0',
62
    useFlatConfig: true,
63
    dev: {
64
      logLevel: ['error', 'warning'],
65
      overrideConfig: {
66
        baseConfig: {
67
          extends: ['@typescript-eslint/recommended'],
68
        },
69
        useEslintrc: false,
70
      },
71
    },
72
  },
73
});
74
```
75

76
### Watch Path Configuration
77

78
Configure which files and directories ESLint should monitor for changes in development mode.
79

80
```typescript { .api }
81
interface EslintConfigObject {
82
  /**
83
   * Configure path to watch files
84
   * - Single string path: 'src'
85
   * - Multiple paths: ['src', 'test', 'lib']
86
   * - Glob patterns: 'src/**/*.ts'
87
   */
88
  watchPath?: string | string[];
89
}
90
```
91

92
**Usage Examples:**
93

94
```typescript
95
// Watch single directory
96
eslint: {
97
  watchPath: 'src',
98
  lintCommand: 'eslint src',
99
}
100

101
// Watch multiple directories
102
eslint: {
103
  watchPath: ['src', 'test', 'lib'],
104
  lintCommand: 'eslint src test lib',
105
}
106

107
// Watch with glob patterns
108
eslint: {
109
  watchPath: ['src/**/*.{ts,tsx}', 'test/**/*.test.ts'],
110
  lintCommand: 'eslint "src/**/*.{ts,tsx}" "test/**/*.test.ts"',
111
}
112
```
113

114
### Lint Command Configuration
115

116
The `lintCommand` defines how ESLint is executed and serves as the primary configuration.
117

118
```typescript { .api }
119
interface EslintConfigObject {
120
  /**
121
   * Command executed in build mode and used as default config for dev mode
122
   * Should include file patterns and any ESLint CLI options
123
   */
124
  lintCommand: string;
125
}
126
```
127

128
**Command Examples:**
129

130
```typescript
131
// Basic TypeScript linting
132
lintCommand: 'eslint "./src/**/*.{ts,tsx}"'
133

134
// With specific rules and formatting
135
lintCommand: 'eslint "./src/**/*.{ts,tsx}" --max-warnings 0 --format unix'
136

137
// Multiple file patterns
138
lintCommand: 'eslint "./src/**/*.ts" "./test/**/*.test.ts" --ext .ts,.tsx'
139

140
// With configuration file
141
lintCommand: 'eslint "./src/**/*.{ts,tsx}" -c .eslintrc.build.json'
142
```
143

144
### Flat Config Support
145

146
ESLint flat config format support for modern ESLint configurations.
147

148
```typescript { .api }
149
interface EslintConfigObject {
150
  /**
151
   * Use ESLint flat config format (eslint.config.js)
152
   * @default false
153
   */
154
  useFlatConfig?: boolean;
155
}
156
```
157

158
**Usage with Flat Config:**
159

160
```typescript
161
// eslint.config.js
162
export default [
163
  {
164
    files: ['src/**/*.{ts,tsx}'],
165
    rules: {
166
      'no-unused-vars': 'error',
167
      '@typescript-eslint/no-unused-vars': 'error',
168
    },
169
  },
170
];
171

172
// vite.config.ts
173
checker({
174
  eslint: {
175
    lintCommand: 'eslint ./src',
176
    useFlatConfig: true,
177
  },
178
});
179
```
180

181
### Development Mode Configuration
182

183
Override ESLint behavior specifically for development mode with custom options and log levels.
184

185
```typescript { .api }
186
interface EslintDevConfig {
187
  /**
188
   * Override ESLint options for development mode
189
   * Takes precedence over options derived from lintCommand
190
   */
191
  overrideConfig: ESLint.Options;
192
  
193
  /**
194
   * Control which diagnostic levels are emitted from the plugin
195
   * @default ['error', 'warning']
196
   */
197
  logLevel: ('error' | 'warning')[];
198
}
199
```
200

201
**Development Configuration Examples:**
202

203
```typescript
204
// Custom ESLint config for development
205
eslint: {
206
  lintCommand: 'eslint "./src/**/*.{ts,tsx}"',
207
  dev: {
208
    overrideConfig: {
209
      baseConfig: {
210
        extends: [
211
          '@typescript-eslint/recommended',
212
          'plugin:react/recommended',
213
        ],
214
        rules: {
215
          // Relax some rules in development
216
          '@typescript-eslint/no-unused-vars': 'warn',
217
          'no-console': 'off',
218
        },
219
      },
220
      useEslintrc: true,
221
      extensions: ['.ts', '.tsx', '.js', '.jsx'],
222
    },
223
    // Only show errors in dev mode, ignore warnings
224
    logLevel: ['error'],
225
  },
226
}
227

228
// Completely different rule set for development
229
eslint: {
230
  lintCommand: 'eslint "./src/**/*.{ts,tsx}"',
231
  dev: {
232
    overrideConfig: {
233
      baseConfig: {
234
        rules: {
235
          // Development-friendly rules
236
          'no-debugger': 'warn',
237
          'no-console': 'off',
238
          '@typescript-eslint/no-explicit-any': 'warn',
239
        },
240
      },
241
    },
242
    logLevel: ['error', 'warning'],
243
  },
244
}
245
```
246

247
### ESLint Options Interface
248

249
The `overrideConfig` accepts standard ESLint API options:
250

251
```typescript { .api }
252
interface ESLint.Options {
253
  /** Base configuration object */
254
  baseConfig?: ESLint.ConfigData;
255
  
256
  /** Whether to use .eslintrc.* files */
257
  useEslintrc?: boolean;
258
  
259
  /** File extensions to check */
260
  extensions?: string[];
261
  
262
  /** Patterns to ignore */
263
  ignorePath?: string;
264
  
265
  /** Custom rules directory */
266
  rulePaths?: string[];
267
  
268
  /** Fix problems automatically */
269
  fix?: boolean;
270
  
271
  /** Additional configuration */
272
  [key: string]: any;
273
}
274
```
275

276
### Error Reporting
277

278
ESLint errors and warnings are reported with comprehensive information:
279

280
- **Rule name**: The specific ESLint rule that was violated
281
- **Severity**: Error or warning level
282
- **File location**: Exact file path and line/column numbers  
283
- **Message**: Detailed description of the linting issue
284
- **Code frame**: Highlighted code snippet showing the problematic code
285
- **Fix suggestion**: Automatic fix information when available
286

287
### Integration Examples
288

289
**React TypeScript Project:**
290

291
```typescript
292
checker({
293
  eslint: {
294
    watchPath: 'src',
295
    lintCommand: 'eslint "./src/**/*.{ts,tsx}" --max-warnings 0',
296
    dev: {
297
      overrideConfig: {
298
        baseConfig: {
299
          extends: [
300
            '@typescript-eslint/recommended',
301
            'plugin:react/recommended',
302
            'plugin:react-hooks/recommended',
303
          ],
304
          parser: '@typescript-eslint/parser',
305
          parserOptions: {
306
            ecmaVersion: 2020,
307
            sourceType: 'module',
308
            ecmaFeatures: { jsx: true },
309
          },
310
        },
311
      },
312
      logLevel: ['error', 'warning'],
313
    },
314
  },
315
});
316
```
317

318
**Vue TypeScript Project:**
319

320
```typescript
321
checker({
322
  eslint: {
323
    watchPath: ['src', 'components'],
324
    lintCommand: 'eslint "./src/**/*.{ts,vue}" "./components/**/*.vue"',
325
    dev: {
326
      overrideConfig: {
327
        baseConfig: {
328
          extends: [
329
            '@typescript-eslint/recommended',
330
            'plugin:vue/vue3-recommended',
331
          ],
332
          parser: 'vue-eslint-parser',
333
          parserOptions: {
334
            parser: '@typescript-eslint/parser',
335
          },
336
        },
337
      },
338
    },
339
  },
340
});
341
```