0
# Stylelint Checker
1

2
CSS and SCSS linting integration using Stylelint with customizable rules, file watching, and separate development and build configurations.
3

4
## Capabilities
5

6
### Stylelint Configuration
7

8
Enable and configure Stylelint for CSS, SCSS, and styled-components linting with flexible options for different environments.
9

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

18
interface StylelintConfigObject {
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
  /** Development-specific configuration */
29
  dev?: Partial<StylelintDevConfig>;
30
}
31

32
interface StylelintDevConfig {
33
  /** Override options translated from lintCommand for development mode */
34
  overrideConfig: Stylelint.LinterOptions;
35
  
36
  /** Which diagnostic levels to emit from the plugin */
37
  logLevel: ('error' | 'warning')[];
38
}
39
```
40

41
**Usage Examples:**
42

43
```typescript
44
// Basic Stylelint configuration
45
checker({
46
  stylelint: {
47
    lintCommand: 'stylelint "./src/**/*.{css,scss,vue}"',
48
  },
49
});
50

51
// Advanced configuration with custom paths and dev options
52
checker({
53
  stylelint: {
54
    watchPath: ['src/styles', 'src/components'],
55
    lintCommand: 'stylelint "./src/**/*.{css,scss}" --max-warnings 0',
56
    dev: {
57
      logLevel: ['error', 'warning'],
58
      overrideConfig: {
59
        configFile: '.stylelintrc.dev.json',
60
        syntax: 'scss',
61
      },
62
    },
63
  },
64
});
65
```
66

67
### Watch Path Configuration
68

69
Configure which files and directories Stylelint should monitor for changes in development mode.
70

71
```typescript { .api }
72
interface StylelintConfigObject {
73
  /**
74
   * Configure path to watch files
75
   * - Single string path: 'src/styles'
76
   * - Multiple paths: ['src/styles', 'src/components']
77
   * - Glob patterns: 'src/**/*.scss'
78
   */
79
  watchPath?: string | string[];
80
}
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
// Watch CSS files in styles directory
87
stylelint: {
88
  watchPath: 'src/styles',
89
  lintCommand: 'stylelint src/styles/**/*.css',
90
}
91

92
// Watch multiple directories
93
stylelint: {
94
  watchPath: ['src/styles', 'src/components', 'src/assets'],
95
  lintCommand: 'stylelint "src/**/*.{css,scss}"',
96
}
97

98
// Watch specific file patterns
99
stylelint: {
100
  watchPath: ['src/**/*.scss', 'src/**/*.vue'],
101
  lintCommand: 'stylelint "src/**/*.{scss,vue}"',
102
}
103
```
104

105
### Lint Command Configuration
106

107
The `lintCommand` defines how Stylelint is executed and serves as the primary configuration.
108

109
```typescript { .api }
110
interface StylelintConfigObject {
111
  /**
112
   * Command executed in build mode and used as default config for dev mode
113
   * Should include file patterns and any Stylelint CLI options
114
   */
115
  lintCommand: string;
116
}
117
```
118

119
**Command Examples:**
120

121
```typescript
122
// Basic CSS linting
123
lintCommand: 'stylelint "./src/**/*.css"'
124

125
// SCSS and CSS files
126
lintCommand: 'stylelint "./src/**/*.{css,scss}"'
127

128
// With specific configuration file
129
lintCommand: 'stylelint "./src/**/*.{css,scss}" --config .stylelintrc.json'
130

131
// With custom syntax
132
lintCommand: 'stylelint "./src/**/*.scss" --syntax scss'
133

134
// Vue SFC styles
135
lintCommand: 'stylelint "./src/**/*.vue" --custom-syntax postcss-html'
136

137
// Multiple patterns with options
138
lintCommand: 'stylelint "./src/**/*.{css,scss}" --max-warnings 0 --formatter string'
139
```
140

141
### Development Mode Configuration
142

143
Override Stylelint behavior specifically for development mode with custom options and log levels.
144

145
```typescript { .api }
146
interface StylelintDevConfig {
147
  /**
148
   * Override Stylelint options for development mode
149
   * Takes precedence over options derived from lintCommand
150
   */
151
  overrideConfig: Stylelint.LinterOptions;
152
  
153
  /**
154
   * Control which diagnostic levels are emitted from the plugin
155
   * @default ['error', 'warning']
156
   */
157
  logLevel: ('error' | 'warning')[];
158
}
159
```
160

161
**Development Configuration Examples:**
162

163
```typescript
164
// Custom Stylelint config for development
165
stylelint: {
166
  lintCommand: 'stylelint "./src/**/*.{css,scss}"',
167
  dev: {
168
    overrideConfig: {
169
      configFile: '.stylelintrc.dev.json',
170
      syntax: 'scss',
171
      fix: true, // Auto-fix issues in development
172
      allowEmptyInput: true,
173
    },
174
    // Only show errors in dev mode
175
    logLevel: ['error'],
176
  },
177
}
178

179
// Relaxed rules for development
180
stylelint: {
181
  lintCommand: 'stylelint "./src/**/*.{css,scss}"',
182
  dev: {
183
    overrideConfig: {
184
      rules: {
185
        // Relaxed rules for development
186
        'declaration-empty-line-before': null,
187
        'comment-empty-line-before': null,
188
        'no-missing-end-of-source-newline': null,
189
      },
190
    },
191
    logLevel: ['error', 'warning'],
192
  },
193
}
194
```
195

196
### Stylelint Linter Options
197

198
The `overrideConfig` accepts standard Stylelint API options:
199

200
```typescript { .api }
201
interface Stylelint.LinterOptions {
202
  /** Configuration file path */
203
  configFile?: string;
204
  
205
  /** Inline configuration object */
206
  config?: Stylelint.Config;
207
  
208
  /** CSS syntax to use */
209
  syntax?: string;
210
  
211
  /** Custom syntax module */
212
  customSyntax?: string;
213
  
214
  /** Automatically fix problems */
215
  fix?: boolean;
216
  
217
  /** Allow empty input */
218
  allowEmptyInput?: boolean;
219
  
220
  /** Report configuration comments */
221
  reportNeedlessDisables?: boolean;
222
  
223
  /** Additional configuration */
224
  [key: string]: any;
225
}
226
```
227

228
### CSS and SCSS Support
229

230
**Standard CSS:**
231
```typescript
232
stylelint: {
233
  lintCommand: 'stylelint "./src/**/*.css"',
234
  watchPath: 'src/styles',
235
}
236
```
237

238
**SCSS/Sass:**
239
```typescript
240
stylelint: {
241
  lintCommand: 'stylelint "./src/**/*.scss" --syntax scss',
242
  dev: {
243
    overrideConfig: {
244
      syntax: 'scss',
245
    },
246
  },
247
}
248
```
249

250
**CSS-in-JS/Styled Components:**
251
```typescript
252
stylelint: {
253
  lintCommand: 'stylelint "./src/**/*.{js,jsx,ts,tsx}" --custom-syntax @stylelint/postcss-css-in-js',
254
  dev: {
255
    overrideConfig: {
256
      customSyntax: '@stylelint/postcss-css-in-js',
257
    },
258
  },
259
}
260
```
261

262
### Vue Single File Component Styles
263

264
Special configuration for linting styles within Vue SFC files:
265

266
```typescript
267
stylelint: {
268
  lintCommand: 'stylelint "./src/**/*.vue" --custom-syntax postcss-html',
269
  watchPath: 'src',
270
  dev: {
271
    overrideConfig: {
272
      customSyntax: 'postcss-html',
273
      rules: {
274
        // Vue-specific style rules
275
        'selector-pseudo-element-no-unknown': [
276
          true,
277
          {
278
            ignorePseudoElements: ['v-deep', 'v-global', 'v-slotted'],
279
          },
280
        ],
281
      },
282
    },
283
  },
284
}
285
```
286

287
### Error Reporting
288

289
Stylelint errors and warnings are reported with comprehensive information:
290

291
- **Rule name**: The specific Stylelint rule that was violated
292
- **Severity**: Error or warning level
293
- **File location**: Exact file path and line/column numbers
294
- **Message**: Detailed description of the style issue
295
- **Code frame**: Highlighted CSS/SCSS code snippet
296
- **Fix suggestion**: Automatic fix information when available
297

298
### Common Configuration Examples
299

300
**React with CSS Modules:**
301
```typescript
302
checker({
303
  stylelint: {
304
    watchPath: 'src',
305
    lintCommand: 'stylelint "./src/**/*.{css,module.css}"',
306
    dev: {
307
      overrideConfig: {
308
        rules: {
309
          'selector-class-pattern': '^[a-z][a-zA-Z0-9]+$', // camelCase
310
        },
311
      },
312
    },
313
  },
314
});
315
```
316

317
**Vue 3 with SCSS:**
318
```typescript
319
checker({
320
  stylelint: {
321
    watchPath: ['src/components', 'src/assets/styles'],
322
    lintCommand: 'stylelint "./src/**/*.{vue,scss}" --custom-syntax postcss-html',
323
    dev: {
324
      overrideConfig: {
325
        extends: ['stylelint-config-standard-scss', 'stylelint-config-recommended-vue'],
326
        customSyntax: 'postcss-html',
327
      },
328
    },
329
  },
330
});
331
```
332

333
**Tailwind CSS Project:**
334
```typescript
335
checker({
336
  stylelint: {
337
    lintCommand: 'stylelint "./src/**/*.css"',
338
    dev: {
339
      overrideConfig: {
340
        extends: ['stylelint-config-standard'],
341
        rules: {
342
          'at-rule-no-unknown': [
343
            true,
344
            {
345
              ignoreAtRules: ['tailwind', 'apply', 'variants', 'responsive', 'screen'],
346
            },
347
          ],
348
        },
349
      },
350
    },
351
  },
352
});
353
```
354

355
### Performance Tips
356

357
- Use `.stylelintignore` file to exclude large vendor files
358
- Configure specific file patterns instead of watching entire directories
359
- Use `allowEmptyInput: true` to avoid errors on empty files
360
- Consider separate configurations for development and production builds
361

362
### Troubleshooting
363

364
**Stylelint not found:**
365
```bash
366
npm install --save-dev stylelint stylelint-config-standard
367
```
368

369
**Vue SFC style issues:**
370
```bash
371
npm install --save-dev postcss-html stylelint-config-recommended-vue
372
```
373

374
**SCSS syntax errors:**
375
```bash
376
npm install --save-dev stylelint-config-standard-scss
377
```
378

379
**Custom syntax not working:**
380
Ensure the custom syntax package is installed and properly configured in both the lintCommand and dev.overrideConfig.