0
# Development Server Integration
1

2
Real-time ESLint checking during development with Vite or Webpack integration. The module provides seamless integration with your development workflow, showing linting errors and warnings directly in your terminal and browser during development.
3

4
## Capabilities
5

6
### Checker Options
7

8
Configuration options for ESLint checker integration with the development server.
9

10
```typescript { .api }
11
/**
12
 * Configuration options for ESLint checker integration
13
 */
14
interface CheckerOptions {
15
  /**
16
   * Use ESLint cache to improve performance
17
   * @default true
18
   */
19
  cache?: boolean;
20

21
  /**
22
   * ESLint config type
23
   * Default to `flat` unless env `ESLINT_USE_FLAT_CONFIG` is set to `false`
24
   * @default 'flat'
25
   */
26
  configType?: 'flat' | 'eslintrc';
27

28
  /**
29
   * Files to include for linting
30
   * @default [`${nuxt.options.srcDir}/**/*.{js,jsx,ts,tsx,vue}`]
31
   */
32
  include?: string[];
33

34
  /**
35
   * Files to exclude from linting
36
   * @default ['**/node_modules/**', nuxt.options.buildDir]
37
   */
38
  exclude?: string[];
39

40
  /**
41
   * ESLint formatter for the output
42
   * @default 'stylish'
43
   * @see https://eslint.org/docs/user-guide/formatters/
44
   */
45
  formatter?: string;
46

47
  /**
48
   * Path to the ESLint module
49
   * @default 'eslint' or 'eslint/use-at-your-own-risk' based on configType
50
   */
51
  eslintPath?: string;
52

53
  /**
54
   * Lint on start
55
   * @default true
56
   */
57
  lintOnStart?: boolean;
58

59
  /**
60
   * The warnings found will printed
61
   * @default true
62
   */
63
  emitWarning?: boolean;
64

65
  /**
66
   * The errors found will printed
67
   * @default true
68
   */
69
  emitError?: boolean;
70

71
  /**
72
   * Run ESLint fix
73
   * @default false
74
   */
75
  fix?: boolean;
76

77
  /**
78
   * Vite specific options
79
   */
80
  vite?: ViteCheckerOptions;
81

82
  /**
83
   * Webpack specific options
84
   * @see https://www.npmjs.com/package/eslint-webpack-plugin
85
   */
86
  webpack?: WebpackCheckerOptions;
87
}
88
```
89

90
### Vite Integration
91

92
For projects using Nuxt with Vite, the module integrates with `vite-plugin-eslint2`.
93

94
```typescript { .api }
95
/**
96
 * Vite-specific ESLint integration options
97
 * Extends vite-plugin-eslint2 options
98
 */
99
interface ViteCheckerOptions {
100
  /** Run linting in a worker thread */
101
  lintInWorker?: boolean;
102
  /** Additional vite-plugin-eslint2 specific options */
103
  [key: string]: any;
104
}
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
// Basic Vite integration
111
export default defineNuxtConfig({
112
  modules: ['@nuxt/eslint'],
113
  eslint: {
114
    checker: {
115
      vite: {
116
        lintInWorker: true
117
      }
118
    }
119
  }
120
})
121
```
122

123
### Webpack Integration
124

125
For projects using Nuxt with Webpack, the module integrates with `eslint-webpack-plugin`.
126

127
```typescript { .api }
128
/**
129
 * Webpack-specific ESLint integration options
130
 * Uses eslint-webpack-plugin under the hood
131
 */
132
interface WebpackCheckerOptions {
133
  /** Context directory for linting */
134
  context?: string;
135
  /** Files pattern to lint */
136
  files?: string[];
137
  /** Only lint changed files */
138
  lintDirtyModulesOnly?: boolean;
139
  /** Additional eslint-webpack-plugin options */
140
  [key: string]: any;
141
}
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
// Basic Webpack integration  
148
export default defineNuxtConfig({
149
  modules: ['@nuxt/eslint'],
150
  eslint: {
151
    checker: {
152
      webpack: {
153
        lintDirtyModulesOnly: true
154
      }
155
    }
156
  }
157
})
158
```
159

160
### Config Type Detection
161

162
The module automatically detects which ESLint config format to use.
163

164
```typescript { .api }
165
/**
166
 * ESLint configuration format detection
167
 */
168
type ConfigType = 'flat' | 'eslintrc';
169

170
/**
171
 * Automatic config type detection based on environment
172
 * Defaults to 'flat' unless ESLINT_USE_FLAT_CONFIG=false
173
 */
174
function detectConfigType(): ConfigType;
175
```
176

177
### File Watching
178

179
The module automatically watches ESLint configuration files for changes.
180

181
```typescript { .api }
182
/**
183
 * ESLint config files that are watched for changes
184
 */
185
const watchedConfigFiles: string[] = [
186
  '.eslintignore',
187
  '.eslintrc',
188
  '.eslintrc.js', 
189
  '.eslintrc.yaml',
190
  '.eslintrc.yml',
191
  '.eslintrc.json',
192
  'eslint.config.js',
193
  'eslint.config.mjs', 
194
  'eslint.config.cjs'
195
];
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
// Enable checker with custom file patterns
202
export default defineNuxtConfig({
203
  modules: ['@nuxt/eslint'],
204
  eslint: {
205
    checker: {
206
      include: ['src/**/*.{ts,vue}'],
207
      exclude: ['src/generated/**'],
208
      formatter: 'unix',
209
      fix: true
210
    }
211
  }
212
})
213

214
// Checker with different config type
215
export default defineNuxtConfig({
216
  modules: ['@nuxt/eslint'],
217
  eslint: {
218
    checker: {
219
      configType: 'eslintrc',
220
      eslintPath: 'eslint'
221
    }
222
  }
223
})
224

225
// Disable warnings, only show errors
226
export default defineNuxtConfig({
227
  modules: ['@nuxt/eslint'],
228
  eslint: {
229
    checker: {
230
      emitWarning: false,
231
      emitError: true,
232
      lintOnStart: false
233
    }
234
  }
235
})
236
```
237

238
## Integration Process
239

240
1. **Builder Detection**: Module detects whether Vite or Webpack is being used
241
2. **Plugin Registration**: Appropriate ESLint plugin is registered with the builder
242
3. **Option Processing**: Checker options are processed and validated
243
4. **File Watching**: ESLint config files are added to the watch list
244
5. **Error Handling**: Linting errors and warnings are displayed in development
245

246
## Development Workflow
247

248
The checker integration enhances the development workflow:
249

250
- **Real-time Feedback**: ESLint errors appear in terminal and browser
251
- **Auto-fixing**: Optional automatic fixing of ESLint issues
252
- **Performance**: Caching and worker threads for better performance
253
- **Config Hot-reload**: Automatic restart suggestions when config changes
254

255
## Builder Support
256

257
The module automatically detects the build system and integrates appropriately:
258

259
### Supported Builders
260

261
- **@nuxt/vite-builder**: Uses `vite-plugin-eslint2` for integration
262
- **@nuxt/webpack-builder**: Uses `eslint-webpack-plugin` for integration
263

264
### Builder Detection
265

266
```typescript { .api }
267
/**
268
 * Builder detection based on Nuxt configuration
269
 * Automatically determines which ESLint integration to use
270
 */
271
interface BuilderDetection {
272
  /** Detected builder name */
273
  builder: '@nuxt/vite-builder' | '@nuxt/webpack-builder' | 'unknown';
274
  /** Whether ESLint integration is supported */
275
  supported: boolean;
276
  /** Integration plugin to use */
277
  plugin?: 'vite-plugin-eslint2' | 'eslint-webpack-plugin';
278
}
279
```
280

281
### Fallback Behavior
282

283
- **Unsupported Builders**: Graceful degradation with warning messages
284
- **Missing Plugins**: Attempts to install compatible ESLint integration plugins
285
- **Configuration Errors**: Clear error messages with suggested fixes
286
- **Development Mode Only**: Checker integration only activates in development
287

288
## Error Handling
289

290
The development server integration includes comprehensive error handling:
291

292
- **Plugin Loading**: Graceful fallback if ESLint plugins are not available
293
- **Config Validation**: Clear error messages for invalid configurations
294
- **Builder Compatibility**: Warnings for unsupported build configurations