0
# Stylelint Config Taro RN
1

2
Stylelint Config Taro RN provides a shareable Stylelint configuration specifically designed for React Native CSS modules within the Taro framework ecosystem. It includes pre-configured rules that warn developers about CSS properties, selectors, and at-rules that are not compatible with React Native, preventing runtime styling issues by catching incompatible CSS patterns during the linting process.
3

4
## Package Information
5

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

11
## Core Imports
12

13
This package does not require direct imports - it's used as a Stylelint configuration extension in your `.stylelintrc` configuration file.
14

15
## Basic Usage
16

17
Create a `.stylelintrc` configuration file that extends this configuration:
18

19
```json
20
{
21
  "extends": "stylelint-config-taro-rn"
22
}
23
```
24

25
You can also extend and customize the configuration by adding your own rules:
26

27
```json
28
{
29
  "extends": "stylelint-config-taro-rn",
30
  "rules": {
31
    "selector-class-pattern": "^[a-z][a-zA-Z0-9]*$"
32
  }
33
}
34
```
35

36
## Architecture
37

38
The package exports a single Stylelint configuration object that includes:
39

40
- **Taro RN Plugin Rules**: Custom rules from `stylelint-taro-rn` for React Native compatibility
41
- **Standard Stylelint Rules**: Built-in Stylelint rules configured for React Native development
42
- **Warning-based Approach**: Most rules use warnings rather than errors to provide flexibility
43
- **Customizable Severity**: Rules can be overridden to change from warnings to errors or disabled entirely
44

45
## Capabilities
46

47
### Configuration Export
48

49
The main export is a complete Stylelint configuration object with React Native-specific rules.
50

51
```javascript { .api }
52
/**
53
 * Stylelint configuration object for React Native CSS modules
54
 * Contains plugins, rules, and their configurations
55
 */
56
module.exports = {
57
  plugins: string[];
58
  rules: StylelintRules;
59
};
60

61
interface StylelintRules {
62
  // Taro RN specific rules
63
  'taro-rn/css-property-no-unknown': boolean;
64
  'taro-rn/line-height-no-value-without-unit': boolean;
65
  'taro-rn/font-weight-no-ignored-values': [boolean, RuleOptions];
66
  
67
  // Standard Stylelint rules
68
  'value-no-vendor-prefix': boolean;
69
  'property-no-vendor-prefix': boolean;
70
  'at-rule-no-vendor-prefix': boolean;
71
  'media-feature-name-no-vendor-prefix': boolean;
72
  'at-rule-disallowed-list': [string[], RuleOptions];
73
  'unit-allowed-list': [string[], RuleOptions];
74
  'selector-pseudo-class-allowed-list': [string[], RuleOptions];
75
  'selector-max-universal': [number, RuleOptions];
76
  'selector-max-attribute': [number, RuleOptions];
77
  'selector-max-type': [number, RuleOptions];
78
  'selector-max-combinators': [number, RuleOptions];
79
  'selector-max-id': [number, RuleOptions];
80
}
81

82
interface RuleOptions {
83
  severity: 'warning' | 'error';
84
  message: string;
85
}
86
```
87

88
### Taro React Native Plugin Rules
89

90
Rules provided by the `stylelint-taro-rn` plugin that are specific to React Native compatibility.
91

92
#### CSS Property Unknown Check
93

94
```javascript { .api }
95
/**
96
 * Disallows unknown CSS properties that are not supported in React Native
97
 * This rule will error on properties that React Native doesn't recognize
98
 */
99
'taro-rn/css-property-no-unknown': true
100
```
101

102
**Example violations:**
103
```css
104
.example {
105
  word-wrap: break-word; /* ❌ Not supported in React Native */
106
}
107
```
108

109
#### Line Height Unit Requirement
110

111
```javascript { .api }
112
/**
113
 * Requires line-height values to include units for React Native compatibility
114
 * React Native requires explicit units for line-height values
115
 */
116
'taro-rn/line-height-no-value-without-unit': true
117
```
118

119
**Example violations:**
120
```css
121
.example {
122
  line-height: 1; /* ❌ Missing unit, should be 1px, 1rem, etc. */
123
}
124
```
125

126
#### Font Weight Validation
127

128
```javascript { .api }
129
/**
130
 * Warns about font-weight values that are ignored on Android React Native
131
 * Only 400, 700, normal, and bold are supported on Android
132
 */
133
'taro-rn/font-weight-no-ignored-values': [
134
  true,
135
  {
136
    severity: 'warning',
137
    message: '400,700，normal 或 bold 之外的 font-weight 值在Android上的React Native中没有效果'
138
  }
139
]
140
```
141

142
**Example warnings:**
143
```css
144
.example {
145
  font-weight: 300; /* ⚠️ Ignored on Android React Native */
146
  font-weight: 500; /* ⚠️ Ignored on Android React Native */
147
}
148
```
149

150
### Vendor Prefix Rules
151

152
Standard Stylelint rules that disallow vendor prefixes, which are not supported in React Native.
153

154
#### Value Vendor Prefixes
155

156
```javascript { .api }
157
/**
158
 * Disallows vendor prefixes in values
159
 * React Native doesn't support vendor-prefixed values
160
 */
161
'value-no-vendor-prefix': true
162
```
163

164
**Example violations:**
165
```css
166
.example {
167
  display: -webkit-flex; /* ❌ Vendor prefix not supported */
168
}
169
```
170

171
#### Property Vendor Prefixes
172

173
```javascript { .api }
174
/**
175
 * Disallows vendor prefixes in properties
176
 * React Native doesn't support vendor-prefixed properties
177
 */
178
'property-no-vendor-prefix': true
179
```
180

181
**Example violations:**
182
```css
183
.example {
184
  -webkit-transform: scale(1); /* ❌ Vendor prefix not supported */
185
}
186
```
187

188
#### At-Rule Vendor Prefixes
189

190
```javascript { .api }
191
/**
192
 * Disallows vendor prefixes in at-rules
193
 * React Native doesn't support vendor-prefixed at-rules
194
 */
195
'at-rule-no-vendor-prefix': true
196
```
197

198
#### Media Feature Vendor Prefixes
199

200
```javascript { .api }
201
/**
202
 * Disallows vendor prefixes in media feature names
203
 * React Native doesn't support vendor-prefixed media features
204
 */
205
'media-feature-name-no-vendor-prefix': true
206
```
207

208
### React Native Incompatible CSS Rules
209

210
Rules that warn about CSS features that are ignored or not supported in React Native.
211

212
#### Disallowed At-Rules
213

214
```javascript { .api }
215
/**
216
 * Warns about at-rules that are ignored by React Native
217
 * These at-rules have no effect in React Native environments
218
 */
219
'at-rule-disallowed-list': [
220
  ['keyframes', 'font-face', 'supports', 'charset'],
221
  {
222
    severity: 'warning',
223
    message: '@-rule 会被 React Native 忽略'
224
  }
225
]
226
```
227

228
**Example warnings:**
229
```css
230
@keyframes slideIn { /* ⚠️ Ignored by React Native */
231
  from { transform: translateX(-100%); }
232
  to { transform: translateX(0); }
233
}
234

235
@font-face { /* ⚠️ Ignored by React Native */
236
  font-family: 'CustomFont';
237
  src: url('font.ttf');
238
}
239
```
240

241
#### Allowed Units
242

243
```javascript { .api }
244
/**
245
 * Restricts CSS units to those supported by React Native
246
 * Only specific units are supported in React Native
247
 */
248
'unit-allowed-list': [
249
  ['px', 'rem', 'deg', '%', 'vh', 'vw', 'vmin', 'vmax'],
250
  {
251
    severity: 'warning',
252
    message: '该单位会被 React Native 忽略'
253
  }
254
]
255
```
256

257
**Example warnings:**
258
```css
259
.example {
260
  font-size: 1ch; /* ⚠️ 'ch' unit ignored by React Native */
261
  width: 10em; /* ⚠️ 'em' unit ignored by React Native */
262
}
263
```
264

265
#### Pseudo-Class Restrictions
266

267
```javascript { .api }
268
/**
269
 * Only allows :export and :root pseudo-classes
270
 * Other pseudo-classes are ignored by React Native
271
 */
272
'selector-pseudo-class-allowed-list': [
273
  ['export', 'root'],
274
  {
275
    severity: 'warning',
276
    message: '伪类选择器会被 React Native 忽略'
277
  }
278
]
279
```
280

281
**Example usage:**
282
```css
283
:export { /* ✅ Allowed - used for CSS modules */
284
  primaryColor: #007AFF;
285
}
286

287
:root { /* ✅ Allowed - used for CSS variables */
288
  --main-color: #007AFF;
289
}
290

291
.button:hover { /* ⚠️ Warning - ignored by React Native */
292
  background-color: blue;
293
}
294
```
295

296
### Selector Restrictions
297

298
Rules that limit CSS selectors to those supported by React Native.
299

300
#### Universal Selector Restriction
301

302
```javascript { .api }
303
/**
304
 * Disallows universal selectors (warns)
305
 * Universal selectors are ignored by React Native
306
 */
307
'selector-max-universal': [
308
  0,
309
  {
310
    severity: 'warning',
311
    message: '通配选择器会被 React Native 忽略'
312
  }
313
]
314
```
315

316
**Example warnings:**
317
```css
318
* { /* ⚠️ Universal selector ignored by React Native */
319
  box-sizing: border-box;
320
}
321
```
322

323
#### Attribute Selector Restriction
324

325
```javascript { .api }
326
/**
327
 * Disallows attribute selectors (warns)
328
 * Attribute selectors are ignored by React Native
329
 */
330
'selector-max-attribute': [
331
  0,
332
  {
333
    severity: 'warning',
334
    message: '属性选择器会被 React Native 忽略'
335
  }
336
]
337
```
338

339
**Example warnings:**
340
```css
341
input[type="text"] { /* ⚠️ Attribute selector ignored by React Native */
342
  border: 1px solid gray;
343
}
344
```
345

346
#### Type Selector Restriction
347

348
```javascript { .api }
349
/**
350
 * Disallows type selectors (warns)
351
 * Type selectors are ignored by React Native
352
 */
353
'selector-max-type': [
354
  0,
355
  {
356
    severity: 'warning',
357
    message: '通配选择器会被 React Native 忽略'
358
  }
359
]
360
```
361

362
**Example warnings:**
363
```css
364
div { /* ⚠️ Type selector ignored by React Native */
365
  display: flex;
366
}
367
```
368

369
#### Combinator Restriction
370

371
```javascript { .api }
372
/**
373
 * Disallows combinator selectors (warns)
374
 * Combinator selectors are ignored by React Native
375
 */
376
'selector-max-combinators': [
377
  0,
378
  {
379
    severity: 'warning',
380
    message: '组合选择器会被 React Native 忽略'
381
  }
382
]
383
```
384

385
**Example warnings:**
386
```css
387
.parent > .child { /* ⚠️ Combinator selector ignored by React Native */
388
  margin: 10px;
389
}
390

391
.foo + .bar { /* ⚠️ Adjacent sibling combinator ignored by React Native */
392
  color: red;
393
}
394
```
395

396
#### ID Selector Restriction
397

398
```javascript { .api }
399
/**
400
 * Disallows ID selectors (warns)
401
 * ID selectors are ignored by React Native
402
 */
403
'selector-max-id': [
404
  0,
405
  {
406
    severity: 'warning',
407
    message: 'ID 选择器会被 React Native 忽略'
408
  }
409
]
410
```
411

412
**Example warnings:**
413
```css
414
#header { /* ⚠️ ID selector ignored by React Native */
415
  background-color: blue;
416
}
417
```
418

419
## Configuration Customization
420

421
### Disabling Rules
422

423
To disable specific rules, set them to `null`:
424

425
```json
426
{
427
  "extends": "stylelint-config-taro-rn",
428
  "rules": {
429
    "taro-rn/font-weight-no-ignored-values": null,
430
    "at-rule-disallowed-list": null,
431
    "unit-allowed-list": null,
432
    "selector-pseudo-class-allowed-list": null,
433
    "selector-max-universal": null,
434
    "selector-max-attribute": null,
435
    "selector-max-type": null,
436
    "selector-max-combinators": null,
437
    "selector-max-id": null
438
  }
439
}
440
```
441

442
### Changing Warnings to Errors
443

444
For React Native-only projects, you might want to change warnings to errors:
445

446
```json
447
{
448
  "extends": "stylelint-config-taro-rn",
449
  "rules": {
450
    "at-rule-disallowed-list": [
451
      ["keyframes", "font-face", "supports", "charset"],
452
      {
453
        "severity": "error",
454
        "message": "the @-rule is ignored by React Native."
455
      }
456
    ],
457
    "unit-allowed-list": [
458
      ["px", "rem", "deg", "%", "vh", "vw", "vmin", "vmax"],
459
      {
460
        "severity": "error",
461
        "message": "the unit is ignored by React Native."
462
      }
463
    ],
464
    "selector-pseudo-class-allowed-list": [
465
      ["export", "root"],
466
      {
467
        "severity": "error",
468
        "message": "pseudo class selectors are ignored by React Native."
469
      }
470
    ],
471
    "selector-max-universal": [
472
      0,
473
      {
474
        "severity": "error",
475
        "message": "universal selectors are ignored by React Native."
476
      }
477
    ],
478
    "selector-max-attribute": [
479
      0,
480
      {
481
        "severity": "error",
482
        "message": "attribute selectors are ignored by React Native."
483
      }
484
    ],
485
    "selector-max-type": [
486
      0,
487
      {
488
        "severity": "error",
489
        "message": "type selectors are ignored by React Native."
490
      }
491
    ],
492
    "selector-max-combinators": [
493
      0,
494
      {
495
        "severity": "error",
496
        "message": "combinator selectors are ignored by React Native."
497
      }
498
    ],
499
    "selector-max-id": [
500
      0,
501
      {
502
        "severity": "error",
503
        "message": "id selectors are ignored by React Native."
504
      }
505
    ]
506
  }
507
}
508
```
509

510
## Dependencies
511

512
- **stylelint-taro-rn**: Provides React Native-specific Stylelint rules (workspace dependency)
513
- **stylelint**: Peer dependency (^16) - the main Stylelint package
514

515
Both dependencies must be installed alongside this configuration package. The package.json defines:
516
- `stylelint-taro-rn` as both a dependency and peer dependency (workspace:*)
517
- `stylelint` as a peer dependency (^16) and dev dependency (^16.4.0)
518
- Node.js requirement: >= 18