Build.sbt for begginers

I am trying to improve the Scala onboarding by adding an article abour VS Code/Metals in the same vein as Getting Started with Scala in IntelliJ | Scala Documentation

Notably I use the New Scala Project feature of Metals, based on giter8.
This lead me to discover the build.sbt is structured radically differently in scala/hello-world.g8 and in scala/scala3.

hello-world.g8 is flat like so:

scalaVersion := "2.13.12"

name := "hello-world"
organization := "ch.epfl.scala"
version := "1.0"

libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "2.3.0"

(With a lot of very nice explanatory comments in-between.)

scala3.g8 on the other hand is “layered”:

val scala3Version = "3.4.1"

lazy val root = project
    name := "$name$",
    version := "0.1.0-SNAPSHOT",

    scalaVersion := scala3Version,

    libraryDependencies += "org.scalameta" %% "munit" % "0.7.29" % Test

To make it simpler for beginners, we should strive to have those two as similar as possible.
This implies the following question: Which one should we copy to the other one ?
(If we choose scala3.g8, we’ll of course port the comments from the other one)


From the topic title, I was sure this was an April Fool’s.

I think they want to deter the simple or naive style of “bare” settings.

There is a FAQ in this area.

Some people also say to use subprojects.

I agree that it’s easier to have one basic template, even if that is not the simplest possible build supported by sbt 0.13. That facilitates both understanding and cut/paste. It may also avoid refactoring the build for some trivial reason.

(An easy on-ramp is nice, but you turn the corner and hit a huge learning curve, it’s no longer nice.)


There was a long inconclusive discussion about this at Simpler seed · Issue #2 · scala/scala-seed.g8 · GitHub (which also links to several previous discussions)

Eugene (and some others) take the position that people are going to need the multiproject style eventually so we might as well start them there. I (and some others) totally disagree. :person_shrugging:

I wrote:

You can learn a lot of Scala, and get a lot of value out of sbt along the way, before ever wanting or needing to know anything about multi-project builds at all. (I used Scala and sbt myself for years without ever learning that.)

In the context of teaching Scala to newcomers, I think the move to a multi-project build is in the learner’s distant future, so to prepare them for that move so early is simply a pedagogical mistake that 1) distracts the learner from more important issues at their stage of learning, and not incidentally 2) gives them an unnecessarily negative impression of sbt.

Not sure if the advent of scala-cli changes anything here. It does mean that I’m no longer using sbt except for multiproject builds.


The flat one is the better one for beginners, imho. Less is more, the layered one looks scary, and raises to many questions that cannot be answered at first (to val or not to val, why or not with lazy, use = or := etc etc ?? Just to name a few of this DSL nightmare). If they are still around after some time and need the layered version later on, they will switch.

And to be honest, i often still don’t get it after many years of using Scala with SBT. It is just that i have collected enough examples for a decent copy-paste, and most build.sbt files are some mixture of both styles.


Thank you for your feedback, I think the flat one is also better for beginners, as we don’t have to worry about these end of line commas


PR opened:

1 Like

It absolutely does!

I think we should steer people towards Scala-cli regardless. I (admittedly non-beginner) converted all my projects to Scala-cli and found it so much easier to teach it (along with the awesome Scastie). I said goodbye to SBT for now and don’t plan on using it in teaching. (I wish Coursera courses would switch to Scala-cli, but that may not be possible due to grading infrastructure and plugins needed.)

The best thing you can do for beginners is to point them in the direction of Scala-cli and using directives with a project.scala file and the Scaladex :laughing:

It is ridiculously dumb and simple to have a mid-to-large size, somewhat complex, single module project (some of these are not even necessary):

Yeah I know, the point is to learn SBT… but!

  1. you can go quite far without SBT,
  2. if you’ll need SBT then you’ll need to learn very non-beginner-friendly stuff anyway… (I think Eugene is right)
  3. I can see Seth’s point that delaying the learning is a bit of a pedagogical mistake; but at the point when someone needs SBT they’ll be advanced enough to learn it. (Even then, they could probably get very far with Scala-cli.)

Having said all that, I think the “layered” one is better for beginners and non-beginners alike. I struggled a lot with going from the “flat” one to the “layered” one. Having the layered one in front of me, so that I can edit the basic template / structure, was really helpful. We shouldn’t delay showing the layered structure :smiley:


I agree Scala-cli is probably the better choice, but I do not know how it interacts with metals and if you can use New ScalaProject… with it ?

For mac users this is not a no-brainer. Installing Scala-CLI requires “brew” on your system. This has its own issues:

  • If you do not have it, it must be installed which is an extra hurdle
  • Nowadays you should install nothing without a thorough safety assessment: a curl-bash pipe, really??
  • Installer requires bash but default shell is now zsh.
  • If you have “ports” you may not want to install “brew” alongside (bin there, done that, not a good idea, although this experience is somewhat older)

It would be a lot nicer if the Scala CLI installation would be possible on a clean mac.

If no build tool is detected Metals will use Scala CLI as default. We do try to integrate it as much as possible to provide a better out of the box experience for Scala. No build tool is necessary to have all IDE features available.

1 Like

That’s very nice, maybe we should move scala/scala3.g8 over to ScalaCLI then ?
(We = me with help or someone else)

Same for hello-world.g8 ?

I would be even more ambitious:
Also add a scala2.g8, and update hello-world.g8 to Scala 3


Agree that it makes sense to give beginners a simple as possible starting point. But are there other templates for more advanced users that do want to create a fresh “non-trivial” sbt project?

1 Like

Yes there’s a long list of .g8 templates in Metals:
(Maybe too long even)


1 Like

That list is in metals/metals/src/main/scala/scala/meta/internal/builds/NewProjectProvider.scala at main · scalameta/metals · GitHub and might need some updating. Open to suggestions!

The “my first program” thread on the other forum suggests that the beginner tool should be a desktop client for scastie. (Upload and run my file without making me click anything.) Then if I want a “project”, download the project from scastie in whichever form I ask for.

Actually, that sounds like the tool they had several years ago for putting the IDE and build behind a web interface. I would require archaeological research to recall the name, which was not “Abide” but possibly also started with “A for Abandon”.

Potentially you could use or Github Codespaces, since both only require a browser and work pretty much as VS Code would.

On our main page we actually have a link to quickly set up a project using Gitpod, though it might not work 100% since we don’t have that tested.

Edit: Seems to be working well, everything set up within a couple of minutes.

1 Like

IMO the template needs to work well with IntelliJ

1 Like