Last updated November 29, 2023

When deploying with Git, it’s common for very large Play applications to exceed the slug size limits of the platform. If this happens, you’ll see an error like this when you deploy:

remote:  !   Compiled slug size 583.3MB is too large, max is 500 MB.

There are a number of ways to mitigate this problem, including switching to non-Git deployment. In this article, you’ll learn how to do this and how to configure your application to reduce it’s slug size.

Using sbt-native-packager

The sbt-native-packager plugin allows the buildpack to prune the sbt cache before compiling the slug. It is a replacement for the deprecated sbt-start-script plugin, and is already used in the most recent versions of the Play framework. To use sbt-native-packager with Play, you’ll need to upgrade to version 2.2 or 2.3 or Play and the plugin will be included for you. Then change your Procfile to contain something like this:

web: target/universal/stage/bin/my-app -Dhttp.port=${PORT}

You may also need to include -DapplyEvolutions.default=true in the command, depending on your application.

For standalone applications, add the following to your project/plugins.sbt:

addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "0.8.0-RC2")

And add this to your build.sbt:

import NativePackagerKeys._

Now when you run sbt stage, the plugin will package everything that’s needed to run your application in the target/universal/stage directory. This allows the buildpack to remove any other temporary assets from the slug.

Renaming the web target

Play packages web assets in to the target/web directory. The buildpack does not remove these by default, but you can configure your application such that buildpack knows it’s ok to remove them. To do so, add the following to your build.sbt:

WebKeys.webTarget := target.value / "scala-web"

artifactPath in PlayKeys.playPackageAssets := WebKeys.webTarget.value / (artifactPath in PlayKeys.playPackageAssets).value.getName

This renames the web target directory to scala-web and moves the assets artifact into that directory. In this way, the buildpack can safely remove the assets from the slug.

Adding a .slugignore file

If your Git repository includes binaries or other large files that are not needed at runtime, you can exclude them from the slug by creating a .slugignore file in the root of your Git repo.

It is very common for the Git repository to include large files that are only needed when running tests. In this case, the .slugignore file might look like this:

*.psd
*.pdf
/test

You can inspect the extracted contents of your slug by running heroku run bash and using commands such as ls and du. This may help you identify large files that need to be added to the .slugignore file. Exactly what should be excluded depends on the needs of each application.

Using sbt to clean build artifacts

This method is useful when your build creates large artifacts that are not required at runtime, or if your project contains large files that are needed at compile time but not at runtime.

Add the following code to your build.sbt file:

val stage = taskKey[Unit]("Stage and clean task")

stage := {
  (stage in Universal).value
  if (sys.env.getOrElse("POST_STAGE_CLEAN", "false").equals("true")) {
    println("cleaning...")
    sbt.IO.delete(baseDirectory.value / "my-subdir")
  }
}

This will override the default stage task provided by the sbt-native-packager plugin, and add some new behavior. The first line in the body of the custom stage task invokes the original stage task from sbt-native-packager (stage in Universal). Then it checks for a POST_STAGE_CLEAN config var, which prevents sbt from deleting your project locally. If that config var is set to true, then the rest of the task can delete project files.

Once the code above has been added to your Git repo, you will need to set the following config var:

$ heroku config:set POST_STAGE_CLEAN="true"

When you push to Heroku, it will ran the staging task and clean your project accordingly.

If you implement these suggestions, and still have a slug that is too large, please contact Heroku support.