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.

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
addSbtPlugin("org.playframework" % "sbt-plugin" % "3.0.6")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
)sbt.version=1.10.7Three 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
| Command | What it does |
|---|---|
sbt run | Starts the dev server on port 9000 with reload on request |
sbt "run 8080" | The same on another port |
sbt test | Runs every test |
sbt "testOnly *OrderSpec" | Runs matching test classes |
sbt compile | Compiles without running |
sbt dist | Builds target/universal/orders-1.0.0.zip |
sbt stage | Prepares an unpacked runnable directory in target/universal/stage/ |
sbt clean | Deletes 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:
sbt:orders> ~testOnly *OrderSpecThat 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:
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:
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
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.


