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-dynverfor git-tag-based versioning - Formatter:
scalafmt - Linter / refactoring:
scalafixwithOrganizeImports - Testing: ScalaTest (primary)
- Effect system: ZIO (where applicable)
- Configuration:
zio-config4.x (typesafe/magnolia modules) feeding ZIO’sConfigProvider— one central config case class per application;pureconfigfor non-ZIO code — NOT scatteredsys.env/System.getenv - Versioning:
sbt-dynverwith-SNAPSHOTsuffix 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:
pushRemoteCacheToconfigured 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 derivedConfig(zio-configderiveConfig) and typed fields, defaults, and required markers - Config is loaded once as a
ZLayerat the application edge and provided by dependency injection; nosys.env/System.getenvor ad hocConfigProviderreads 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; hereapplication-<env>.confoverapplication.conf/reference.confsits under environment/secret-file providers, and local-development values come from the IDE/sbt run configuration, not a.envfile
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 viaConfigProvideras aZLayer. Typesafe Config has no built-in per-environment file convention, so build the file layer explicitly in the config module: readAPP_ENVonce viasys.env, thenConfigFactory.parseResources(s"application-$env.conf").withFallback(ConfigFactory.load())(the latter already mergesapplication.confoverreference.conf), wrapped withTypesafeConfigProvider.fromTypesafeConfig; compose an environment/secret-fileConfigProviderahead of it withorElse(layering pertwelve-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-dynverfor versioning; do not hardcode version strings dynverSeparator := "-"for Docker compatibilitypackageTimestamp := Package.gitCommitDateTimestampfor reproducible artifacts- Read configuration only by depending on the config layer; ban
sys.env/System.getenvoutside the config module (scalafixDisableSyntax.regexwith patterns forSystem\\.getenv,sys\\.env, andConfigProvider\\.envProvider; it is syntactic, so the config module opts out with// scalafix:off DisableSyntax(closed with// scalafix:on)) - Exclude
.bloop,.cache,.targets,.metalsfrom IDE indexing
Testing
- Framework: ScalaTest
- Config in tests: provide
ConfigProvider.fromMap(...)or a testZLayer; 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 checksbt scalafixAll OrganizeImports— import organizationsbt test— unit test suitesbt compile— compile all subprojects
Dependency Management
- Declare in
project/Dependencies.scalaorbuild.sbtwith explicitlibraryDependencySchemesfor version conflicts - Use
VersionScheme.Alwayssparingly (only for known-safe upgrades) - Remote cache:
pushRemoteCacheToreduces 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"
}
]
}