β-testing for Play Gradle Plugin

[ihostage]

Hi, everyone! 👋

The Play Team is happy to announce the start of beta testing for our new Play Gradle Plugin (referred to as Play Plugin in the text below).

Current version: 3.0.2-773ecf9b-SNAPSHOT (will be regularly updated here and we will also announce any further updates through additional comments below, so we recommend subscribing to this discussion thread to stay up to date)

We highly value your feedback and encourage you to share your thoughts and experiences in the comments section of this discussion. Your input is essential for us to make improvements and enhancements.

We have tested the Play Plugin using all the examples in the play-samples repository (see play-samples#467). We encourage you to review how these projects are set up, you can use them as an example on how to migrate your projects to the new Play Plugin.

Play version compatibility

Although you technically have the capability to use different versions of Play modules and the Play Plugin, we strongly recommend using the same version for both. Using mismatched versions may lead to compatibility issues and correctness is not guaranteed.

Gradle version compatibility

We haven't tested the Play Plugin with various Gradle versions (yet). Therefore, we currently recommend using the latest available version of Gradle. For instance, the examples mentioned above use Gradle 8.5. However, similar to the Twirl Gradle Plugin, we aim to support Gradle versions 7.1 and above in future releases of the Play Plugin.

Current status

All Play Plugin classes are annotated with @Incubating and may undergo changes in the future, depending on user feedback. Please keep this in mind.

How to apply the Play Plugin

During the beta-testing period, the Play Plugin will be published in the OSS Sonatype repository. Therefore, to apply the Play Plugin to your project, you will need to follow these steps:

First, add the snapshot repository to your settings.gradle[.kts] file:

pluginManagement {
  repositories {
    gradlePluginPortal()
    maven {
      url = uri("https://oss.sonatype.org/content/repositories/snapshots")
    }
  }
}

Second, add the Play Plugin into your build.gradle[.kts] file:

plugins {
  id("org.playframework.play") version "<PLUGIN-VERSION>"
}

Features

Application Layout

The Play Plugin seamlessly supports both the Play and default Sbt/Gradle application layouts out of the box. No special settings are necessary. You can read more about these layouts in the Play documentation.

Twirl Integration

Of course, the Play Plugin works in synergy with the Twirl Plugin. It's important to note, however, that the Twirl Plugin must be applied before the Play Plugin in order to make additional settings. Additionally, we want to let you know that the Twirl Plugin is compatible with Gradle versions 7.1 and above.

plugins {
  id("org.playframework.twirl") version "2.0.3" // MUST COME BEFORE THE PLAY PLUGIN!
  id("org.playframework.play") version "<PLUGIN-VERSION>"
}

Dependency configurations

You can add dependencies to your application using standard Gradle Configurations. Additionally, we strongly recommend employing the Play BOM (Bill of Materials) for managing your dependency configurations.

val scalaVersion = "2.13"

dependencies {
  implementation(platform("org.playframework:play-bom_$scalaVersion:<PLUGIN-VERSION>}"))

  implementation("org.playframework:play-pekko-http-server_$scalaVersion")
  implementation("org.playframework:play-guice_$scalaVersion")
  implementation("org.playframework:play-java-forms_$scalaVersion")
  implementation("org.playframework:play-logback_$scalaVersion")

  testImplementation("junit:junit:4.13.1")
  testImplementation("org.playframework:play-test_$scalaVersion")
}

Play Routes

The Play Plugin includes two tasks, compilePlayRoutes and compileTestPlayRoutes, which, as their names suggest, are, designed to compile routes. Both tasks are integrated into the standard Gradle build lifecycle, so you don't have to run them manually. Just be aware that they exist. These tasks also support multi-module projects and the "Aggregating reverse routers" feature.

Below are a few related settings that you might find useful:

play {
  routes {
    generateReverseRouter = ...
    namespaceReverseRouter = ...
    imports.add("...")
    aggregateReverseRoutes.addAll(project(":module-1"), project(":module-2"))
  }
}

Web Assets

Similar to the Play Sbt plugin, all your assets will be packaged in a separate *-assets.jar file.

Static Assets

The processPublicAssets task copies public static assets. This task, too, is integrated into the standard Gradle build lifecycle, so you don't need to run it manually. It's just good to be aware of its existence.

Handling Compiled Assets

To manage compiled assets, you will need to either implement your own tasks or use third-party Gradle plugins, for example, the Gradle Node Plugin. We strongly recommend using third-party build systems like WebPack, Grunt, Gulp, which can be integrated into your Gradle build lifecycle.

The Play Plugin itself implements several things that you need to know about: Firstly, there is a special SourceDirectorySet named assets. It is important that all compiled assets end up in the directory referenced by the destinationDirectory property. Secondly, there is a special processAssets task, which, when executed, will process the assets. It's important that this task needs to depend on tasks implemented by you or on tasks provided by third-party Gradle plugins to function correctly.

To give an example, consider that you want to use CoffeeScript in your project.

First, you will need to add a package.json file to your project:

{
  "devDependencies": {
    "coffeescript": "^2.7.0"
  }
}

Then, add the CoffeeScript compilation task to your build script and ensure that the processAssets task depends on it:

import com.github.gradle.node.npm.task.NpxTask

plugins {
  ...
  id("com.github.node-gradle.node") version "7.0.1"
}

val compileCoffeeScript = tasks.register<NpxTask>("compileCoffeeScript") {
  dependsOn(tasks.npmInstall)
  val destDir = sourceSets.main.get().assets.destinationDirectory
  command = "coffee"
  args.addAll("-c", "-m", "-o", destDir.get().toString(), "app/assets/")
  inputs.files("app/assets/javascripts/")
  outputs.dir(destDir)
}

tasks.processAssets {
    dependsOn(compileCoffeeScript)
}

When the processAssets task is run, CoffeeScript files (*.coffee) located in the app/assets/javascripts/ folder will be compiled into JavaScript .js files.

Running the application

Running in development (DEV) mode

To run your app in development mode, use the playRun task. This task starts automatically in Gradle's continuous mode, tracks changes to the source code and hot-reloads the application as needed. Some settings of this task may be useful for you, for example:

tasks.playRun {
  devSettings.put("foo", "bar")
}

Running in production (PROD) mode

You can run your application in production mode using the standard Gradle run task. To do this, add a Play application secret to the task settings. For example:

tasks.run.configure {
  systemProperties["play.http.secret.key"] = "some-long-key-that-will-be-used-by-your-application"
}

Running in production (PROD) (distribution)

Another way to run your application in production mode is by preparing a distribution using the standard Gradle installDist task. You can then run the application with the Play application secret as follows:

cd build/install/my-application-name
JAVA_OPTS="-Dplay.http.secret.key=some-long-key-that-will-be-used-by-your-application" ./bin/my-application-name

[ihostage]

📣 New release 3.0.2-773ecf9b-SNAPSHOT published.

Changelog:

• Fix using templateImports property of Twirl plugin in Play projects

[ihostage]

📣 New release 3.1.0-078266b8-SNAPSHOT published.

Changelog:

• Add option generateJsReverseRouter to disable Javascript routers (see for details [Feature] Add option to disable Javascript routers #12262)

[iaco86]

Hi all, thanks for centralizing gradle support for play!
I was wondering if it's possible to use the snapshots versions 3.1.0 for the akka-based play framework (2.9.x) despite the following statement:

Although you technically have the capability to use different versions of Play modules and the Play Plugin, we strongly recommend using the same version for both. Using mismatched versions may lead to compatibility issues and correctness is not guaranteed.

We'd love to move out of 2.8.x, but we're stuck until we get proper gradle support.

Would adding 2.9.x support to https://github.com/gradle/playframework be an option until the official gradle plugin becomes more stable?

Thanks!

[mkurz]

@ihostage probably knows more on this, but I would say no you can't use the current gradle plugin (snapshots) with Play 2.9.
Do you actually want to migrate to play 2.9? Do you / did you purchase an akka license?

[ihostage]

Hi, @iaco86!

I was wondering if it's possible to use the snapshots versions 3.1.0 for the akka-based play framework (2.9.x) despite the following statement:

Although you technically have the capability to use different versions of Play modules and the Play Plugin, we strongly recommend using the same version for both. Using mismatched versions may lead to compatibility issues and correctness is not guaranteed.

So, this statement is actual, but I think you can try to use the snapshots version with Play 2.9.x and with a high probability have a good result. Current implementation of Gradle Plugin has a two point that can have a potential problem.

• API of play.core.server.DevServerStart
• API and templates of play.routes.compiler

But currently the both is very stable and still haven't changed dramatically in 3.1.x branch so as why I think it's possible to use a snapshots plugin with Play 2.9.x at your own risk without our compatibility guarantees 😉

PS: If you do that, please will write a result, it's very interesting

Would adding 2.9.x support to https://github.com/gradle/playframework be an option until the official gradle plugin becomes more stable?

Personally, I haven't a time for this and haven't considered this option, sorry 🤷‍♂️

[vincent-raman-centrica]

Hi, this latest version was compiled with a compatibility for Java 17. Is it an intended change for the future because it was not the case for the previous 3.0.2 version ?
Currently I am running gradle under jdk 11 and I get the following error

* What went wrong:
A problem occurred configuring project ':my-project'.
> Could not resolve all files for configuration ':my-project:classpath'.
   > Could not resolve org.playframework:gradle-plugin:3.1.0-078266b8-SNAPSHOT.
     Required by:
         project :my-project > org.playframework.play:org.playframework.play.gradle.plugin:3.1.0-078266b8-SNAPSHOT:20240304.123407-1
      > No matching variant of org.playframework:gradle-plugin:3.1.0-078266b8-SNAPSHOT:20240304.123407-1 was found. The consumer was configured to find a library for use during runtime, compatible with Java 11, packaged as a jar, and its dependencies declared externally, as well as attribute 'org.gradle.plugin.api-version' with value '8.5' but:
          - Variant 'apiElements' capability org.playframework:gradle-plugin:3.1.0-078266b8-SNAPSHOT declares a library, packaged as a jar, and its dependencies declared externally:
              - Incompatible because this component declares a component for use during compile-time, compatible with Java 17 and the consumer needed a component for use during runtime, compatible with Java 11
              - Other compatible attribute:
                  - Doesn't say anything about org.gradle.plugin.api-version (required '8.5')

Thank you for your answer

[mkurz]

Hi, this latest version was compiled with a compatibility for Java 17. Is it an intended change for the future because it was not the case for the previous 3.0.2 version ?

Yes, that is intended. The Play Gradle plugin is not officially released yet and its snapshots are published from the current Play Framework main branch, in which we dropped support for Java 11, requiring Java 17 as minimium Java version. We expect to publish an official Play Gradle plugin release with upcoming Play release (which will be Play 3.1)

[iaco86]

Thanks for the feedback!
So currently I have access to a Akka license, that's why I was asking about compatibility with play 2.9.x.

Nevertheless I tried moving to pekko on the project I'm working on, and that was relatively painless.

The biggest problem I'm seeing is given by the differences in how the new gradle plugin acts wrt to the old one.

For instance, we were previously able to specify Jvm Args using the forkOptions.jvmArgs notation, but I can't find a way to specify jvm args in the new plugin, since they all seem to be initialized to List.of() in PlayRunHandle.java

This, for instance, would be used to allow migrating to 2.9/3.0 - see here. I know we can run the task with the properties appended, just trying to hide that to service users.

I will keep you posted if I find time to test this with Play 2.9.x 👍

Thank you!