Setup a polyrepo

Execute the following steps to setup Stylelint for a polyrepo solution (single project per repository) 👇

Install the packages

Open a terminal at the root of the solution and install the following packages:

pnpm add -D @workleap/stylelint-configs stylelint prettier

Configure Stylelint

First, create a configuration file named .stylelintrc.json at the root of the solution:

root
├── src
├──── ...
├── package.json
├── .stylelintrc.json

Then, open the newly created file and extend the default configuration with the shared configurations provided by @workleap/stylelint-configs:

{
    "$schema": "https://json.schemastore.org/stylelintrc",
    "extends": "@workleap/stylelint-configs"
}

.stylelintignore

Stylelint can be configured to ignore certain files and directories while linting by specifying one or more glob patterns.

To do so, first, create a .stylelintignore file at the root of the solution:

root
├── src
├──── ...
├── package.json
├── .stylelintrc.json
├── .stylelintignore

Then, open the newly created file and paste the following ignore rules:

**/dist/*
node_modules
storybook-static
!.storybook

.prettierrc.json5

@workleap/stylelint-configs formats CSS files with Prettier, through stylelint-prettier, while oxfmt formats the rest of the code. Prettier doesn't read oxfmt's configuration, so give it a CSS-scoped configuration that uses the same options.

First, create a .prettierrc.json5 file at the root of the solution:

root
├── src
├──── ...
├── package.json
├── .stylelintrc.json
├── .stylelintignore
├── .prettierrc.json5

Then, open the newly created file and paste the following configuration:

// stylelint-prettier formats CSS with Prettier, which doesn't read oxfmt.config.ts.
// Keep these options in sync with oxfmt.config.ts.
{
    $schema: "https://json.schemastore.org/prettierrc",
    overrides: [
        {
            files: "*.css",
            options: {
                printWidth: 150,
                tabWidth: 4,
                useTabs: false,
                singleQuote: false,
                endOfLine: "lf"
            }
        }
    ]
}

Configure indent style

Prettier offers built-in rules for configuring the indentation style of a codebase. However, there's a catch: when VS Code auto-formatting feature is enabled, it might conflict with the configured indentation rules if they are set differently.

To guarantees a consistent indentation, we recommend using EditorConfig on the consumer side. With EditorConfig, the indent style can be configured in a single file and be applied consistently across various formatting tools, including Prettier and VS Code.

First, create a .editorconfig file at the root of the solution:

root
├── src
├──── ...
├── package.json
├── .stylelintrc.json
├── .stylelintignore
├── .prettierrc.json5
├── .editorconfig

Then, open the newly created file and paste the following configuration:

root = true

[*]
charset = utf-8
end_of_line = lf
trim_trailing_whitespace = true
insert_final_newline = true
indent_style = space
indent_size = 4

[*.md]
trim_trailing_whitespace = false

[*.{yml,yaml}]
indent_size = 2

Finally, install the EditorConfig.EditorConfig VS Code extension.

Add a CLI script

At times, especially when running the CI build, it's useful to lint the entire solution using a single command. To do so, add the following script to your solution's package.json file:

{
    "lint:stylelint": "stylelint \"**/*.css\" --cache --cache-location node_modules/.cache/stylelint"
}

The script definition may vary depending on your needs and your application configuration. For example, you might want to specify additional file extensions such as "**/*.{css,scss,sass}".

Custom configuration

New projects shouldn't have to customize the default configurations offered by @workleap/stylelint-configs. However, if you are in the process of migrating an existing project to use this library or encountering a challenging situation, refer to the custom configuration page to understand how to override or extend the default configurations. Remember, no locked in ❤️✌️.

Try it 🚀

To test your new setup, open a CSS file, type invalid code (e.g. color: #fff), then save. Open a terminal at the root of the solution and execute the CLI script added earlier:

pnpm lint:stylelint

The terminal should output a linting error.