I really like the Play Framework but they’re not shy about making changes when moving to new major versions. The migration of existing an existing app from v2.2.x to v2.3.x can be a painful process, I’ve done it twice now, and there are many pitfalls on the way. Looking through articles as I go suggests I’m not the only one suffering.
It’s a good idea to read the documentation at https://www.playframework.com/documentation/2.4.x/Migration23
Here’s a summary of the changes you’ll need to move a Java project
Before you begin…
Make sure you commit your current version, and do a `play eclipse` in the old version before you start to migrate if you want IDE support. Once you start the migration, you won’t be able to do this
lazy val root = (project in file(“.”)).enablePlugins(PlayJava).enablePlugins(SbtWeb)
in your build.sbt. You can leave out the SbtWeb plugin if you don’t use Play’s templating language.
If you use external APIs, you’ll also need to add javaWs to your library dependencies. Mine now looks like this:
libraryDependencies ++= Seq(
If your project uses LESS, you now have to explicitly indicate that you want LESS files to be compiled. This line in build.sbt will cause all .less assets to be included in the compilation
includeFilter in (Assets, LessKeys.less) := “*.less”
The javaWs package name has also changed from upper-case to lower-case, which is easy-to-miss in your imports. Do a search and replace on all your .java files, changing
Note the trailing . at the end of the line!
Coffeescript and LESS are now no-longer included by default. If you use them, they need to be included in your plugins.sbt file. Annoyingly, you won’t get an error if you fail to include the LESS component, your site will just look bad.
Add these lines to your plugins.sbt
addSbtPlugin(“com.typesafe.sbt” % “sbt-coffeescript” % “1.0.0”)
addSbtPlugin(“com.typesafe.sbt” % “sbt-less” % “1.0.1”)
Note the blank line between the two plug-ins. That’s not an accident, it’s required.
While you’re here, you should also roll up your Play sbt plugin version
addSbtPlugin(“com.typesafe.play” % “sbt-plugin” % “2.3.3”)
Finally, upgrade your Play version to get the changes. Set
in your build.properties
Check it out
That’s it. Run
activator clean update start
to compile and run your new version!