How to create a Scala 3 project with SBT

By Alvin Alexander. Last updated: October 19, 2021

I can never remember how to create a Scala 3 (formerly Dotty) project with sbt, so I created this page.

After I created the initial section on this page, I also added more sections below to show scalacOptions for an sbt/Scala 3 project, as well as a sample .gitignore file for an Scala 3 project.

How to create a new Scala 3 project with sbt

These sbt new commands show how to create new Scala 3 sbt projects:

# create a new Scala 3 (nee Dotty) project
sbt new scala/scala3.g8

# create a Scala 3 (nee Dotty) project that cross compiles with scala 2
sbt new scala/scala3-cross.g8

# optional: launch VS Code
sbt launchIDE

# as a reminder to self, here’s how to start a Scala 3 repl 
# in your sbt project directory (two steps):
sbt

> console
scala> _

Here’s what an example interaction looks like — include SBT renaming my directory name to all lowercase, which brings me no joy:

/Users/al> sbt new scala/scala3.g8
[info] Loading settings for project global-plugins from idea.sbt,plugins.sbt,metals.sbt ...
[info] Loading global plugins from /Users/al/.sbt/1.0/plugins
[info] Updating ProjectRef(uri("file:/Users/al/.sbt/1.0/plugins/"), "global-plugins")...
[info] Done updating.

A template to demonstrate a minimal Dotty application

name [Dotty Project Template]: MyCoolDottyProject

Template applied in /Users/al/mycooldottyproject

/Users/al> mv mycooldottyproject MyCoolDottyProject

For more information: dotty.epfl.ch/docs/usage/getting-started.html

My Scala 3 build.sbt scalacOptions

While I’m in the neighborhood, my Scala 3 sbt build.sbt scalacOptions currently look like this:

scalacOptions ++= Seq(
  "-deprecation",         // emit warning and location for usages of deprecated APIs
  "-explain",             // explain errors in more detail
  "-explain-types",       // explain type errors in more detail
  "-feature",             // emit warning and location for usages of features that should be imported explicitly
  "-indent",              // allow significant indentation.
  "-new-syntax",          // require `then` and `do` in control expressions.
  "-print-lines",         // show source code line numbers.
  "-unchecked",           // enable additional warnings where generated code depends on assumptions
  "-Ykind-projector",     // allow `*` as wildcard to be compatible with kind projector
  "-Xfatal-warnings",     // fail the compilation if there are any warnings
  "-Xmigration"           // warn about constructs whose behavior may have changed since version
)

Many of these come from working with Hermann Hueck, who has been a tremendous reviewer on the 2nd Edition of the Scala Cookbook.

My Scala 3 .gitignore file

Also while I’m in this neighborhood, my Scala 3 .gitignore file looks like this:

bin/
target/
build/
.bloop/
.bsp/
.metals
.cache
.cache-main
.classpath
.history
.project
.scala_dependencies
.settings
.worksheet
.DS_Store
*.class
*.tasty
*.log
*.iml
*.ipr
*.iws
.idea
meta.json

Some of these settings are for IntelliJ, some are for VS Code, and some may be for Eclipse. The list probably needs some cleanup, but it seems to be working for me in January, 2021.

scala

commands