Scalafix Tutorial: Setup, Rules, Configuration

Scalafix is a code refactoring and linting tool that automatically fixes and improves Scala code. Here's what you need to know:

What Scalafix Does:

• Spots and fixes code issues automatically
• Updates old code patterns to modern syntax
• Enforces consistent code style
• Helps with Scala version migrations

Key Components:

Quick Setup:

1. Add to project/plugins.sbt:

addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.13.0")

2. Update build.sbt:

inThisBuild(List(
  semanticdbEnabled := true,
  semanticdbVersion := scalafixSemanticdb.revision
))

Requirements:

Most Used Rules:

• RemoveUnused: Cleans up dead code
• ExplicitResultTypes: Adds missing types
• OrganizeImports: Structures imports
• DisableSyntax: Blocks unwanted patterns

This guide walks you through setting up Scalafix, using built-in rules, creating custom rules, and integrating with your build tools.

Related video from YouTube

Before You Start

Here's what you need to set up Scalafix on your machine.

Required Tools

Setting Up Scala

Start by installing Java. Then add these settings to your .jvmopts file:

-Xss8m
-Xms1G
-Xmx8G

Build Tool Setup

First, add this to project/plugins.sbt:

addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.13.0")

Next, update your build.sbt:

inThisBuild(
  List(
    scalaVersion := "2.13.15",
    semanticdbEnabled := true,
    semanticdbVersion := scalafixSemanticdb.revision
  )
)

IDE Setup

For VS Code:

1. Install Metals extension
2. Remove other Scala extensions
3. Run this command:

scala-cli setup-ide . --scala 2.13

This creates two files:

• .bsp/scala-cli.json for Build Server Protocol
• .scala-build/ide-options-v2.json for IDE settings

For IntelliJ:

1. Install Scala plugin
2. Import project as sbt project
3. Enable Build Server Protocol

Don't forget to restart your IDE after making these changes.

Setting Up Scalafix

Here's how to add Scalafix to your project.

Adding the Plugin

In project/plugins.sbt, add:

addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.13.0")

For Scala 2.11, use this instead:

addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.10.4")

Setting Up SemanticDB

Add to your build.sbt:

inThisBuild(
  List(
    scalaVersion := "2.13.15",
    semanticdbEnabled := true,
    semanticdbVersion := scalafixSemanticdb.revision,
    scalacOptions += "-Wunused:imports"
  )
)

For Scala 2.12, use this option instead:

scalacOptions += "-Ywarn-unused-import"

Project Setup

You'll need these folders:

Want a quick start? Run:

sbt new scalacenter/scalafix.g8 --repo="YourRepoName"

Basic Config File

Make a .scalafix.conf file:

rules = [
  DisableSyntax
]

DisableSyntax.noFinalize = true

For CI, add:

lint.error = [
  ".*"
]

To run Scalafix:

sbt "scalafix RemoveUnused"   # one project
sbt scalafixAll              # all projects

For tests:

sbt "Test / scalafix"

Scalafix Rules Explained

Scalafix comes with two types of rules to fix and improve your code.

Built-in Rules

Here's what each built-in rule does:

Rule Types

Scalafix splits rules into two main groups:

Using Rules

Pick rules based on what you want to fix:

• Need Java/Scala interop? Go with ExplicitNonNullaryApply
• Want better type safety? Add ExplicitResultTypes
• Looking for clean imports? Use OrganizeImports

Setting Up Rules

Here's how to set up rules in .scalafix.conf:

rules = [
  DisableSyntax,
  ExplicitResultTypes
]

# Rule-specific settings
ExplicitResultTypes {
  memberVisibility = [
    public,
    protected
  ]
  skipSimpleDefinitions = false
}

# Import blocks
OrganizeImports {
  groups = [
    "java.",
    "scala.",
    "*"
  ]
}

Scalafix runs rules in parallel, making it faster than regular compiler plugins.

Basic Settings

Here's how to set up and use Scalafix configuration:

Config File Layout

Scalafix looks for .scalafix.conf in your project's root folder. It uses HOCON format:

# Pick your rules
rules = [
  DisableSyntax,
  ExplicitResultTypes
]

# Set rule options
DisableSyntax.noFinalize = true
ExplicitResultTypes.skipSimpleDefinitions = false

HOCON Basics

Rule Settings

You can configure rules in three ways:

Common Settings

Here's what most teams use:

# Pick rules
rules = [
  DisableSyntax,
  RemoveUnused
]

# Auto-run these
triggered.rules = [
  DisableSyntax
]

# Handle errors
lint.error = [
  "DisableSyntax"
]

# Handle imports
OrganizeImports {
  groups = [
    "java.",
    "scala.",
    "*"
  ]
}

Want to change settings from the command line? Use --settings:

scalafix --settings.DisableSyntax.noFinalize=true

Using Built-in Rules

Scalafix ships with 4 key rules to keep your Scala code clean. Let's see how each one works:

Type Annotations

The ExplicitResultTypes rule adds missing type info to your methods:

// Before
def process = List(1,2,3).map(_ * 2)

// After
def process: List[Int] = List(1,2,3).map(_ * 2)

Here's how to set it up in .scalafix.conf:

ExplicitResultTypes {
  skipSimpleDefinitions = false
  skipLocalImplicits = true
}

Import Cleanup

The OrganizeImports rule keeps your imports tidy. Add this to your config:

OrganizeImports {
  groups = [
    "java.",
    "scala.",
    "*"
  ]
  removeUnused = true
  blankLines = 1
}

Removing Unused Code

The RemoveUnused rule cuts dead code. First, turn on these compiler flags:

• Scala 2.12: -Ywarn-unused
• Scala 2.13: -Wunused
• Scala 3.3.4+: -Wunused:all

Then configure what to remove:

RemoveUnused {
  imports = true
  privates = true
  locals = true
  patternvars = true
  params = true
}

Syntax Restrictions

The DisableSyntax rule blocks code patterns you don't want:

DisableSyntax {
  noVars = true
  noNulls = true
  noReturns = true
  noWhileLoops = true
  noFinalize = true
}

Making Custom Rules

Let's walk through how to build custom rules for your code checks and fixes.

Creating Rules

Your project needs a specific folder setup. For a single project:

repository/
├── build.sbt
└── src/
    └── scalafix/
        ├── resources/META-INF/services/
        │   └── scalafix.v1.Rule
        └── scala/fix/
            └── MyRule1.scala

Working with multiple projects? Use this structure:

repository/
├── build.sbt
└── scalafix/
    ├── input/src/main/scala/fix/
    ├── output/src/main/scala/fix/
    ├── rules/src/main/scala/fix/
    └── tests/src/test/scala/fix/

Testing Rules

The scalafix-testkit helps you test your rules. Here's what each folder does:

Here's a test case example:

// Input file
val x = List(1, "") // assert: NoInfer.any

// Output file
val x: List[Any] = List(1, "")

Rule Writing Tips

You can write two types of rules:

Look at this semantic rule that adds names to arguments:

// Before
complete(true)

// After
complete(isSuccess = true)

Finding and Fixing Bugs

Here's how to debug your rules:

1. Run your rule:

sbt> scalafix MyRule1

2. Look at what changed between input and output

3. Add tests for weird cases

4. Use // scalafix:ok to skip specific lines

For CI, add this to your build:

scalafixDependencies += "org.fix" %% "custom-rule" % "1.0.0"

Run your checks:

sbt "scalafixEnable; scalafixAll --check"

sbb-itb-bfaad5b

Build Tool Setup

Here's how to set up Scalafix in your project:

sbt Setup

First, add the Scalafix plugin to project/plugins.sbt:

addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.13.0")

For Scala 2.x, put these settings in build.sbt:

inThisBuild(
  List(
    scalaVersion := "2.12.20",
    semanticdbEnabled := true,
    semanticdbVersion := scalafixSemanticdb.revision
  )
)

Multiple Projects

Working with multiple modules? Here's how to structure your build.sbt:

lazy val core = (project in file("core"))
  .settings(commonSettings)

lazy val mod1 = (project in file("mod1"))
  .dependsOn(core)
  .settings(commonSettings)

CI Pipeline Setup

Add these commands to your CI pipeline:

# Verify code without changes
sbt "scalafixEnable; scalafixAll --check"

# Speed up builds with caching
cache:
  paths:
    - ~/.cache/coursier

Auto-checks

Want Scalafix to run automatically? Add this to build.sbt:

scalafixOnCompile := true

Configure auto-run rules in .scalafix.conf:

triggered.rules = [
  DisableSyntax
]

Advanced Settings

Multi-project Config

Here's how to share configs across Scala projects using a core module:

# core/application.conf
rules = [
  DisableSyntax
  NoAutoTupling
]

Want to add these core settings to other modules? Just include them:

# mod1/application.conf
include "core/application.conf"

# Add module-specific rules
rules += RemoveUnused

Custom Rule Settings

Here's how to set up rules in .scalafix.conf:

# Customize rule settings
DisableSyntax.noVars = true
DisableSyntax.noNulls = true
RemoveUnused.imports = true

# Override lint behavior
lint.error = [
  ".*"
  "-UnusedScalafixSuppression"
]

Error Management

Got Scalafix issues? Here's what to do:

Speed Improvements

Want faster Scalafix runs? Try these settings:

Pro tip: For codebases with over 10,000 lines, skip the ExplicitNonNullaryApply rule. It can eat up memory because of SemanticDB limits.

Fix Common Problems

Here's what you need to know about fixing Scalafix issues:

Known Issues

Error Guide

Fix Configuration

Here's what you need in your build.sbt:

addCompilerPlugin("org.scalameta" % "semanticdb-scalac" % "4.10.2" cross CrossVersion.full)
scalacOptions += "-Yrangepos"
semanticdbVersion := "4.4.11"

Handle Rule Conflicts

Pro tip: Most version-related errors happen when you update Scala but forget to update the Scalafix plugin. Always check your semanticdb version in build.sbt after updates.

Tips and Tricks

File Organization

Here's how to set up your Scalafix files:

Rule Selection

Here's what matters when picking rules:

Config Management

Here's a simple config setup:

// .scalafix.conf
rules = [
  RemoveUnused,
  ExplicitResultTypes,
  LeakingImplicitClassVal
]

ExplicitResultTypes {
  memberKind = [Val, Def, Var]
  skipSimpleDefinitions = false
}

Git Integration

Set up GitHub Actions for Scalafix:

name: "Scalafix"
on: [pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run Scalafix
        env:
          JAVA_OPTS: -Xmx8G -Xms1G -Xss8M
        run: sbt "scalafix RemoveUnused"

Want faster builds? Keep your build graph shallow.

Boost your build speed with these JVM settings:

GraalVM performance options:

Help and Resources

Here's what you need to know about getting started with Scalafix and finding help when you need it.

Core Documentation

The docs cover everything you need to run Scalafix:

Popular Community Rules

These community-made rules can help improve your code:

Want to use these rules? Add them to your build:

// build.sbt
ThisBuild / scalafixDependencies += "GROUP" %% "ARTIFACT" % "VERSION"

Where to Get Help

Need help? Here's where to go:

Stay Up to Date

Keep track of what's new:

Check if your rules need updates:

sbt "scalafix --check"

Update rules on the fly:

sbt "scalafix dependency:RULE@GROUP::ARTIFACT:VERSION"

Summary

Here's what you need to know about Scalafix:

Let's look at some before/after examples:

What can Scalafix do? It helps you:

• Fix code automatically
• Update old code to modern syntax
• Find and change specific patterns
• Work with sbt, Maven, Mill, and Gradle
• Build your own rules

Here's where teams use it most:

Bottom line: Scalafix makes your code better by fixing issues, keeping things consistent, and helping you move to newer Scala versions. It's like having an extra team member who's really good at spotting and fixing code problems.

FAQs

What is the use of Scalafix?

Scalafix is a tool that helps you fix and improve Scala code automatically. It's like a smart assistant that spots issues and helps clean up your code.

Here's what Scalafix does:

Want to start using Scalafix? Here's how:

1. Get it running: Add it to your build and set up tests
2. Find patterns: Tell it what code to look for
3. Check methods: Look up how functions work
4. Spot problems: Set up warnings for bad code
5. Make it flexible: Add settings to your rules
6. Share it: Use it locally or share with others

Here's how to fit Scalafix into your coding:

Want to make your own rules? Use the scalafix.g8 template. It gives you:

• rules/: Where you write rules
• input/: Code to test on
• output/: What code should look like
• tests/: Check if rules work

To test your rules, just run tests / test.

Related posts

• Scala for Beginners: An Introduction
• Set Up Rust Development Environment: Quick Guide
• Build REST API with Scala Play Framework
• Slick 3 Guide: Best Practices, Tips & Examples