Documentation

§Scala 3 Migration Guide

This guide is for migrating a Play application from Scala 2 to Scala 3 and requires that your application is already running on at least Play 2.9 (built on Akka / Akka HTTP) or Play 3.0 (built on Pekko / Pekko HTTP).

Depending on your codebase, migrating existing Play applications to Scala 3 can be a substantial task. We strongly recommend that you initially migrate to Play 2.9 or 3.0 while staying on Scala 2.13. This approach ensures that everything functions as intended. Afterward, you can make the transition to Scala 3.

§General

In addition to the migration steps mentioned on this page, which cover the migration steps needed to move a Play Framework application to Scala 3, there are general Scala 3 resources that you want to follow to migrate your code base to Scala 3:

§Setting scalaVersion in your project

Both Scala and Java users must configure sbt to use Scala 3. Even if you have no Scala code in your project, Play itself uses Scala and must be configured to use the right Scala libraries.

To set the Scala version in sbt, simply set the scalaVersion key, for example:

scalaVersion := "3.3.3"

It’s important to emphasize that Play exclusively supports Scala LTS (Long-Term Support) versions. As a result, any Scala release between Scala 3.3 LTS and the subsequent LTS version will not be officially supported by Play. However, it might still be feasible to use Play with such Scala versions. You may be interested in “The Scala 3 compatibility story” and the Scala 3.3 release blog post.

§Using Scala 3 with Akka HTTP 10.5 or newer

This section only applies to Play 2.x, but not Play 3.x.

As mentioned in the Play 2.9 Highlights, Play 2.9 keeps shipping Akka 2.6 and Akka HTTP 10.2, despite newer versions being available.

Akka HTTP 10.2, however, does not provide Scala 3 artifacts; only Akka HTTP 10.5 introduced them. If you wish to make use of these native Scala 3 artifacts with Akka HTTP and therefore want to upgrade to Akka HTTP 10.5 or newer, you can do that with the assistance of our Play Scala or Play Java update guides, which also provide notes on which settings to adjust to use Akka HTTP 10.5 or newer with Scala 3. We also strongly encourage you to review:

§running() wrapper required for certain tests

§Using specs2

specs2’s Around trait makes use of Scala’s DelayedInit, which has been dropped in Scala 3 (actually not removed, it just isn’t doing anything anymore). Unfortunately, there is no replacement for DelayedInit in Scala 3. Therefore, when writing tests with specs2 that make use of:

we had to come up with a solution to not make users completely refactor their tests. The solution we came up with is to wrap tests within a running() method, as we think this is the simplest way to migrate those tests without making migration too costly. As an example, for WithApplication, code like:

"testing some logic" in new WithApplication {
  // <test code>
}

now needs to be written like:

"testing some logic" in new WithApplication {
  override def running() = {
    // <test code>
  }
}

An advantage of using a wrapper method is that we made it work in Scala 2 as well, so Scala 2 tests will even run if you wrap them in running(), so such test code can be easily switched forth/back from/to Scala 2/3, and tests will work in both cases (which may help during migration).

§Using ScalaTest Plus Play

When writing tests with ScalaTest and making use of App, Server, Chrome, Firefox, HtmlUnit, InternetExplorer, or Safari, you need to wrap the test code within a running() method to make them work with Scala 3. That is because under the hood, ScalaTest also makes use of DelayedInit, just like described in the previous section. As an example, when using App, code like:

"testing some logic" in new App(...) {
 // <test code>
}

needs to be converted to:

"testing some logic" in new App(...) {
  override def running() = {
    // <test code>
  }
}

§String Interpolating Routing DSL (sird) imports

We had to split some methods out of the implicit class play.api.routing.sird.UrlContext, using extension methods instead.
For you, that means if you imported the UrlContext class directly:

import play.api.routing.sird.UrlContext

you now have to instead import everything from the sird package to make sure the extension methods are imported as well:

import play.api.routing.sird._

§Dependency graph changes

If you start to use Scala 3 in your Play application, the Play specs2 dependency will no longer pull in the "org.specs2" %% "specs2-mock" dependency because it is not available for Scala 3 anymore. The Play specs2 Scala 3 artifacts depend on "org.mockito" % "mockito-core" instead to use Mockito directly, which we think is the best alternative to switch your existing test code to at the time of this writing.
You need to adjust your code, e.g., here is a snippet of how to use Mockito:

import org.mockito.Mockito._
import org.mockito.ArgumentMatchers._

val userRepository = mock(classOf[UserRepository])
when(userRepository.roles(any[User])).thenReturn(Set(Role("ADMIN")))

Next: Module directory

Found an error in this documentation? The source code for this page can be found here. After reading the documentation guidelines, please feel free to contribute a pull request. Have questions or advice to share? Go to our community forums to start a conversation with the community.