IDEs

The summary above restates the Scala documentation’s own description of the two tools.

Source: Scala documentation: Scala IDEs

Installation. Install the Metals extension from the Visual Studio Marketplace (or from the extensions view in VS Code), then open a directory that contains Scala code. The extension activates when the directory has a build.sbt or build.sc, when a Scala file (a .scala, .sbt or .sc file) is opened, or when a standard src/main/scala layout is detected. Metals needs a JDK to run its server (the minimum is 11, and the extension’s own setting defaults to 17; if none is found it downloads one with Coursier) and uses the JDK in JAVA_HOME to build the project. The project’s JDK must be at least as new as the server’s. For Scala 3.10 the project JDK must be 17 or later.

Importing the build. The first time you open a workspace Metals prompts "Import build". For sbt, Mill, Maven and Gradle it runs the build tool once to export the project to Bloop, a Scala build server with fast incremental compilation, and then compiles the open files. You do not need Bloop installed for this. If you click "Don’t show again" remove the .metals/ directory to bring the prompt back. When you change build.sbt or files under project/ Metals asks to re-import; you can trigger it any time from the command palette with "Metals: Import build". The import can take from seconds (a small cached build) to ten minutes or more (a large build that downloads dependencies for the first time); tail -f .metals/metals.log shows the progress.

Run Doctor. The command "Metals: Run Doctor" helps troubleshoot configuration problems in the workspace, and it is also how you check the build target names that a debug configuration needs (for an sbt project they are the project ids, with -test appended for test sources).

Files to keep out of git. Metals writes .metals/ (logs and indexes), .bloop/ (Bloop’s compilation data), .scala-build/ (when Scala CLI scripts are used) and project/metals.sbt (the file that adds the Bloop plugin to an sbt build). Add them to .gitignore:

Settings you will touch. Settings such as "Java Home", "Sbt Script" (point to your own sbt script when you need environment variables, since the default embedded launcher respects .sbtopts and .jvmopts but not SBT_OPTS), "Custom Repositories" for a private artifact server and the server properties for an HTTP proxy are described in the Metals documentation under VS Code and User Configuration. Proxy settings go into a .jvmopts file, as -Dhttps.proxyHost and -Dhttps.proxyPort.

Running and debugging. Metals runs and debugs main methods and tests with the Debug Adapter Protocol (DAP), and Bloop starts the process. There are four ways to start a session:

The configuration is the documented shape with the class names of the trailhead example (the hike and TrailSuite classes of the sbt page). It was not run here, because it needs VS Code. To pass environment variables or JVM options to tests, use a .jvmopts file (-X options are filtered out of it) or a .test-jvmopts file for test-only options.

Worksheets. A worksheet is a Scala file named with the suffix .worksheet.sc that Metals evaluates when you save, showing each result as an inlay hint at the end of its line (hover to see a long value in full). Everything may be at the top level, with no wrapping object. Put the file next to your sources if it should see the project’s classes; elsewhere it sees only the standard library and its own dependencies. Dependencies come from Scala CLI directives, for example //> using dep com.lihaoyi::scalatags:0.7.0, and compiler options from //> using options. Worksheets are evaluated with mdoc, which has limitations (for example, a class that extends AnyVal cannot be defined in a worksheet). A file like this:

is evaluated by Metals on save, with the value of each expression shown as an inlay hint. If you run the same file with scala run Trail.worksheet.sc instead, it executes without printing anything, since a script prints only what it asks to, and it reports a harmless warning about the file name, because the dot in Trail.worksheet.sc becomes part of a generated object name:

This is the real output of the run. The worksheet inlay hints themselves were not run here.

Creating a project. The command "Metals: New Scala project" is the equivalent of sbt new: it lists Giter8 templates (and lets you type any organization/repo of GitHub), asks for a folder and a name, and creates the project.

Source: Metals: Visual Studio Code, Metals: User Configuration

Metals is an LSP server, so it works with any LSP client. The Scala documentation names Emacs, Vim, Sublime Text and Helix next to VS Code. The Metals feature table marks most features as supported in all of them, with a few gaps per editor, and the installation is a single click everywhere except Helix, where it is manual. Each editor has its own page: Vim, Sublime Text, Emacs and Helix, and there is also a page for online IDEs. What they share:

Source: Metals: Text Editors overview (editor support table), Metals: Build tools

Both Metals and IntelliJ talk to builds through the Build Server Protocol (BSP), the build-tool counterpart of the Language Server Protocol: the build tool runs as a server that answers "what are the modules, sources and classpaths?" and "compile this target", so an editor needs one integration for every build tool that speaks BSP, instead of one per tool. Metals imports sbt through Bloop, which is a BSP server; any tool that implements BSP can be integrated, as Metals' documentation for new build tools describes.

Scala CLI is a BSP server too. It does not rely on the editor to find it. Instead it writes a connection details file that the BSP specification calls build server discovery. Run scala setup-ide . (or just run compile, run or test; they do it first) and look at the directory:

(The argv array holds the command line that the IDE starts, with the machine-specific paths replaced by placeholders.) Scala CLI 1.17.1 wrote .bsp/scala.json; its documentation still says .bsp/scala-cli.json, and IDEs read the connection file they find in the .bsp directory. The file .scala-build/ide-options-v2.json next to it stores the options (Scala version, extra arguments) that the BSP server uses; the other ide-*.json files in .scala-build keep inputs and environment variables. By default Scala CLI saves the options of the last compile, run or test, so that the IDE builds what you last built; after you run setup-ide yourself, that automatic update stops until you delete .bsp and run compile again.

For a Scala CLI project, open the directory in the IDE, not a single file; an IDE shows every file below the folder, but the build includes only the files Scala CLI was given. To add a file, add it to the Scala CLI command (scala setup-ide dir/A.scala dir/B.scala) or use //> using file, or better make the directory the project.

Source: Scala CLI: IDE support, Scala CLI: setup-ide, Build Server Protocol, Metals: Integrating a new build tool

Installation. Install IntelliJ IDEA (the Scala site recommends the Community edition unless you already use Ultimate; IntelliJ’s own documentation for the Scala plugin is part of IDEA’s help), then add the Scala plugin: open Settings (Ctrl+Alt+S), choose Plugins, open the Marketplace tab, find "Scala" and click Install. The plugin has a stable channel and, optionally, an Early Access Program and a Nightly Builds channel in Settings under Languages & Frameworks and Scala, on the Updates tab.

Creating a project. File, New, Project, choose Scala on the left. You pick a build system and a JDK:

For a Scala 3 project the wizard offers "Use significant indentation syntax (Optional Braces)", which you can change later in Settings, Editor, Code Style, Scala. You can also open an existing project with File, Open (point to the directory containing build.sbt), import from existing sources, or check a project out from version control. IntelliJ’s documentation covers sbt support on its own page. A project that Scala CLI manages can be opened too; the Scala CLI cookbook has recipes for a simple project, for a Scala CLI project beside an sbt one, and for several Scala CLI projects as separate modules.

Running and worksheets. The Scala tutorial creates @main def hello(): Unit = println("Hello, World!"), and you run it with "Run 'hello'" from the context menu of the method. A Scala worksheet (right-click src, New, Scala Worksheet) evaluates as you type and shows results in a pane on the right:

The pane shows res0: Int = 4. (Quoted from the tutorial; not run here.) In both IDEs the worksheet is a convenience for exploring an API, not a build artifact: do not depend on its output in CI.

Debugging. Scala compiles to JVM bytecode, so the JVM debugger of the IDE applies. The steps (breakpoints, the Debug action beside Run, stepping) and the Scala-specific evaluator settings are in the JetBrains documentation; this was not run here.

Metals or IntelliJ? Both work with sbt and Scala CLI projects. A pragmatic split that follows the Scala documentation: IntelliJ when you want an integrated IDE with sane defaults; Metals when you want the compiler’s own feedback or a lighter editor. You can install both and switch per project, since they use different state directories (.idea/ for IntelliJ, .metals/ and .bloop/ for Metals).

Source: Scala documentation: IntelliJ IDEA + Scala plugin, Scala documentation: Getting started with Scala in IntelliJ, IntelliJ IDEA Help: Get started with Scala