0
# stylelint-config-recommended-scss
1

2
stylelint-config-recommended-scss is a shareable configuration for Stylelint that provides comprehensive SCSS linting rules. It extends the base stylelint-config-recommended configuration and bundles the stylelint-scss plugin pack with postcss-scss custom syntax to enable complete linting of SCSS code, checking for possible errors and enforcing best practices.
3

4
## Package Information
5

6
- **Package Name**: stylelint-config-recommended-scss
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev stylelint-config-recommended-scss`
10

11
## Core Imports
12

13
This package exports a single configuration object that is used by Stylelint's configuration system:
14

15
```javascript
16
// The package exports the configuration object directly
17
const config = require('stylelint-config-recommended-scss');
18
```
19

20
For ES modules (CommonJS interop):
21

22
```javascript
23
import config from 'stylelint-config-recommended-scss';
24
```
25

26
## Basic Usage
27

28
Set your `.stylelintrc.json` config to extend this package:
29

30
```json
31
{
32
  "extends": "stylelint-config-recommended-scss"
33
}
34
```
35

36
Extend with custom rules:
37

38
```json
39
{
40
  "extends": "stylelint-config-recommended-scss",
41
  "rules": {
42
    "scss/at-if-no-null": null
43
  }
44
}
45
```
46

47
## Architecture
48

49
stylelint-config-recommended-scss is built around several key components that work together to provide comprehensive SCSS linting:
50

51
- **Base Configuration Extension**: Extends `stylelint-config-recommended` and adapts its rules for SCSS compatibility by selectively disabling conflicting rules
52
- **Custom Syntax Integration**: Bundles `postcss-scss` to enable proper parsing of SCSS syntax features like variables, mixins, and nested rules
53
- **Plugin Integration**: Automatically loads the `stylelint-scss` plugin pack to provide SCSS-specific linting rules
54
- **Rule Configuration**: Provides 25 carefully curated rules (10 disabled core rules, 5 enabled core rules, 15 SCSS-specific rules) focused on error detection rather than style enforcement
55
- **Dependency Management**: Handles all required dependencies internally, requiring only Stylelint itself as a peer dependency
56

57
## Capabilities
58

59
### Configuration Object Export
60

61
The package exports a complete Stylelint configuration object that includes extends, plugins, custom syntax, and rules.
62

63
```javascript { .api }
64
/**
65
 * Main export: Complete Stylelint configuration object
66
 * @type {StylelintConfig}
67
 */
68
const config: StylelintConfig;
69

70
interface StylelintConfig {
71
  /** Base configurations to extend */
72
  extends: string[];
73
  /** PostCSS custom syntax for parsing SCSS */
74
  customSyntax: object;
75
  /** Stylelint plugins to load */
76
  plugins: string[];
77
  /** Linting rules configuration */
78
  rules: StylelintRules;
79
}
80

81
interface StylelintRules {
82
  // Core Stylelint rules (modified for SCSS compatibility)
83
  'annotation-no-unknown': null;
84
  'at-rule-descriptor-no-unknown': null;
85
  'at-rule-descriptor-value-no-unknown': null;
86
  'at-rule-no-unknown': null;
87
  'at-rule-prelude-no-invalid': null;
88
  'color-no-invalid-hex': boolean;
89
  'comment-no-empty': null;
90
  'declaration-property-value-no-unknown': null;
91
  'function-linear-gradient-no-nonstandard-direction': boolean;
92
  'function-no-unknown': null;
93
  'media-feature-name-value-no-unknown': null;
94
  'media-query-no-invalid': null;
95
  'no-invalid-position-at-import-rule': [boolean, { ignoreAtRules: string[] }];
96
  'string-no-newline': boolean;
97
  'unit-no-unknown': boolean;
98
  
99
  // SCSS-specific rules (from stylelint-scss plugin)
100
  'scss/at-extend-no-missing-placeholder': boolean;
101
  'scss/at-if-no-null': boolean;
102
  'scss/at-rule-no-unknown': boolean;
103
  'scss/comment-no-empty': boolean;
104
  'scss/declaration-nested-properties-no-divided-groups': boolean;
105
  'scss/dollar-variable-no-missing-interpolation': boolean;
106
  'scss/function-quote-no-quoted-strings-inside': boolean;
107
  'scss/function-unquote-no-unquoted-strings-inside': boolean;
108
  'scss/load-no-partial-leading-underscore': boolean;
109
  'scss/load-partial-extension': 'never';
110
  'scss/no-duplicate-mixins': boolean;
111
  'scss/no-global-function-names': boolean;
112
  'scss/operator-no-newline-after': boolean;
113
  'scss/operator-no-newline-before': boolean;
114
  'scss/operator-no-unspaced': boolean;
115
}
116
```
117

118
### Configuration Properties
119

120
#### extends Property
121

122
Specifies base configurations to extend.
123

124
```javascript { .api }
125
extends: ['stylelint-config-recommended']
126
```
127

128
The configuration extends `stylelint-config-recommended` and adapts its rules for SCSS compatibility.
129

130
#### customSyntax Property
131

132
Configures PostCSS custom syntax for parsing SCSS files.
133

134
```javascript { .api }
135
customSyntax: postcssScss
136
```
137

138
Uses `postcss-scss` package to enable proper SCSS syntax parsing.
139

140
#### plugins Property  
141

142
Specifies Stylelint plugins to load.
143

144
```javascript { .api }
145
plugins: ['stylelint-scss']
146
```
147

148
Bundles the `stylelint-scss` plugin pack for SCSS-specific linting rules.
149

150
#### rules Property
151

152
Contains the complete rules configuration with 25 total rules.
153

154
```javascript { .api }
155
rules: {
156
  // Core rules disabled for SCSS compatibility (10 rules)
157
  'annotation-no-unknown': null,
158
  'at-rule-descriptor-no-unknown': null,
159
  'at-rule-descriptor-value-no-unknown': null,
160
  'at-rule-no-unknown': null,
161
  'at-rule-prelude-no-invalid': null,
162
  'comment-no-empty': null,
163
  'declaration-property-value-no-unknown': null,
164
  'function-no-unknown': null,
165
  'media-feature-name-value-no-unknown': null,
166
  'media-query-no-invalid': null,
167
  
168
  // Core rules enabled (5 rules)
169
  'color-no-invalid-hex': true,
170
  'function-linear-gradient-no-nonstandard-direction': true,
171
  'no-invalid-position-at-import-rule': [true, { ignoreAtRules: ['use', 'forward'] }],
172
  'string-no-newline': true,
173
  'unit-no-unknown': true,
174
  
175
  // SCSS-specific error detection rules (15 rules)
176
  'scss/at-extend-no-missing-placeholder': true,
177
  'scss/at-if-no-null': true,
178
  'scss/at-rule-no-unknown': true,
179
  'scss/comment-no-empty': true,
180
  'scss/declaration-nested-properties-no-divided-groups': true,
181
  'scss/dollar-variable-no-missing-interpolation': true,
182
  'scss/function-quote-no-quoted-strings-inside': true,
183
  'scss/function-unquote-no-unquoted-strings-inside': true,
184
  'scss/load-no-partial-leading-underscore': true,
185
  'scss/load-partial-extension': 'never',
186
  'scss/no-duplicate-mixins': true,
187
  'scss/no-global-function-names': true,
188
  'scss/operator-no-newline-after': true,
189
  'scss/operator-no-newline-before': true,
190
  'scss/operator-no-unspaced': true
191
}
192
```
193

194
### Dependencies
195

196
The configuration automatically handles these dependencies:
197

198
```javascript { .api }
199
interface Dependencies {
200
  /** Runtime dependencies bundled with the config */
201
  dependencies: {
202
    'postcss-scss': '^4.0.9';
203
    'stylelint-config-recommended': '^17.0.0';
204
    'stylelint-scss': '^6.12.1';
205
  };
206
  
207
  /** Required peer dependencies */
208
  peerDependencies: {
209
    'postcss': '^8.3.3';  // optional
210
    'stylelint': '^16.23.1';  // required
211
  };
212
}
213
```
214

215
## Usage Examples
216

217
### CLI Usage
218

219
```bash
220
# Run Stylelint with the config
221
npx stylelint "**/*.scss" --config-extends stylelint-config-recommended-scss
222
```
223

224
### Programmatic Usage
225

226
```javascript
227
import stylelint from 'stylelint';
228
import config from 'stylelint-config-recommended-scss';
229

230
const result = await stylelint.lint({
231
  code: scssCode,
232
  config: config
233
});
234
```
235

236
### Configuration File Usage
237

238
```json
239
{
240
  "extends": "stylelint-config-recommended-scss",
241
  "rules": {
242
    "scss/at-if-no-null": null
243
  }
244
}
245
```
246

247
### Package.json Scripts
248

249
```json
250
{
251
  "scripts": {
252
    "lint:scss": "stylelint '**/*.scss'",
253
    "lint:scss:fix": "stylelint '**/*.scss' --fix"
254
  }
255
}
256
```