0
# stylelint-no-unsupported-browser-features
1

2
A Stylelint plugin that disallows CSS features that are unsupported by your target browser audience. It uses doiuse for browser compatibility checking against the Can I Use database and integrates with browserslist for flexible browser targeting.
3

4
## Package Information
5

6
- **Package Name**: stylelint-no-unsupported-browser-features
7
- **Package Type**: npm  
8
- **Language**: JavaScript (ES modules)
9
- **Installation**: `npm install stylelint-no-unsupported-browser-features`
10

11
## Core Imports
12

13
```javascript
14
import plugin from "stylelint-no-unsupported-browser-features";
15
```
16

17
For CommonJS environments:
18

19
```javascript
20
const plugin = require("stylelint-no-unsupported-browser-features");
21
```
22

23
Note: The plugin is an ES module (`"type": "module"` in package.json), but can be imported in CommonJS environments that support ES module imports.
24

25
## Basic Usage
26

27
Add the plugin to your Stylelint configuration:
28

29
```json
30
{
31
  "plugins": ["stylelint-no-unsupported-browser-features"],
32
  "rules": {
33
    "plugin/no-unsupported-browser-features": true
34
  }
35
}
36
```
37

38
With configuration options:
39

40
```json
41
{
42
  "plugins": ["stylelint-no-unsupported-browser-features"],
43
  "rules": {
44
    "plugin/no-unsupported-browser-features": [
45
      true,
46
      {
47
        "browsers": ["> 1%", "Last 2 versions"],
48
        "ignore": ["rem", "css-table"],
49
        "ignorePartialSupport": true
50
      }
51
    ]
52
  }
53
}
54
```
55

56
Example CSS that would trigger warnings:
57

58
```css
59
/* Triggers warning if targeting IE 8 */
60
div {
61
  display: table;
62
}
63

64
/* Triggers warning if targeting older browsers */
65
.element {
66
  border-radius: 10px;
67
}
68
```
69

70
## Architecture
71

72
The plugin integrates with Stylelint's standard architecture:
73

74
- **Plugin Registration**: Uses `stylelint.createPlugin()` for proper integration
75
- **Rule Implementation**: Processes PostCSS AST nodes and integrates with doiuse
76
- **Browser Detection**: Leverages doiuse library for Can I Use database queries
77
- **Error Reporting**: Uses Stylelint's standard reporting mechanism for consistent output
78
- **Configuration**: Supports standard Stylelint rule option patterns
79

80
## Capabilities
81

82
### Plugin Export
83

84
The main plugin export that integrates with Stylelint. This is a function with additional properties attached.
85

86
```javascript { .api }
87
/**
88
 * Main Stylelint plugin export - a function created by stylelint.createPlugin()
89
 * @param on - Whether the rule is enabled
90
 * @param options - Optional configuration for the rule
91
 * @returns Stylelint rule function
92
 */
93
declare function plugin(on: boolean, options?: PluginOptions): StylelintRule;
94

95
/**
96
 * Plugin properties attached to the main function
97
 */
98
declare namespace plugin {
99
  /** The unique identifier for this Stylelint rule */
100
  const ruleName: "plugin/no-unsupported-browser-features";
101
  
102
  /** Message templates for reporting violations */
103
  const messages: {
104
    rejected: (details: string) => string;
105
  };
106
}
107

108
/**
109
 * Stylelint rule function signature
110
 */
111
interface StylelintRule {
112
  (root: PostCSSRoot, result: StylelintResult): void;
113
}
114

115
/**
116
 * PostCSS AST root node
117
 */
118
interface PostCSSRoot {
119
  // PostCSS AST root containing CSS nodes
120
}
121

122
/**
123
 * PostCSS AST node
124
 */
125
interface PostCSSNode {
126
  // PostCSS AST node representing a CSS declaration, rule, etc.
127
}
128

129
/**
130
 * Stylelint result object for reporting violations
131
 */
132
interface StylelintResult {
133
  // Stylelint result object for rule reporting
134
}
135
```
136

137
### Plugin Configuration
138

139
Configuration options for customizing browser compatibility checks.
140

141
```javascript { .api }
142
interface PluginOptions {
143
  /** Array of browserslist-compatible browser selectors */
144
  browsers?: string[];
145
  /** Array of CSS feature names to ignore */
146
  ignore?: string[];  
147
  /** Whether to ignore features with partial browser support */
148
  ignorePartialSupport?: boolean;
149
}
150
```
151

152
**browsers** - Array of browserslist-compatible strings:
153
- `["> 1%", "Last 2 versions"]` - Modern browser support
154
- `["IE 8", "Chrome >= 60"]` - Specific browser versions
155
- `["defaults"]` - Uses browserslist defaults
156

157
**ignore** - Array of feature names from Can I Use database:
158
- `["rem", "css-table"]` - Ignore specific CSS features
159
- Feature names are shown in error messages
160
- Useful for features with known fallbacks
161

162
**ignorePartialSupport** - Boolean flag for partial support handling:
163
- `true` - Ignore features that are only partially supported
164
- `false` (default) - Report all unsupported features including partial
165
- Helps reduce noise for features with acceptable partial support
166

167
### Browser Targeting
168

169
The plugin uses browserslist for determining target browsers. Browser lists can be specified in multiple ways:
170

171
**Via plugin options:**
172
```json
173
{
174
  "plugin/no-unsupported-browser-features": [
175
    true,
176
    { "browsers": ["> 1%", "Last 2 versions"] }
177
  ]
178
}
179
```
180

181
**Via browserslist config file (`.browserslistrc`):**
182
```text
183
> 1%
184
Last 2 versions
185
```
186

187
**Via package.json:**
188
```json
189
{
190
  "browserslist": ["> 1%", "Last 2 versions"]
191
}
192
```
193

194
### Error Reporting
195

196
The plugin reports violations using Stylelint's standard error format. Based on the source code, error messages are formatted by the `cleanWarningText()` internal function and follow this pattern:
197

198
```javascript { .api }
199
interface StylelintViolation {
200
  ruleName: "plugin/no-unsupported-browser-features";
201
  message: string; // Format: 'Unexpected browser feature "feature-id" is [support description] (plugin/no-unsupported-browser-features)'
202
  node: PostCSSNode; // The CSS node causing the violation
203
  line: number;
204
  column: number;
205
}
206
```
207

208
**Actual Message Format Examples from Tests:**
209
- `Unexpected browser feature "css-table" is not supported by IE 6 (plugin/no-unsupported-browser-features)`
210
- `Unexpected browser feature "rem" is only partially supported by IE 9 (plugin/no-unsupported-browser-features)`
211
- `Unexpected browser feature "css-table" is not supported by IE 6,7 (plugin/no-unsupported-browser-features)` (multiple browsers)
212
- `Unexpected browser feature "rem" is not supported by IE 7 (plugin/no-unsupported-browser-features)` (when ignorePartialSupport removes partial warnings)
213

214
### Integration with doiuse
215

216
The plugin leverages the doiuse library for browser compatibility detection. While this integration is internal, it's important for understanding the plugin's behavior:
217

218
```javascript { .api }
219
// Internal integration details (not directly exposed in public API)
220
interface DoiuseIntegration {
221
  /** Options passed to doiuse processor */
222
  doiuseOptions: {
223
    browsers?: string[];
224
    ignore?: string[];
225
    ignorePartialSupport?: boolean;
226
    onFeatureUsage: (info: FeatureUsageInfo) => void;
227
  };
228
}
229

230
interface FeatureUsageInfo {
231
  usage: PostCSSNode;
232
  featureData: {
233
    missing: boolean;  // True if feature is completely unsupported
234
    partial: boolean;  // True if feature has partial support
235
  };
236
}
237
```
238

239
**Processing Flow:**
240
1. Plugin passes configuration options to doiuse
241
2. doiuse processes the PostCSS AST and identifies unsupported features
242
3. `onFeatureUsage` callback tracks feature data for each CSS node
243
4. doiuse warnings are processed and filtered based on `ignorePartialSupport` setting
244
5. Filtered warnings are reported through Stylelint's reporting mechanism
245

246
### Option Validation
247

248
The plugin validates configuration options using Stylelint's built-in validation:
249

250
```javascript { .api }
251
// Internal validation schema (not directly exposed)
252
interface OptionsValidation {
253
  /** Validation schema for plugin options */
254
  optionsSchema: {
255
    browsers: [(value: any) => boolean];  // Array of functions that check if value is string
256
    ignore: [(value: any) => boolean];    // Array of functions that check if value is string  
257
    ignorePartialSupport: (value: any) => boolean;  // Function that checks if value is boolean
258
  };
259
}
260
```
261

262
**Validation Behavior:**
263
- If options validation fails, the rule returns early without processing
264
- `browsers` and `ignore` options must be arrays of strings
265
- `ignorePartialSupport` must be a boolean value
266
- Invalid options will cause Stylelint to report configuration errors
267

268
## Usage Patterns
269

270
### Development Workflow
271

272
Recommended usage with warning-level severity:
273

274
```json
275
{
276
  "plugins": ["stylelint-no-unsupported-browser-features"],
277
  "rules": {
278
    "plugin/no-unsupported-browser-features": [
279
      true,
280
      {
281
        "severity": "warning"
282
      }
283
    ]
284
  }
285
}
286
```
287

288
This allows builds to continue while highlighting compatibility issues that may need fallbacks.
289

290
### CI/CD Integration
291

292
For build-breaking compatibility checks:
293

294
```json
295
{
296
  "plugins": ["stylelint-no-unsupported-browser-features"],
297
  "rules": {
298
    "plugin/no-unsupported-browser-features": [
299
      true,
300
      {
301
        "browsers": ["> 1%"],
302
        "severity": "error"
303
      }
304
    ]
305
  }
306
}
307
```
308

309
### Feature-Specific Ignoring
310

311
To ignore specific features with handled fallbacks:
312

313
```json
314
{
315
  "plugin/no-unsupported-browser-features": [
316
    true,
317
    {
318
      "ignore": ["rem", "viewport-units", "css-grid"],
319
      "ignorePartialSupport": true
320
    }
321
  ]
322
}
323
```
324

325
## Dependencies
326

327
### Peer Dependencies
328

329
```javascript { .api }
330
// Required peer dependency
331
"stylelint": "^16.0.2"
332
```
333

334
### Direct Dependencies
335

336
```javascript { .api }
337
// Browser compatibility checking
338
"doiuse": "^6.0.5"
339

340
// CSS parsing and processing  
341
"postcss": "^8.4.32"
342
```
343

344
## Error Handling
345

346
The plugin handles various error conditions gracefully:
347

348
- **Invalid Configuration**: Uses Stylelint's `validateOptions` for option validation
349
- **Missing Browserslist**: Falls back to doiuse defaults when no browser list is specified
350
- **Unknown CSS Features**: Passes through doiuse warnings without modification
351
- **Partial Support Edge Cases**: Properly handles mixed partial/full support violations based on `ignorePartialSupport` setting
352

353
## Node.js Requirements
354

355
- **Minimum Node.js**: 18.12.0
356
- **Module Type**: ES Module (package.json: `"type": "module"`)
357
- **Export Path**: `./lib/index.js`