Skip to content
javahacks.dev
Play Framework

sbt Play Project Settings Plugins and Commands Explained

Understand how sbt builds a Play Framework project: build.sbt, the Play plugin, key commands, dependencies, run and test tasks and multi project layouts.

5 min read
Summarize in AI
Flat illustration of a dependency tree and build phases, with the Docker, Apache Maven and Jenkins logos.

Play does not ship its own build tool. A Play application is an sbt project with the Play plugin switched on, so learning how sbt behaves is most of learning how a Play project is built, run and packaged. This covers Play 3 on JDK 17 or newer. If you have not created an application yet, start with the Play tutorial and come back here when build.sbt stops making sense.

The files that define the build

project/plugins.sbtscala
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.6")
build.sbtscala
name := "orders"
organization := "dev.javahacks"
version := "1.0.0"

lazy val root = (project in file("."))
  .enablePlugins(PlayJava)

scalaVersion := "2.13.15"

libraryDependencies ++= Seq(
  guice,
  jdbc,
  "org.postgresql" % "postgresql" % "42.7.4",
  "org.assertj" % "assertj-core" % "3.26.3" % Test
)
project/build.propertiesText
sbt.version=1.10.7

Three files, three jobs. project/build.properties pins the sbt launcher version. project/plugins.sbt loads plugins, and the Play plugin version is the Play version: you do not declare Play as a library anywhere, upgrading the plugin line upgrades the framework. build.sbt describes the project itself.

Reading the dependency list: guice and jdbc are Play's own modules, defined by the plugin as shortcuts. In "org.postgresql" % "postgresql" % "42.7.4" the single % separates group, artifact and version, which is the form every Java library uses. A double %% appends the Scala binary version to the artifact name, for example _2.13, and is needed for libraries compiled for Scala but wrong for plain Java libraries. Using %% on a Java library produces a "not found" error for an artifact name that does not exist, which is the most common first mistake. The trailing % Test limits a dependency to the test classpath.

PlayJava selects the Java flavour of the templates, routing helpers and JSON API. A Scala application uses PlayScala instead. The Scala version in the build is Play's implementation language, and a Java-only project does not need to touch it beyond keeping it on a version the plugin supports.

The commands you will actually run

CommandWhat it does
sbt runStarts the dev server on port 9000 with reload on request
sbt "run 8080"The same on another port
sbt testRuns every test
sbt "testOnly *OrderSpec"Runs matching test classes
sbt compileCompiles without running
sbt distBuilds target/universal/orders-1.0.0.zip
sbt stagePrepares an unpacked runnable directory in target/universal/stage/
sbt cleanDeletes target/, the first thing to try when the build behaves strangely

Each invocation of sbt as a command starts a JVM, loads the build and compiles, which costs several seconds before any of your work begins. Run sbt alone to open the interactive shell instead, with history and tab completion, and type commands there. The cost is paid once.

Prefixing a command with ~ makes sbt rerun it whenever a source file changes:

Text
sbt:orders> ~testOnly *OrderSpec

That is a tight test loop with no editor integration needed. Press Enter to leave watch mode.

What dev mode does

In sbt run, Play does not recompile continuously. The first request after a change triggers a compile, and the response waits for it. A compile error shows up as an error page in the browser with the failing line, so the cycle is edit, refresh, read. If you see an error that does not match your code, the usual explanation is stale compiled output, covered with fixes in Play compile errors. Stopping the server with Ctrl+D rather than Ctrl+C lets sbt shut the application down cleanly and keeps the shell open.

Build time versus run time settings

Facts the build needs, such as dependencies, JVM flags and plugin settings, belong in build.sbt. Facts the running application needs, such as database URLs and secrets, belong in conf/application.conf, overridden from the environment:

conf/application.confText
db.default.driver = org.postgresql.Driver
db.default.url = "jdbc:postgresql://localhost/orders"
db.default.url = ${?DATABASE_URL}

The ${?DATABASE_URL} form overrides the line above only when the variable is set. Without the question mark, an unset variable is a startup error. Play also reads -Dkey=value system properties, which sit above the file and are convenient for one-off changes.

Packaging for a server or a container

sbt dist produces a zip with the jars and start scripts. sbt stage produces the same layout as a plain directory, which is what a container image wants because it avoids unzipping:

Dockerfile
FROM eclipse-temurin:21-jre
COPY target/universal/stage /app
ENTRYPOINT ["/app/bin/orders"]

Run sbt stage in CI and copy the directory in. The application secret must be supplied at run time, never baked into the image, and the full walk-through is in deploying a Play application.

More than one project

build.sbtscala
lazy val domain = (project in file("domain"))

lazy val web = (project in file("web"))
  .enablePlugins(PlayJava)
  .dependsOn(domain)

lazy val root = (project in file("."))
  .aggregate(domain, web)

Only web is a Play application. domain is a plain sbt project holding code with no web dependency, which compiles and tests faster on its own. dependsOn puts one project on another's classpath, and aggregate makes sbt test at the root run both. Run a single module with sbt web/run or sbt domain/test. Testing such a layout follows testing Play applications.

Reading a failing sbt build

Failures in sbt come in three kinds. A resolution failure names a dependency it could not download, and it usually means a typo in the coordinates, a missing resolver for a private repository, or a %% used on a Java library. A compilation failure shows the file and line, as in any compiler, and in dev mode Play renders it in the browser. A configuration failure, reported while loading the build, names a setting or a plugin and appears before any compilation starts, often after an upgrade of the plugin without the matching change in build.sbt.

When the output is unclear, ask sbt for more with sbt -debug, or run show libraryDependencies in the shell to print the effective list, and dependencyTree to see where a version came from, the same investigation as in Maven dependency conflicts. If a build behaves strangely after a branch switch, exit the shell, delete target and project/target, and start again. Those directories hold compiled build definitions and are safe to remove.

When sbt is not the answer

Play can be built with Gradle or Maven through community plugins, and some Java teams prefer that to learning sbt syntax. Those are not the supported path, and framework upgrade notes assume sbt, so expect to translate. If the team is Java-only and already standardised on Maven, weigh that translation cost honestly before choosing Play. The reference for both tools is the Play documentation and the sbt documentation.

Also inDevOps
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.