@bitfactory/stylelint-config

This is a shareable config for Stylelint. All the rules and configurations are already set. Rules can be overridden if needed.

• @bitfactory/stylelint-config
  • :technologist: Development
  • Installing
    • PostCSS projects
    • SASS projects
  • Turning off rules
  • CLI usage
  • Editor / IDE integration
    • Visual Studio Code
    • PhpStorm

:technologist: Development

Publishing

Before publishing a new version:

1. Update the version number in the package.json file.
2. And also update the badges in the README.md file, even for patches.
3. Create a new release, after merging the PR. This will trigger a workflow.
4. The GitHub action workflow will then automatically create a new NPM package.

:package: Installing

Include the config into your project:

make npm "i @bitfactory/stylelint-config --save-dev --save-exact"

make pnpm "i @bitfactory/stylelint-config --save-dev --save-exact"

Then install the dependencies that the config needs:

make npx "install-peerdeps --dev --extra-args="-E" @bitfactory/stylelint-config"

make pnpm "dlx install-peerdeps --dev --extra-args="-E" @bitfactory/stylelint-config"

In your project, create a .stylelintrc.js file with the following contents:

// NOTE: for now this does not work with ESM style modules, somehow `export default` gives errors.
// NOTE: it looks like this file is not checked by eslint with .cjs extension. For now keep it at .js.

/* eslint-disable-next-line unicorn/prefer-module */
module.exports = {
    extends: ['@bitfactory/stylelint-config'],
};

PostCSS projects

To use this config with a PostCSS project, also install the following package:

make npm "i postcss-html --save-dev --save-exact"

make pnpm "i postcss-html --save-dev --save-exact"

And set extends to the following config:

module.exports = {
    extends: ['@bitfactory/stylelint-config/postcss'],
};

The project does not have to use the customSyntax and overrides for postcss anymore. This is included in the config.

PostCSS+SCSS projects

To use this config with a PostCSS with SCSS/SASS project, also install the following packages:

make npm "i postcss-html postcss-scss --save-dev --save-exact"

make pnpm "i postcss-html postcss-scss --save-dev --save-exact"

And set extends to the following config:

module.exports = {
    extends: ['@bitfactory/stylelint-config/scss'],
};

SASS projects

To use this config with a SASS project, also install the following package:

make npm "i stylelint-scss --save-dev --save-exact"

make pnpm "i stylelint-scss --save-dev --save-exact"

And set extends to the following config:

module.exports = {
    extends: ['@bitfactory/stylelint-config/sass'],
};

:firecracker: Turning off rules

To turn off a rule, you can set the value of the rule to null in your .stylelintrc.js file:

module.exports = {
    extends: ['@bitfactory/stylelint-config'],
    rules: {
        'declaration-no-important': null,
    },
};

Or when you only need to turn off a rule for a specific line, use the /* stylelint-disable-line */ comment, followed by the rule:

.selector {
    color: #fff !important; /* stylelint-disable-line declaration-no-important */
}

More about disabling Stylelint rules can be found here.

:rocket: CLI usage

To use Stylelint in the command-line, add the following scripts to your projects package.json:

{
  "scripts": {
    "stylelint": "stylelint '**/*.css'",
    "stylelint:fix": "npm run stylelint -- --fix"
  }
}

{
  "scripts": {
    "stylelint": "stylelint '**/*.css'",
    "stylelint:fix": "pnpm run stylelint --fix"
  }
}

You can run the commands with:

make npm run stylelint
make npm run stylelint:fix

make pnpm run stylelint
make pnpm run stylelint:fix

With PNPM you can also run scripts without 'run' like make pnpm stylelint.

With SCSS use

{
  "scripts": {
    "stylelint": "stylelint '**/*.scss'",
    "stylelint:fix": "npm run stylelint -- --fix"
  }
}

{
  "scripts": {
    "stylelint": "stylelint '**/*.scss'",
    "stylelint:fix": "pnpm run stylelint --fix"
  }
}

With Vue add

{
  "scripts": {
      "stylelint:vue": "stylelint '**/*.vue'",
      "stylelint:vue:fix": "npm run stylelint:vue -- --fix"
  }
}

{
  "scripts": {
      "stylelint:vue": "stylelint '**/*.vue'",
      "stylelint:vue:fix": "pnpm run stylelint:vue --fix"
  }
}

You can run the commands with:

make npm run stylelint:vue
make npm run stylelint:vue:fix

make pnpm run stylelint:vue
make pnpm run stylelint:vue:fix

With PNPM you can also run scripts without 'run' like make pnpm stylelint:vue.

:pencil2: Editor / IDE integration

For Stylelint to work, you need to set up your editor / IDE.

Visual Studio Code

1. Install the Stylelint extension
2. Get linting :rocket:

Additional Extensions

• Error Lens to get inline error messages

:warning: If you have the Prettier extension enabled, make sure to disable the extension for your project's workspace. This is because Prettier's rules will conflict with ours.

PhpStorm

See https://github.com/bitfactory-nl/shared-npm-eslint-config-bitfactory#phpstorm, as we mainly use VSCode/Zed and there currently is no experience in setting this up with PhpStorm.