Shareable stylelint config for CSS and SCSS, following Wagtail’s code style.
Install stylelint, and the config:
npm install --save-dev stylelint @wagtail/stylelint-config-wagtailThen configure stylelint to use this config. As a stylelint.config.js or stylelint.config.mjs in the root of your project:
/** @type {import('stylelint').Config} */
export default {
// See https://github.com/wagtail/stylelint-config-wagtail for rules.
extends: '@wagtail/stylelint-config-wagtail',
};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,
};
/** @type {import('stylelint').Config} */
export default {
// See https://github.com/wagtail/stylelint-config-wagtail for rules.
extends: '@wagtail/stylelint-config-wagtail',
rules: {
...legacyRules,
},
};This project ships two agent skills for AI coding agents:
upgrading-stylelint— for auditing or carrying out a Stylelint upgrade within a project, including checking the upgrade path, reviewing migration guides, updating dependencies or config, running QA, and reporting follow-up work.upgrading-shared-stylelint-config— for upgrading this shared Stylelint configuration itself to a new major release, including updating version constraints, reconfiguring rules, and releasing.
Install the project skills with Vercel Lab’s Agent Skills:
npx skills add wagtail/stylelint-config-wagtailExample prompt:
Use the upgrading-stylelint skill to upgrade this project from Stylelint 16 to 17, including updating to the compatible stylelint-config-wagtail version. Update dependencies and config as needed, update as much of the styles as you can if safe.
We recommend the following run script to add to your package.json:
"lint:css": "stylelint --report-needless-disables --report-unscoped-disables 'src/sass'"- Use
--report-needless-disablesto ensure you do not use morestylelint-disablecomments than needed. - Use
--report-unscoped-disablesto prevent fully disabling linting. - Target specific folders so Stylelint doesn’t attempt to lint other file types, say 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.
We recommend prek, an implementation of the pre-commit framework to manage hooks. Our sample setup uses a standard .pre-commit-config.yaml, so the same configuration also works with pre-commit if needed:
default_language_version:
node: system
repos:
- repo: https://github.com/thibaudcolas/pre-commit-stylelint
rev: v17.9.0
hooks:
- id: stylelint
files: \.(css|scss)$
additional_dependencies:
- stylelint@17.9.0
- '@wagtail/stylelint-config-wagtail@2.0.0'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.jsfor the config definition. This package includes configuration from: