Prettier, Stylelint for SCSS with WordPress

If you’re working on a WordPress plugin or theme and want to conform to WordPress CSS coding standards, WordPress offers Stylelint and Prettier configurations that are easy to install. But their documentation is frankly a little lacking when it comes to linting and formatting SCSS. Not to mention the headaches involved with getting these two tools t play well together. Luckily, this article is going to show you exactly how to set up Prettier and Stylelint for WordPress coding standards.

If you want to lint and format your Javascript, don’t miss this post on setting ESLint and Prettier up to meet WordPress Coding Standards.

Estimated reading time: 4 minutes

Installing The WordPress Stylelint Config

Step one, setting up Stylelint for SCSS is simple enough and covered in the WordPress documentation found here.

If your package manager is NPM:

npm install @wordpress/stylelint-config --save-dev

If you use Yarn:

yarn add @wordpress/stylelint-config -D

You can confirm that this config has been added to your package.json in your devDependencies key.

Create a StylelintRC file

Next up create a file in your root directory like this .stylelintrc.json

Inside this file add the following extends property and save. Notice that this config is specifically for SCSS. We’re going to come back to this file but first we need to set up prettier.

{
"extends": "@wordpress/stylelint-config/scss"
}

Install Prettier

We need to install the prettier package to our project so we can run it on our files. Now, to get our SCSS ready for WordPress coding standards we need to install prettier so that we can then install WordPress’ configuration.

With NPM:

npm install --save-dev --save-exact prettier

With Yarn:

yarn add prettier --exact -D

Install the WordPress Prettier config

For NPM:

npm install @wordpress/prettier-config --save-dev

For Yarn:

yarn add @wordpress/prettier-config -D

You should now see “@wordpress/prettier-config”, “@wordpress/stylelint-config”, and “prettier” in your devDependencies key in your package.json.

Create a prettierrc file

Create a file in your root project folder titled .prettierrc and add the following like as is, (no curly brackets or anything).

"@wordpress/prettier-config"

Now go ahead and save.

You can test if prettier is formatting your scss code by running the following command in your terminal:

npx prettier -w **/*.scss

You should get back a message in your terminal if this is successful:

Add a script in your package.json to run prettier on your SCSS

In your package.json file in the scripts key add the following:

"scripts": {
"lint:scss": "npx prettier -w **/*.scss"
}

Update the script to lint your SCSS using Stylelint

Update the same script like this:

"lint:scss": "npx prettier -w **/*.scss && stylelint **/*.scss"

Now you can run this simple command below to get Prettier and Stylelint formatting and linting all of your SCSS to meet WordPress coding standards.

npm run lint:scss

Want to set up Typescript and ESLint in your WordPress project too? Don’t miss this must see guide.

Dealing with Stylelint & Prettier conflicts

Now if you have noticed stylelint is pointing out errors in your SCSS, and if you are getting flagged with the warning “Expected empty line before rule (rule-empty-line-before) Stylelintrule-empty-line-before“, you might have fixed this only to notice that prettier overwrites your fix when you run your lint script again. BUMMER!

Don’t fret! You don’t need to turn this rule off to make prettier and stylelint play nicely. Instead, let’s add a few more things to our Stylelint file.

Configure Prettier to control formatting:

Prettier is a code formatter, and because it can automatically format our code, we should leave the formatting linting rules out of our Stylelint configuration. Enter the stylelint-config-prettier package.

In your terminal add this to your package.json

Using NPM:

npm install --save-dev stylelint-config-prettier

Using Yarn

yarn add stylelint-config-prettier -D

Prevent SCSS Linting issues with Stylelint

One more way we can prevent rules from causing issues with SCSS is to include the stylelint-scss plugin. There are some peer dependency issues with the next package and the wordpress-config, so be sure to include the version like shown below.

Using NPM:

npm i --save-dev stylelint-scss@^4.0.0

Yarn:

yarn add stylelint-scss@^4.0.0 -D

Update our StylelintRC file

Now we can update our .stylelintrc.json file like so:

{
	"extends": ["@wordpress/stylelint-config/scss", "stylelint-config-prettier"],
	"plugins": ["stylelint-scss"]
}

Resolving the empty rule-empty-line-before stylelint rule:

Finally we are going to update our Stylelint rule rule-empty-line-before with exceptions so that Stylelint will always require an empty line before a block except when the block is the first nested selector, and after a single line comment.

This is really about personal preference, or project agreed upon preferences. Read through the options for this rule and determine how you want your code to look:

"rules": {
		"rule-empty-line-before": [
			"always",
			{
				"except": ["first-nested", "after-single-line-comment"]
			}
		]
	}