Skip to content
javahacks.dev
Play Framework

Play 2.8 to 3 Migration Steps for Your Existing Project

Migrate a Play 2.8 application to Play 3: go through 2.9 first, update sbt and Java, swap Akka for Pekko, fix removed APIs and verify before deploying.

6 min read
Summarize in AI
Flat illustration of a controller, a service and a repository stacked above a database, with the OpenJDK, Spring Boot and Swagger logos.

Play 2.8 is two major steps behind. The path is mechanical, and the order keeps each failure explainable. The reasons for the rename are in Play 3 and Pekko.

Step 1: Play 2.8 to 2.9

project/plugins.sbtscala
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.9.6")

Also bump sbt.version in project/build.properties to a version the plugin supports, and use Scala 2.13 (Play 2.9 also supports Scala 3). Read the 2.9 migration guide and handle each deprecated item. Typical things:

  • Java: some play.mvc helpers and HttpExecutionContext usage changed.
  • Guice and dependency injection modules may need updated versions.
  • JSON and WS libraries received minor API tidying.

Compile with warnings enabled and fix them while still on Akka, since this keeps the later step small. Run the test suite and deploy this version before continuing if your process allows.

Step 2: Play 2.9 to 3.0

Change the plugin group and version, because the artifacts moved to the org.playframework group:

project/plugins.sbtscala
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.6")

The other build changes:

  • The Play plugin name changes from com.typesafe.play to org.playframework, and also for modules in libraryDependencies such as "org.playframework" %% "play-json".
  • Java 11 is the minimum for the sbt plugin, and Java 17 or 21 is the practical choice.
  • The sbt-native-packager and other plugins need compatible versions.

Step 3: Akka to Pekko

Run a global search for akka and change:

  1. Java and Scala imports to org.apache.pekko.
  2. application.conf keys under akka { ... } to pekko { ... }.
  3. Dependencies from com.typesafe.akka to org.apache.pekko.
  4. Log filters or metrics that match akka logger names.
java
// before
import akka.actor.ActorSystem;
// after
import org.apache.pekko.actor.ActorSystem;

A sed-style search and replace over src/ handles most of it, but review the diff, because some strings, like a documentation URL or a type name containing "akka", should stay.

Step 4: check the dependency tree

Shell
sbt dependencyTree | grep -i akka

Any hit shows a library still bringing Akka. Replace it with the Pekko version or find an alternative, so only one actor library is on the classpath.

Step 5: verify behaviour

  • Start the app and run the full test suite.
  • Check configuration overrides in each environment, because a missed akka. key silently falls back to a default.
  • Exercise WebSockets, streaming responses, scheduled tasks and anything using actors.
  • Compare startup logs between versions for new warnings.
  • Deploy to staging and run a load check, with the practices in deploying Play.

Rollback

Keep the 2.9 branch tagged. If a third party library blocks the move, staying on 2.9 for a while is acceptable. Do not mix partial renames, because a half-migrated project has two actor systems.

Find every Akka reference before you start

The size of the migration is the number of places that mention Akka, and a few commands find them all. Run them at the start, keep the output, and run them again at the end; the second run should print nothing.

Shell
grep -rn --include='*.scala' --include='*.java' 'akka\.' app test | wc -l
grep -rn --include='*.conf' --include='*.xml' -E '(^|[^a-z])akka([^a-z]|$)' conf | head -20
grep -n 'akka' build.sbt project/*.sbt project/*.properties
sbt "show dependencyTree" 2>/dev/null | grep -i akka

The first counts source files that import Akka; the second lists configuration keys such as akka.actor.default-dispatcher and logger names; the third finds build coordinates; the fourth lists libraries that pull Akka in transitively. The fourth is the one that decides the schedule, as the Pekko post explains: a library with only an Akka release blocks the move until it publishes a Pekko one or you replace it.

Move through 2.9 before 3.0

The recommended path goes through Play 2.9, which is the last release on Akka and the first with the JDK and Scala level that Play 3 needs. Doing the version change in two steps separates problems: anything that breaks in 2.9 is a Play or Scala change, and anything that breaks in 3.0 is Pekko or the package rename.

project/plugins.sbtscala
// step 1: 2.8 to 2.9 (still Akka)
addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.9.x")

// step 2: 2.9 to 3.0 (Pekko). Note the group id changed.
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.x")

Replace x with the current patch release from the Play release notes. The group id changed from com.typesafe.play to org.playframework with 3.0, which is an easy line to miss when the build fails to resolve the plugin. Run the full test suite at each step and tag a commit, so that a problem can be bisected between them.

Rename imports mechanically, then read what remains

The import rename is a pattern replacement, and a script is safer than an editor because it covers every file in one pass and can be repeated.

Shell
git grep -l 'akka\.' -- '*.scala' '*.java' | xargs perl -pi -e 's/\bakka\.(actor|stream|pattern|util|dispatch|event|japi|routing|testkit)\b/org.apache.pekko.$1/g'
git grep -n 'akka' -- '*.scala' '*.java'

The second command prints whatever the pattern did not catch: string literals with class names, akka in logger configuration, and package names outside the list. Each remaining hit needs a decision. Configuration is the second half. In application.conf, the root key akka { ... } becomes pekko { ... }, and the nested keys keep their names, so a block of dispatcher settings moves as a whole.

Text
# before
akka.actor.default-dispatcher.fork-join-executor.parallelism-max = 16
# after
pekko.actor.default-dispatcher.fork-join-executor.parallelism-max = 16

A configuration key left under akka is ignored silently, and the actor system runs on defaults, which is a performance regression with no error. After the rename, print the effective configuration at startup in a test and check the values you set are present.

scala
val config = app.configuration.underlying
assert(config.getInt("pekko.actor.default-dispatcher.fork-join-executor.parallelism-max") == 16)

Verify behaviour that the compiler cannot see

Three things pass compilation and fail in production. Message serialization for actors that cross nodes or persist events changes its class names, so events written by 2.8 must still be readable; replay a copy of production data on a test environment. Metrics and log filters named after akka stop matching. And libraries that detect Akka on the classpath by class name, such as some monitoring agents, may need a new version. Roll out to a single instance first, compare error rates for a day, and keep the previous release deployable. The rollback is a redeploy of the old version, which works only while the data formats are compatible, so decide before the migration whether you need a window in which both versions run.

Plan the cut-over

Treat the move as two releases. The first release is Play 2.9 with no functional changes, so the team gets used to the new build and the production metrics stay comparable. The second release is Play 3.0 with the Pekko rename. Between them, run the application on 2.9 for at least a full business cycle, such as a month-end for a billing system, to find any problem that depends on the calendar. Before the second release, take a baseline of response time, memory use and error rate on 2.9, and compare it with the same numbers after the move on one instance. A regression in either release has a small search space because only one thing changed.

Communicate the change to the people who operate the application. Dashboards, alerts and log queries that mention akka need updating on the same day, or the first incident after the release will be harder to diagnose than it should be.

Where this does not apply

If you are coming from a version older than 2.8, go through each major step first. Template and routes syntax did not change in this move, see Twirl templates. The reference is the Play 3.0 migration guide, and the Play 2.9 migration guide covers the earlier step.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.