Getting Started With SCSS-Lint

Share this article

As surprising as it might sound, writing working code is actually the easy part when developing a website, application or any piece of software. Making the whole thing scalable, tested, properly documented and easy to contribute to is the hard part.

One part is having a code base which is both clean and consistent. Clean, because maintaining ugly ‘weird’ code is definitely not a pleasure and consistent because it makes maintaining the code base easier and faster. If code looks the same everywhere in the software, then it should be quite fast to get used to the way it’s written.

When it comes to Sass, there are a couple of things you can do to make your code clean and consistent. The first one would be to respect some coding guidelines, such as CSS Guidelines and Sass Guidelines. The other thing is to lint your codebase.

If you are not familiar with the word lint, here is what Wikipedia says:

In computer programming, lint was the name originally given to a particular program that flagged some suspicious and non-portable constructs (likely to be bugs) in C language source code. The term is now applied generically to tools that flag suspicious usage in software written in any computer language.

What would be a suspicious usage in Sass? It depends on how you define suspicious but, more broadly speaking, it could simply be a matter of making sure the stylesheet remains easily readable and not complex. One example would be to limit the usage of selector nesting to a single level for instance.

To lint our Sass code base, there is one hell of a tool called SCSS-lint. Now let’s start with the bad news: SCSS-lint is a Ruby gem and no matter how you run it (CLI, Grunt, Gulp…), you will need to install this gem beforehand. On the bright side, some lovely folks are currently developing a port of SCSS-lint as a npm package, so we might get rid of this tedious extra step sooner or later. Right. Let’s get this over with:

$ gem install scss_lint

Note: the gem is called scss_lint for naming reason but the command line tool actually is scss-lint. And the library is called SCSS-lint. Because it was not complex enough… :)

Getting starting with the CLI tool

SCSS-lint comes with a lot of options. Actually, so many that it might be a little overwhelming at first. Fortunately, there are actually not so many of those that we’ll use frequently, so let’s have a look at these.

Through the -c or --config option, you can pass the path to a configuration file that will be helpful to define which rules you want to apply to your codebase. For example:

$ scss-lint . --config .scss-lint.yml

Depending on your project, you might want to use the -e or --exclude option to exclude some files or folders from the linting process. For instance, you might not want to lint your third-party libraries or your node modules. For example

$ scss-lint . --exclude ./node_modules/**/*

For more complex usage of --exclude, you can define it in the configuration file passed through --config.

There are other options but I feel like this is more than enough to get started.

The first argument passed to scss-lint is the folder to run on. If omitted, it will default to ., the current folder. If you want to specify a specific folder, you can:

scss-lint ./assets/stylesheets

Configuring the linters

Now that we are ready to lint our Sass code base, we need to define which rules we should stick to. SCSS-lint has a load of linters, as they are called, so much that listing them all here would be too long. I recommend you go through the linters documentation.

The idea is that you create a YAML file at the root of your project, containing all your linting configuration. As a default, SCSS-lint will try to look for a .scss-lint.yml file in the current folder so I recommend you name your file like this. However if you prefer another name, you can; be sure to pass it with the --config option, that’s all.

Sass Guidelines has a configuration file ready for you to grab and use in your project. Be sure to have a more in-depth look if you want to customise things, but all in all it should do the trick.

Linting on committing

One neat thing to do is to make sure the code is clean (linted) when committing with the help of a pre-commit hook. I played a bit with Sass testing and pre-commit hooks in a previous article here at SitePoint entitled testing a Sass library.

In case you are not sure what a pre-commit hook is, basically it is a mechanism aiming at running some operations before a commit being applied. If any of the operations performed raises an error, then the commit gets aborted.

Making sure the code is linted before committing to the remote repository is the perfect use case for a Git hook. In this section, we’ll see how we can set this up in a very easy way.

To do so, we are going to use a very lightweight npm package providing support for Git hooks through the package.json file direction. There are a lot of libraries to do so, but I personally opted for pre-commit. Here is what it looks like:

  "scripts": {
    "lint": "scss-lint ."
  "pre-commit": [

When committing, the pre-commit hook fires and runs the lint npm script (exactly like npm run lint). The lint npm script, as you can see from the code, runs the scss-lint . command. If SCSS-lint returns an error, the commit is aborted and the code needs to be fixed for the commit to pass.

If you run SCSS-lint through Gulp, Grunt or whatever else, you can run a task in the lint npm script instead of using the scss-lint binary directly. Along the same lines, you can pass options like --config or --exclude.

Final thoughts

We can always go further, but I think this is a good introduction to SCSS-lint, and we can actually use it on existing and new projects in a simple yet powerful way.

No reason to keep committing dirty code anymore folks, lint it before pushing it!

Frequently Asked Questions (FAQs) about SCSS Lint

What is the main purpose of SCSS Lint?

SCSS Lint is a tool that helps developers maintain a consistent coding style in their SCSS files. It analyzes your SCSS code and flags any deviations from the defined coding standards. This tool is particularly useful in large projects where multiple developers are working on the same codebase. By enforcing a consistent coding style, SCSS Lint makes the code easier to read, understand, and maintain.

How do I install SCSS Lint?

SCSS Lint is a Ruby gem, so you need to have Ruby installed on your system to use it. Once you have Ruby, you can install SCSS Lint by running the command gem install scss_lint in your terminal. After the installation is complete, you can run scss-lint from the command line to lint your SCSS files.

How do I configure SCSS Lint?

SCSS Lint can be configured by creating a .scss-lint.yml file in the root directory of your project. This file allows you to enable or disable specific linters, and to customize the behavior of the linters. The configuration file uses the YAML syntax, and each linter has its own set of options that you can configure.

Can I use SCSS Lint with other tools?

Yes, SCSS Lint can be integrated with many popular tools and editors. For example, you can use it with task runners like Grunt and Gulp, or with code editors like Sublime Text and Atom. This allows you to lint your SCSS files automatically as part of your development workflow.

What are some common SCSS Lint rules?

SCSS Lint comes with a wide range of rules that enforce good practices in SCSS code. Some common rules include enforcing consistent indentation, disallowing trailing whitespace, and requiring a newline at the end of files. There are also rules for more specific SCSS features, like disallowing the use of ID selectors, or requiring a space before the opening brace of a rule.

How do I ignore certain SCSS Lint warnings?

If there are certain warnings that you want to ignore, you can do so by adding a comment with // scss-lint:disable RuleName before the line of code. To re-enable the rule, you can add another comment with // scss-lint:enable RuleName. You can also disable all linters for a section of code with // scss-lint:disable all.

Can I use SCSS Lint with CSS files?

SCSS Lint is specifically designed for SCSS, which is a superset of CSS. This means that it can lint CSS code, but it may not understand some CSS-specific syntax. If you’re working primarily with CSS, you might want to consider using a CSS-specific linter like Stylelint.

How do I update SCSS Lint?

You can update SCSS Lint by running the command gem update scss_lint in your terminal. This will download and install the latest version of the gem. It’s a good idea to keep your tools up to date to benefit from the latest features and bug fixes.

What are the alternatives to SCSS Lint?

There are several alternatives to SCSS Lint, including Stylelint, CSSLint, and Sass Lint. These tools have similar functionality, but they may have different rules or configuration options. You should choose the tool that best fits your needs and preferences.

How do I uninstall SCSS Lint?

If you no longer need SCSS Lint, you can uninstall it by running the command gem uninstall scss_lint in your terminal. This will remove the gem from your system. If you want to reinstall it later, you can do so by running the installation command again.

Kitty GiraudelKitty Giraudel
View Author

Non-binary trans accessibility & diversity advocate, frontend developer, author. Real life cat. She/they.

AdvancedCSSlintingsasssass testing
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week