Setting Up Scala with Helix and Metals

1. The Architecture of a Modern Scala Environment

Before we install anything, it's crucial to understand the components you'll be working with. Unlike some environments where a single IDE handles everything, a lightweight setup like the one you prefer involves several specialized tools that communicate with each other. Your experience with CI/CD and container orchestration will make the service-oriented nature of this setup feel familiar.

The key components are:

• Helix: Your chosen editor. A modern, modal, terminal-based editor written in Rust. It has built-in support for the Language Server Protocol (LSP), which is fundamental to our setup.
• Language Server Protocol (LSP): A standard protocol created by Microsoft that allows editors (like Helix) to communicate with language "servers." The server provides language-specific features like code completion, diagnostics, and go-to-definition. This decouples the editor from the language intelligence.
• Metals: The language server for Scala. It's the "brain" of our operation, providing all the Scala-specific smarts to Helix.
• sbt (Scala Build Tool): The most common build tool for Scala projects. It manages dependencies, compiles, tests, and packages your code. Think of it as a combination of pip/poetry and make for Scala, defined in a build.sbt file.
• Bloop: A build server that runs in the background. Metals uses Bloop to provide extremely fast compilation and diagnostic feedback within the editor, without the startup overhead of sbt for every small change.
• Coursier: A dependency fetcher for the JVM ecosystem, written in Scala. We will use its command-line tool, cs, to install and manage our Scala tooling.

The video below provides an excellent conceptual overview of how Metals, LSP, and Bloop work together to create a responsive development experience. While it uses other editors for demonstration, the underlying principles are exactly what we're setting up.

2. Installation and Setup

Now, let's get these tools installed and configured. We'll follow a streamlined process using Homebrew and Coursier. The article "Helix and Scala" by Eugene Yokota provides a great, concise guide for this exact setup.

Here is a summary of the steps to perform in your terminal:

1. Install Java: Metals and the Scala compiler run on the JVM. Ensure you have a Java Development Kit (JDK), version 8 or 11, installed. You likely already do, but you can verify with java -version.
2. Install Helix:

   brew install helix
   

3. Install Coursier:

   brew install coursier/formulas/coursier
   

4. Install Metals CLI:

   cs install metals
   

   This command uses Coursier to install the Metals command-line application.

After installation, verify that the tools are correctly installed and available on your PATH:

hx --health scala



# Expected output should show a ✓ next to 'metals'

metals --version



# Expected output should show the installed Metals version

A Note on PATH: A common pitfall is having conflicting versions of tools on your PATH. For example, Homebrew might install one version of metals, and cs another. The GitHub discussion in the resource LINK highlights how a PATH issue led to problems. Ensure that the cs-installed versions are prioritized in your shell's PATH to avoid such issues.

3. Creating Your First Scala Project

With the tools installed, let's create a standard sbt project. sbt uses a conventional directory structure that will be familiar from other build systems.

1. Create a new directory for your project and navigate into it:

   mkdir scala-beam-kickstart
   cd scala-beam-kickstart
   

2. Create the build.sbt file. This file tells sbt about your project, including its name, version, and dependencies.

   touch build.sbt
   

   Open build.sbt and add the following lines:

   val scala3Version = "3.3.3"
   
   lazy val root = project
     .in(file("."))
     .settings(
       name := "scala-beam-kickstart",
       version := "0.1.0-SNAPSHOT",
       scalaVersion := scala3Version
     )
   

3. Create your first Scala source file:

   mkdir -p src/main/scala
   touch src/main/scala/Main.scala
   

   Open Main.scala and add a simple "Hello, World" object:

   @main def hello(): Unit = 
     println("Hello, Scala environment!")
     println(s"Running on Scala version: ${util.Properties.versionString}")
   

Your project is now set up.

4. The Critical Link: Importing the Build in Helix

This is the most important—and often missed—step for using Metals with Helix. When you open a project, Metals needs to "import the build" to understand its structure, dependencies, and source files. In full-featured IDEs or more mature LSP clients, a prompt appears automatically. In Helix, you currently need to trigger this manually.

This is a known limitation of Helix's LSP support, as explained in the GitHub discussion LINK. Fortunately, the workaround is simple once you know it.

1. Open the project in Helix: From your project's root directory, run hx.
2. Open a Scala file: Use the file picker (<Space>f) to open src/main/scala/Main.scala.
3. Trigger the Build Import: Once the file is open, enter command mode by typing : and then run the following command:

   :lsp-workspace-command build-import
   

   This sends a command to Metals, telling it to analyze your build.sbt file. Metals will then use sbt-bloop to generate the necessary configuration. This process can take a minute or two for the first time, as it may download sbt, Bloop, and other dependencies. Helix will not show progress, so be patient.
4. Verify LSP is Active: Once the import is complete, LSP features should work. Move your cursor over println and press k (in normal mode) to invoke hover information. You should see documentation for the println method. Try gd (go to definition) on Properties. It should take you to the source file (which Metals downloads for you).

If you encounter issues, the troubleshooting thread below is an invaluable resource.

Summary and Next Steps

Congratulations! You have successfully configured a lightweight, powerful Scala development environment tailored to your preferences.

Key Takeaways:

• A modern Scala dev setup consists of communicating components: Helix (editor), Metals (language server), sbt (build tool), and Bloop (build server), all tied together by LSP.
• Installation is managed via brew and the Scala tool manager cs.
• The most critical step in Helix is manually triggering the build import with :lsp-workspace-command build-import after opening a Scala file.

You are now fully equipped to start coding. In the next lesson, "Translate core Python concepts to their idiomatic Scala equivalents," we will leverage this new environment to dive into the Scala language itself, drawing parallels to your existing knowledge of Python and Go to accelerate your learning.