Skip to main content

Your First Bleep Project (Scala)

This tutorial walks you through scaffolding a small Scala 3 project with bleep, running it, running its tests with MUnit, and importing the project into IntelliJ IDEA or VS Code with Metals.

Other languages: Java → · Kotlin →

Prerequisites​

  • Bleep installed
  • A terminal
  • IntelliJ IDEA with the Scala plugin, or VS Code with Metals

Step 1: Create the project​

mkdir my-first-bleep-project
cd my-first-bleep-project
bleep new myapp

bleep new defaults to Scala 3 on the JVM. It writes a complete, ready-to-run workspace: a bleep.yaml, a myapp project with a hello-world Main.scala, and a myapp-test project wired up with MUnit.

The Scala compiler and standard library are downloaded by Coursier on first compile.

Step 2: What got generated​

The build file:

$schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
$version: 1.0.0-M9
jvm:
  name: graalvm-community:25.0.1
projects:
  myapp:
    extends: template-common
    platform:
      mainClass: com.example.helloMain
  myapp-test:
    dependencies: org.scalameta::munit:1.0.0
    dependsOn: myapp
    extends: template-common
    isTestProject: true
templates:
  template-common:
    platform:
      name: jvm
    scala:
      options: -encoding utf8 -feature -unchecked
      strict: true
      version: 3.8.3

template-common carries the shared scala.version, recommended compiler options, and platform.name: jvm; both projects extend it.

The main source, myapp/src/scala/com/example/Main.scala:

package com.example

object Main {
  def greet(name: String): String = s"Hello, $name!"
}

@main def helloMain(): Unit =
  println(Main.greet("World"))

The @main annotation marks helloMain as the entry point — that's the symbol mainClass: com.example.helloMain points at in bleep.yaml.

The test, myapp-test/src/scala/com/example/MainTest.scala:

package com.example

class MainTest extends munit.FunSuite {
  test("greets by name") {
    assertEquals(Main.greet("World"), "Hello, World!")
  }
}

Step 3: Run it​

bleep run myapp
Hello, World!

Step 4: Run the tests​

bleep test myapp-test

Step 5: Add a dependency​

Scala libraries use :: (double colon) — that's a Scala-only shorthand for adding the Scala version suffix to the artifact ID. (For Java libraries, use a single :.) Edit bleep.yaml:

projects:
  myapp:
    extends: template-common
    dependencies:
      - com.lihaoyi::fansi:0.5.0
    platform:
      mainClass: com.example.helloMain

Step 6: Open it in your IDE​

bleep setup-ide

IntelliJ IDEA​

Open → select the project directory. The Scala plugin handles .scala files once BSP has imported the project. Don't import as a Maven/sbt project — bleep speaks BSP directly.

VS Code with Metals​

Open the project folder in VS Code. Metals will detect the BSP configuration and import.

Cross-building​

Scaffold a cross-built project with multiple --scala and --platform flags:

bleep new mylib --scala 213 --scala 3 --platform jvm --platform js

This produces one mylib project per (scala, platform) combination. See Cross-building for the full picture.

Project structure​

my-first-bleep-project/
├── bleep.yaml
├── myapp/
│   └── src/
│       └── scala/
│           └── com/
│               └── example/
│                   └── Main.scala
└── myapp-test/
    └── src/
        └── scala/
            └── com/
                └── example/
                    └── MainTest.scala

Coming from sbt? Bleep uses src/scala/ rather than src/main/scala/ because there is no src/test/scala/ to contrast with — tests live in their own sibling project (myapp-test) rather than under a test/ subtree. Same files, shorter paths.

Next steps​