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
```