Step by Step: How to setup ktlint with spotless?

Setting up ktlint is easy and straightforward. In a previous post, I explained why I prefer ktlint over detekt. In this article, I use Gradle to configure the linter, but you can use even the command line and run the lint as you need.

Before we start

If you haven’t used Gradle before, I strongly encourage you to go through their example projects and try to play a little with its build script, or even attend to one of their webinars. Because to make this setup work, your project must be set up with Gradle.

Some available plugins for integrating it with ktlint are:

• jlleitschuh/ktlint-gradle – which has an excellent command that generates files for IntelliJ
• jeremymailen/kotlinter-gradle
• diffplug/spotless

In this example, I use Spotless, which is a tool for formatting code according to the configuration of your Gradle script. In other words, it is a plugin. A crucial observation is that spotless itself cannot format Kotlin code style errors without some external help, which in our case is ktlint 😎.

The huge advantage of using spotless over other plugins is when you have more than one language at your principal repository – for instance, you might have some small script written in javascript, python, or other language and you still want to keep it formatted. In this case, spotless gives you an excellent advantage.

Setup ktlint step by step

Create a new project to test it or modify your build.gradle file directly. That’s up to you.

1. Add the spotless plugin ↴

2. Setup spotless ↴

The tricky part here is that even though the ktlint command supports version as a parameter to spotless, it does not support all released versions. So, pay attention because you might experience strange behaviors for some versions (current I’m experiencing this bug). That might happen because this lint does not have a config file as most linters so that some configuration can change over version and spotless breaks.

3. Create your custom rule (Optional)

For this step, you need a module where the custom rules are stored. I suggest you organize custom rules in a different repository and I tell you why.

When creating a custom rule, your teammates may raise their hands 🙋🏽‍♀️🙋🏼‍♂️ and ask the reasons behind each change. It is likely to happen, especially when no ktlint configuration file is present and your team follows all formatting conventions for Kotlin. In this case, it’s essential to start a conversation about each rule. Don’t hesitate to show existing and real examples.

Having a dedicated repository to hold your code guidelines has the advantage of concentrating all the discussions in Pull Request, and all the history of conversation is stored 🧐.

There’s a small problem with spotless: it does not support custom ruleset yet. It’s necessary to use another plugin.

4. After creating a new module, all you have to do is ↴

You can find examples of custom rules I use here. The project is already set up with multi modules, so you can easily add more modules for custom rules.

5. Remember to add RuleSet to your dependencies ↴

The custom rule I created to this example was ↴

As you can see, custom rules accept emojis 🤯!

That is it, folks, you have reached to the end of this quick setup for ktlint. 

Conclusion 

Keep in mind that ktlint was designed to be enough as it is. Even though it has the feature for custom rules, that does not mean we have to create one. Sometimes It’s better to follow official rules or even propose to Kotlin team some new guidelines.

If you don’t need custom rules, I recommend you to use spotless, even though its limitation for ktlint versions. Spotless has many plug-and-play tools in its belt. You could benefit a lot from that. 

If your team need to validate some custom rule, then I recommend you to use one of the other plugins for Gradle. Even more, you can go without plugins at all. I didn’t show you how in this article for the sake of simplicity, but you can find in my gist pretty straightforward Gradle task for ktlint and HTML reporter.

George Guimarães

Co-founder and CEO of SourceLevel. Previously co-founder of Plataformatec.

Loves to talk about software engineering, Elixir, coffee, mechanical keyboards, multitools and his 3 big dogs.