0
# Stylelint Config Recommended
1
2
A recommended shareable configuration for Stylelint that focuses on avoiding CSS errors. This package provides a comprehensive set of rules that help developers detect common CSS mistakes, unknown properties and selectors, and invalid syntax patterns.
3
4
## Package Information
5
6
- **Package Name**: stylelint-config-recommended
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install stylelint-config-recommended --save-dev`
10
11
## Core Imports
12
13
```javascript
14
// Import the configuration object
15
const config = require('stylelint-config-recommended');
16
```
17
18
For ES modules:
19
20
```javascript
21
import config from 'stylelint-config-recommended';
22
```
23
24
## Basic Usage
25
26
Add the configuration to your Stylelint setup:
27
28
```json
29
{
30
"extends": "stylelint-config-recommended"
31
}
32
```
33
34
The configuration can also be extended with additional rules:
35
36
```json
37
{
38
"extends": "stylelint-config-recommended",
39
"rules": {
40
"block-no-empty": null,
41
"unit-allowed-list": ["em", "rem", "s"]
42
}
43
}
44
```
45
46
## Architecture
47
48
Stylelint Config Recommended operates as a **shareable configuration package** within the Stylelint ecosystem. Understanding its architecture helps developers effectively integrate and extend the configuration:
49
50
**Configuration System**: Stylelint uses a modular configuration system where rules can be enabled, disabled, or configured with options. This package provides a curated set of rules focused specifically on error prevention.
51
52
**Shareable Config Pattern**: The package follows Stylelint's shareable config convention by exporting a configuration object that can be extended via the `"extends"` property in Stylelint configurations. This allows multiple projects to share the same rule base while customizing specific rules as needed.
53
54
**Rule Engine Integration**: When Stylelint processes CSS, it loads this configuration and applies each rule in the `rules` object to the CSS being analyzed. Rules are processed independently, with each rule's configuration determining its behavior (enabled/disabled, options, severity level).
55
56
**Extension Hierarchy**: Configurations can extend multiple shareable configs, with later configurations overriding earlier ones. This package is often used as a foundation, extended by more opinionated configs like `stylelint-config-standard`.
57
58
**Peer Dependency Design**: The package requires Stylelint as a peer dependency, ensuring compatibility with the user's specific Stylelint version while avoiding version conflicts in dependency trees.
59
60
## Capabilities
61
62
### Configuration Object
63
64
The main export provides a Stylelint configuration object containing error-prevention rules.
65
66
```javascript { .api }
67
/**
68
* Stylelint configuration object with recommended rules
69
* @type {StylelintConfig}
70
*/
71
module.exports = {
72
rules: {
73
// Rule configurations (see Rules section for complete list)
74
}
75
};
76
77
interface StylelintConfig {
78
rules: Record<string, boolean | [boolean, any] | any>;
79
}
80
```
81
82
### Rules Configuration
83
84
The configuration includes 41 rules focused on preventing CSS errors:
85
86
```javascript { .api }
87
// Annotation and At-rule Validation
88
'annotation-no-unknown': true;
89
'at-rule-descriptor-no-unknown': true;
90
'at-rule-descriptor-value-no-unknown': true;
91
'at-rule-no-deprecated': true;
92
'at-rule-no-unknown': true;
93
'at-rule-prelude-no-invalid': [true, { ignoreAtRules: ['media'] }];
94
95
// Block and Comment Validation
96
'block-no-empty': true;
97
'comment-no-empty': true;
98
99
// Custom Property Validation
100
'custom-property-no-missing-var-function': true;
101
102
// Declaration Block Validation
103
'declaration-block-no-duplicate-custom-properties': true;
104
'declaration-block-no-duplicate-properties': [
105
true,
106
{ ignore: ['consecutive-duplicates-with-different-syntaxes'] }
107
];
108
'declaration-block-no-shorthand-property-overrides': true;
109
'declaration-property-value-keyword-no-deprecated': true;
110
'declaration-property-value-no-unknown': true;
111
112
// Font Family Validation
113
'font-family-no-duplicate-names': true;
114
'font-family-no-missing-generic-family-keyword': true;
115
116
// Function Validation
117
'function-calc-no-unspaced-operator': true;
118
119
// Keyframe Validation
120
'keyframe-block-no-duplicate-selectors': true;
121
'keyframe-declaration-no-important': true;
122
123
// Media Feature and Query Validation
124
'media-feature-name-no-unknown': true;
125
'media-feature-name-value-no-unknown': true;
126
'media-query-no-invalid': true;
127
'media-type-no-deprecated': true;
128
129
// Grid and Nesting Validation
130
'named-grid-areas-no-invalid': true;
131
'nesting-selector-no-missing-scoping-root': true;
132
133
// General CSS Validation
134
'no-descending-specificity': true;
135
'no-duplicate-at-import-rules': true;
136
'no-duplicate-selectors': true;
137
'no-empty-source': true;
138
'no-invalid-double-slash-comments': true;
139
'no-invalid-position-at-import-rule': true;
140
'no-invalid-position-declaration': true;
141
'no-irregular-whitespace': true;
142
143
// Property Validation
144
'property-no-deprecated': true;
145
'property-no-unknown': true;
146
147
// Selector Validation
148
'selector-anb-no-unmatchable': true;
149
'selector-pseudo-class-no-unknown': true;
150
'selector-pseudo-element-no-unknown': true;
151
'selector-type-no-unknown': [true, { ignore: ['custom-elements'] }];
152
153
// String and Syntax Validation
154
'string-no-newline': [true, { ignore: ['at-rule-preludes', 'declaration-values'] }];
155
'syntax-string-no-invalid': true;
156
```
157
158
## Rule Categories
159
160
The rules are organized into the following categories for error prevention:
161
162
**Annotation & At-rule Rules**: Prevent unknown annotations, at-rules, and their descriptors
163
**Block & Comment Rules**: Detect empty blocks and comments
164
**Custom Property Rules**: Ensure proper custom property usage
165
**Declaration Rules**: Prevent duplicate properties and invalid property values
166
**Font Rules**: Validate font family declarations
167
**Function Rules**: Ensure proper function syntax (especially calc)
168
**Keyframe Rules**: Validate keyframe blocks and declarations
169
**Media Rules**: Prevent invalid media queries and features
170
**Grid & Nesting Rules**: Validate CSS Grid and nesting syntax
171
**General CSS Rules**: Catch common CSS structural errors
172
**Property Rules**: Detect unknown and deprecated properties
173
**Selector Rules**: Validate selector syntax and pseudo-elements/classes
174
**String & Syntax Rules**: Prevent invalid strings and syntax patterns
175
176
## Usage Examples
177
178
**Basic Stylelint Configuration:**
179
180
```json
181
{
182
"extends": "stylelint-config-recommended"
183
}
184
```
185
186
**Extending with Custom Rules:**
187
188
```json
189
{
190
"extends": "stylelint-config-recommended",
191
"rules": {
192
"at-rule-no-unknown": [
193
true,
194
{ "ignoreAtRules": ["extends", "tailwind"] }
195
],
196
"property-no-unknown": [
197
true,
198
{ "ignoreProperties": ["composes"] }
199
]
200
}
201
}
202
```
203
204
**Programmatic Usage:**
205
206
```javascript
207
const stylelint = require('stylelint');
208
const config = require('stylelint-config-recommended');
209
210
// Use the configuration object directly
211
const result = await stylelint.lint({
212
code: 'a { color: blue; }',
213
config: config
214
});
215
```
216
217
## Types
218
219
```javascript { .api }
220
/**
221
* Stylelint configuration object structure
222
*/
223
interface StylelintConfig {
224
/** Rule configurations keyed by rule name */
225
rules: {
226
[ruleName: string]: boolean | [boolean, any] | any;
227
};
228
}
229
230
/**
231
* Rule configuration value types
232
*/
233
type RuleConfig =
234
| boolean // Simple enable/disable
235
| [boolean, RuleOptions] // Enable/disable with options
236
| RuleOptions; // Options only (implies enabled)
237
238
interface RuleOptions {
239
[key: string]: any;
240
}
241
```