Shareable stylelint config for CSS and SCSS, following Torchbox’s code style.
Install stylelint, and the config:
npm install --save-dev stylelint stylelint-config-torchbox
Then configure stylelint to use this config. As a stylelint.config.js
in the root of your project:
module.exports = {
// See https://github.com/torchbox/stylelint-config-torchbox for rules.
extends: 'stylelint-config-torchbox',
};
Review our CHANGELOG for guidance on how to upgrade a project’s linting to a specific version.
More generally, when retrofitting stricter linting onto an existing project, consider a gradual approach to linting strictness, so you can start using linting without having to change significant portions of the project’s code. Here is an example, disabling commonly hard-to-retrofit rules:
// Rules which we ideally would want to enforce but are reporting too many issues currently.
const legacyRules = {
'max-nesting-depth': null,
'selector-max-specificity': null,
};
module.exports = {
// See https://github.com/torchbox/stylelint-config-torchbox for rules.
extends: 'stylelint-config-torchbox',
rules: {
...legacyRules,
},
};
We recommend the following run
script to add to your package.json
:
"lint:css": "stylelint --report-needless-disables 'src/sass' 'src/vue'"
- Use
--report-needless-disables
flag to ensure you do not use morestylelint-disable
comments than needed. - Target specific folders so Stylelint doesn’t attempt to lint e.g. JS or HTML files.
Stylelint supports ignore patterns in a .stylelintignore
file, however we tend not to use this since we lint all files within a given folder.
This config is Prettier-compatible, there isn’t anything extra needed.
This config should work with Tailwind with no adjustments needed. Please submit an issue if that’s not the case.
Here is a sample setup with our recommended configuration for the pre-commit pre-commit hook framework:
default_language_version:
node: system
repos:
- repo: https://github.com/thibaudcolas/pre-commit-stylelint
rev: v15.10.3
hooks:
- id: stylelint
files: \.(scss|vue)$
additional_dependencies:
- stylelint@15.10.3
- stylelint-config-torchbox@3.0.0
Stylelint supports Vue, and our configuration is usable in .vue
single-file components with no changes. Do make sure linting is configured to check .vue
files:
- Wherever
stylelint
is manually invoked, make sure to point it both at stylesheets, and Vue components:stylelint --report-needless-disables './src/sass' './src/vue_components'
. - With
stylelint-webpack-plugin
, useextensions: ['scss', 'vue'],
. - With
pre-commit
, usefiles: \.(scss|vue)$
.
To get the most out of this config, it is assumed that projects have the following tools set up:
- Prettier for automated formatting of stylesheets.
- Browserslist and autoprefixer.
See
config.js
for the config definition. This package includes configuration from:
For the full list of enabled, disabled, and unused rules, view src/rules.md.
color-named
:never
declaration-block-no-shorthand-property-overrides
declaration-no-important
selector-max-id
:0
selector-max-type
:2, ignore: child, compounded, next-sibling
selector-class-pattern
:, resolveNestedSelectors: true
max-nesting-depth
:4
selector-max-specificity
:0,4,0
value-no-vendor-prefix
property-no-vendor-prefix
selector-no-vendor-prefix
media-feature-name-no-vendor-prefix
at-rule-no-vendor-prefix
declaration-property-value-disallowed-list
:text-align: justify
scss/at-rule-no-unknown
:true, ignoreAtRules: tailwind, apply, variants, responsive, screen, layer
scss/declaration-nested-properties
:never
scss/selector-no-redundant-nesting-selector
scss/percent-placeholder-pattern
:^do-not-use-placeholders$
scss/dollar-variable-no-missing-interpolation
scss/at-mixin-argumentless-call-parentheses
:always
scss/at-mixin-pattern
: ``order/order
:dollar-variables, custom-properties, type: at-rule, hasBlock: false, declarations
scale-unlimited/declaration-strict-value
:color, fill, stroke, /-color/, ignoreKeywords: currentColor, inherit, transparent, initial, none, unset, Canvas, CanvasText, LinkText, VisitedText, ActiveText, ButtonFace, ButtonText, ButtonBorder, Field, FieldText, Highlight, HighlightText, SelectedItem, SelectedItemText, Mark, MarkText, GrayText, AccentColor, AccentColorText
block-no-empty
color-hex-length
:short
color-no-invalid-hex
comment-empty-line-before
:always, except: first-nested, ignore: stylelint-commands
comment-whitespace-inside
:always
custom-property-empty-line-before
:always, except: after-custom-property, first-nested, ignore: after-comment, inside-single-line-block
custom-property-no-missing-var-function
declaration-block-no-duplicate-custom-properties
declaration-block-no-duplicate-properties
:true, ignore: consecutive-duplicates-with-different-syntaxes
declaration-block-single-line-max-declarations
:1
font-family-name-quotes
:always-where-recommended
font-family-no-duplicate-names
font-family-no-missing-generic-family-keyword
function-calc-no-unspaced-operator
function-linear-gradient-no-nonstandard-direction
function-name-case
:lower
function-url-quotes
:always
hue-degree-notation
:angle
import-notation
:string
keyframe-block-no-duplicate-selectors
keyframe-declaration-no-important
keyframe-selector-notation
:percentage-unless-within-keyword-only-block
length-zero-no-unit
:true, ignore: custom-properties
media-feature-name-no-unknown
named-grid-areas-no-invalid
no-duplicate-at-import-rules
no-duplicate-selectors
no-empty-source
no-invalid-double-slash-comments
no-invalid-position-at-import-rule
:true, ignoreAtRules: use, forward
no-irregular-whitespace
number-max-precision
:4
property-no-unknown
rule-empty-line-before
:always-multi-line, except: first-nested, ignore: after-comment
scss/at-else-closing-brace-newline-after
:always-last-in-chain
scss/at-else-closing-brace-space-after
:always-intermediate
scss/at-else-empty-line-before
:never
scss/at-else-if-parentheses-space-before
:always
scss/at-function-parentheses-space-before
:never
scss/at-if-closing-brace-newline-after
:always-last-in-chain
scss/at-if-closing-brace-space-after
:always-intermediate
scss/at-if-no-null
scss/at-import-no-partial-leading-underscore
scss/at-import-partial-extension
:never
scss/at-mixin-parentheses-space-before
:never
scss/at-rule-conditional-no-parentheses
scss/comment-no-empty
scss/declaration-nested-properties-no-divided-groups
scss/dollar-variable-colon-space-after
:always
scss/dollar-variable-colon-space-before
:never
scss/double-slash-comment-whitespace-inside
:always
scss/function-quote-no-quoted-strings-inside
scss/function-unquote-no-unquoted-strings-inside
scss/no-duplicate-mixins
scss/operator-no-newline-after
scss/operator-no-newline-before
scss/operator-no-unspaced
selector-anb-no-unmatchable
selector-attribute-quotes
:always
selector-pseudo-class-no-unknown
selector-pseudo-element-colon-notation
:double
selector-pseudo-element-no-unknown
selector-type-case
:lower
selector-type-no-unknown
:true, ignore: custom-elements
string-no-newline
unit-no-unknown
value-keyword-case
:lower
See the contribution guidelines for guidance and setup instructions.