Skip to content

Scala + sbt

Category: Tech Stack · Areas: all

Description

Category

tech-stack

Areas

all

Slot

language-runtime

Components

  • Language: Scala 2.x (pinned per project)
  • Build system: sbt with sbt-dynver for git-tag-based versioning
  • Formatter: scalafmt
  • Linter / refactoring: scalafix with OrganizeImports
  • Testing: ScalaTest (primary)
  • Effect system: ZIO (where applicable)
  • Configuration: zio-config 4.x (typesafe/magnolia modules) feeding ZIO’s ConfigProvider — one central config case class per application; pureconfig for non-ZIO code — NOT scattered sys.env/System.getenv
  • Versioning: sbt-dynver with -SNAPSHOT suffix for dirty/non-tagged commits

Constraints

  • All code must pass scalafmtCheckAll (zero diff)
  • All code must pass scalafixAll OrganizeImports
  • No uncommitted changes should reach CI with a clean version string
  • Concurrent task limits: derived from CPU count ((nproc / 2) - 1, min 2)
  • Remote build cache: pushRemoteCacheTo configured for incremental CI builds
  • Library dependency schemes must be explicit to avoid eviction noise
  • All configuration is declared in one central config case class (single module, e.g. AppConfig.scala) with a derived Config (zio-config deriveConfig) and typed fields, defaults, and required markers
  • Config is loaded once as a ZLayer at the application edge and provided by dependency injection; no sys.env/System.getenv or ad hoc ConfigProvider reads outside the config module
  • Secrets use Config.Secret (zio) or an equivalent redacting type; invalid or missing config fails at startup (layer construction), not at first use
  • Config layering follows twelve-factor; here application-<env>.conf over application.conf/reference.conf sits under environment/secret-file providers, and local-development values come from the IDE/sbt run configuration, not a .env file

When to use

Existing Scala projects on the sbt ecosystem. New Scala services should evaluate ZIO + sbt as the default stack. Note: projects actively migrating from Scala to TypeScript should prefer typescript-bun for new code and maintain scala-sbt only for the remaining Scala surface.

Artifact Impact

Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):

  • TD: sbt-dynver versioning, format/lint gates, build-cache and concurrency conventions, central config case class and its config-key contract (owner and source per key)

Practices by activity

Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.

Requirements (Frame activity)

  • Identify whether the project is greenfield Scala or has a migration plan to another runtime
  • If mid-migration, scope new work to the target stack and minimize new Scala surface

Design

  • Organize as an sbt multi-project build; each logical module is a subproject
  • Depend on ZIO for effect management, ZIO JSON for serialization where applicable
  • Centralize configuration in one case class with deriveConfig (zio-config-magnolia) and load it via ConfigProvider as a ZLayer. Typesafe Config has no built-in per-environment file convention, so build the file layer explicitly in the config module: read APP_ENV once via sys.env, then ConfigFactory.parseResources(s"application-$env.conf").withFallback(ConfigFactory.load()) (the latter already merges application.conf over reference.conf), wrapped with TypesafeConfigProvider.fromTypesafeConfig; compose an environment/secret-file ConfigProvider ahead of it with orElse (layering per twelve-factor)
  • Define portable contracts at service seams to enable incremental migration

Implementation

  • Format before commit: run scalafmtAll + scalafixAll OrganizeImports (or the combined alias)
  • Use sbt-dynver for versioning; do not hardcode version strings
  • dynverSeparator := "-" for Docker compatibility
  • packageTimestamp := Package.gitCommitDateTimestamp for reproducible artifacts
  • Read configuration only by depending on the config layer; ban sys.env/System.getenv outside the config module (scalafix DisableSyntax.regex with patterns for System\\.getenv, sys\\.env, and ConfigProvider\\.envProvider; it is syntactic, so the config module opts out with // scalafix:off DisableSyntax (closed with // scalafix:on))
  • Exclude .bloop, .cache, .targets, .metals from IDE indexing

Testing

  • Framework: ScalaTest
  • Config in tests: provide ConfigProvider.fromMap(...) or a test ZLayer; never depend on a developer’s local environment
  • Property-based: ScalaCheck (if used)
  • Run: sbt test
  • CI: separate unit and integration suites; integration tests may require Docker services

Quality Gates (pre-commit / CI)

  • sbt scalafmtCheckAll — format check
  • sbt scalafixAll OrganizeImports — import organization
  • sbt test — unit test suite
  • sbt compile — compile all subprojects

Dependency Management

  • Declare in project/Dependencies.scala or build.sbt with explicit libraryDependencySchemes for version conflicts
  • Use VersionScheme.Always sparingly (only for known-safe upgrades)
  • Remote cache: pushRemoteCacheTo reduces incremental CI time
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
concerns/scala-sbt.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:c4408edf…a2961adb

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/concerns/scala-sbt/",
        "digest": {
          "alg": "sha256",
          "value": "c4408edf022f1a411db10b3a80c2627debcbb5f1d54f30958648ae35a2961adb"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "wXr29SNSdHIYQ1rN-aMRiUjA6pdaRJiW7DdhgTyKg1jHzi6rS7H3SUDJ5wXeDs1nqy63NpTSjij8ccgo5lj8AA",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}