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.

3 min read
Summarize in AI
Flat illustration of a staircase from one version to the next, with the Gradle and Spring Boot 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.

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.