I've been there. You've spent a weekend writing a sleek little utility library, you've tested it on your machine (which is running Scala 2.13), and you push it to your team. Then, ten minutes later, you get a Slack message: "Why is this throwing a NoSuchMethodError on my 2.12 project?"

The problem is that Scala is not binary compatible across major versions. A JAR compiled for 2.13 simply won't work for someone on 2.12, and certainly not for someone on Scala 3. If you're writing a library meant for others to use, you can't just pick one version and hope for the best.

The "Single Version" Trap

Here is a typical build.sbt for a library that's about to cause a lot of friction:

name := "scala-utils"
organization := "com.example"
scalaVersion := "2.13.12"

libraryDependencies += "org.typelevel" %% "cats-core" % "2.9.0"

At first glance, this looks fine. But notice that scalaVersion is hardcoded. When you run sbt publish, sbt produces a single artifact: scala-utils_2.13-1.0.jar. When your teammate tries to add this to their 2.12 project, the build will either fail to find the dependency or, if they force it, the JVM will crash at runtime because the bytecode doesn't match the expected runtime version.

You might think, "I'll just manually change the version string and publish again," but that's a recipe for disaster. You'll forget a version, or worse, you'll realize your code uses a feature from 2.13 (like LazyList) that doesn't even exist in 2.12, and your manual process will miss the compilation error until it's too late.

Automating the Matrix with crossScalaVersions

The professional way to handle this is to tell sbt that your project is intended to be "cross-built." We do this by defining a list of supported versions and using the + prefix for our commands.

Update your build.sbt like this:

name := "scala-utils"
organization := "com.example"

// This is your primary development version
scalaVersion := "2.13.12"

// These are the versions you want to support
crossScalaVersions := Seq("2.12.18", "2.13.12", "3.3.1")

libraryDependencies += "org.typelevel" %% "cats-core" % "2.9.0"

Notice that %% in the dependency? That's the "magic" operator. It tells sbt to append the current Scala binary version to the artifact name. If sbt is building for 2.12, it looks for cats-core_2.12; if it's 3.3, it looks for cats-core_3.

Now, instead of running sbt publish, you run:

sbt +publish

That little + is a signal to sbt: "Run this command for every version listed in crossScalaVersions." sbt will now compile, test, and publish three separate JARs, ensuring that every single one is binary compatible with its target version.

Handling Version-Specific Code

Now, here is the real challenge. What if you want to use LazyList (introduced in 2.13) but you still have to support 2.12, where only Stream exists? You can't put both in the same file without the 2.12 compiler screaming at you.

sbt has a built-in convention for this. You can create version-specific source folders. Your directory structure should look like this:

• src/main/scala/ (Code that works on ALL versions)
• src/main/scala-2.12/ (Code only for 2.12)
• src/main/scala-2.13/ (Code only for 2.13)
• src/main/scala-3/ (Code only for Scala 3)

I usually define a common trait in the main scala/ folder and then provide version-specific implementations in the versioned folders. For example, you might define a CollectionUtils trait in src/main/scala, and then implement the specific "lazy sequence" logic in src/main/scala-2.12 using Stream and in src/main/scala-2.13 using LazyList. When sbt cross-builds, it only includes the folder that matches the current target version.

It's a bit more boilerplate, but it's the only way to maintain a high-quality library that doesn't break your users' builds.

📋 Practical Task

Exercise: Build a Cross-Version Compatibility Bridge

You are tasked with creating a small library called compat-bridge that must support both Scala 2.13 and Scala 3. The library needs to provide a method that returns a "version identity" string.

Requirements:

1. Configure build.sbt to support crossScalaVersions for 2.13.12 and 3.3.1.
2. Create a trait VersionInfo in src/main/scala/VersionInfo.scala with a method def versionString: String.
3. Create an object VersionImpl in src/main/scala-2.13/VersionImpl.scala that extends VersionInfo and returns "Built for Scala 2.13".
4. Create an object VersionImpl in src/main/scala-3/VersionImpl.scala that extends VersionInfo and returns "Built for Scala 3".
5. Run sbt +compile and verify that sbt compiles the project successfully for both versions.

Success Criteria: Your project should compile without errors when running the +compile command, proving that sbt is correctly swapping the source folders based on the target Scala version.