How to add Stylelint to a Gatsby project (opens in a new tab)

In this post, I will go through the process of adding Stylelint (opens in a new tab) to a Gatsby project.

Pre-requisites

You will need a Gatsby application to try this out. I will be using the Gatsby Starter (opens in a new tab) project that I built. Feel free to use the same or you can use this approach on any Gatsby project.

Read the docs (opens in a new tab) to learn how to create a Gatsby app or explore other starters (opens in a new tab).

Let’s get started

Install the Gatsby Plugin for Stylelint

npm install --save @danbruegge/gatsby-plugin-stylelint

Remarks

I followed the instructions in the documentation (opens in a new tab) but that seems to be outdated. The package gatsby-plugin-stylelint (opens in a new tab) has been deprecated and moved to @danbruegge/gatsby-plugin-stylelint (opens in a new tab).

Also there was the following note in the documentation.

Note

You need your own Stylelint setup. Please have a look at the Stylelint website (opens in a new tab). The intention of this plugin is to inject Stylelint into webpack for gatsbyjs.

This means that installing @danbruegge/gatsby-plugin-stylelint (opens in a new tab) only configures Stylelint for webpack.

Add the plugin to Gatsby Config

Next, we need to add the plugin we just installed to the gatsby.config.js .

The plugin supports config options from stylelint-webpack-plugin (opens in a new tab). I just updated the blob pattern to look for CSS, SASS and SCSS files.

module.exports = {
    plugins: [
        ...
        {
            options: {
                files: [
                    "**/*.{css,sass,scss}"
                ]
            },
            resolve: "@danbruegge/gatsby-plugin-stylelint"
        }
    ],
    ...
};

Install Stylelint package and sharable lint ruleset

Now we need to install stylelint (opens in a new tab) and stylelint-config-standard (opens in a new tab).

npm install --save stylelint stylelint-config-standard

Installing Stylelint package will give access to the Stylelint command and the stylelint-config-standard (opens in a new tab) is a good starting point for configuring Stylelint.

Add a Stylelint configuration file

There are many ways of configuring Stylelint (opens in a new tab) but I prefer to use a JavaScript configuration file.

Click here (opens in a new tab) to read more about alternative configuration methods.

# From the root directory.  
touch stylelint.config.js

Add the following config inside the file that you just created.

module.exports = {
    extends: [
        "stylelint-config-standard"
    ],
    rules: {
        "at-rule-no-unknown": [ true, {
            "ignoreAtRules": [
                "extends",
                "tailwind"
            ]
        }],
        "indentation": 4
    }
};

extends

You can extend any sharable lint configuration here. Read the docs here (opens in a new tab).

rules

Add or override any rules here. Checkout the docs (opens in a new tab) for the list of available rules.

Add helper npm script

It is always best to add npm scripts to execute the linter.

Add the following script in the script section in package.json.

"lint:styles": "stylelint 'src/**/*.{css,scss,sass}' --config stylelint.config.js --allow-empty-input",

This command basically tries to run the linter against the specified file patterns inside the src folder.

--config option can be used to point to our configuration file.

--allow-empty-input ensures that the command is successful if there are no files matching the file patter.

Let’s try it out

Now we can try out and see if the linter integration is working as expected.

Execute the below command to see the result.

I have intentionally violated the indentation rule I had specified for demo purposes.

Stylelint in Action

Conclusion

Hope you found this blog post useful. Feel free to try this out and if you have any suggestions regarding the blog you can log an issue in this repo (opens in a new tab).