Airframe is a collection of essential building blocks for Scala applications — logging, JSON and MessagePack serialization, dependency injection, an HTTP server and client with RPC support, and the AirSpec testing framework — aimed at Scala developers building services and libraries.
What it is
Airframe is an open-source Scala library suite hosted at wvlet.org/airframe and published to Maven Central under the org.wvlet.airframe group. It bundles several independent modules that most service codebases end up needing: a logger, object serialization using JSON or MessagePack, a dependency injection container, an HTTP server and client with RPC support, and AirSpec, a functional testing library. The project uses Scala 3 as its default Scala version and also publishes for Scala 2.12 and 2.13.
The concrete problem it solves is assembly. Instead of stitching together a DI framework, a serialization library, a logging facade, a test runner, and an RPC layer from separate projects with separate release cycles, a Scala team pulls one consistent set of modules from the same group and version. It lives in the Scala ecosystem and, in the dependency-injection slot, stands in for general-purpose containers such as Guice, which appears in the project's own topic list alongside gRPC, JSON, MsgPack, SQL, and JMX.
Key capabilities
- Airframe DI, a dependency injection library documented as tailored to Scala rather than adapted from a Java container.
- AirSpec, a functional testing library for writing Scala tests.
- Airframe RPC, a framework for using Scala on both the frontend and the backend.
- Object serialization in both JSON and MessagePack formats.
- HTTP server and client support with RPC integrated into the same module.
- Logging, JMX, and metrics modules, matching the registry's Monitoring & Observability category.
- Scala.js support, indicated by the Scala.js 1.0.0 badge in the README.
- Binary compatibility checking through
sbt mimaReportBinaryIssues with AIRFRAME_BINARY_COMPAT_VERSION set in build.sbt.
Who uses it and how
- Teams on Scala 3 use the default artifact set directly; teams still on Scala 2.12 or 2.13 switch with
++ 2.12 or ++ 2.13 in the sbt console.
- Full-stack Scala projects use Airframe RPC to write frontend and backend code in one language instead of splitting across a separate client stack.
- Services that need observability wire in the logger, JMX, and metrics modules from the same dependency group rather than adding three unrelated libraries.
- Library and application maintainers run
sbt mimaReportBinaryIssues before release so upgrades do not break consumers on older Airframe versions.
- Contributors and maintainers follow the documented release flow, running
ruby ./scripts/release.rb to tag, update docs/release-notes.md, and publish artifacts to Maven Central, which takes 10-30 minutes.
Getting started
Airframe is consumed as a library dependency from Maven Central under the org.wvlet.airframe group, for example airframe_2.12, indexed on index.scala-lang.org. There is no Docker image, compose file, or hosted service in the project's documentation — it is added to an sbt build and used in-process.
How it compares
The registry facts list no paid products that Airframe replaces, so the honest comparison is internal to the Scala tool space: its dependency injection module occupies the role that Guice occupies generally, and its RPC module occupies territory adjacent to gRPC, both of which appear only as topics here rather than as stated replacements. Where it differs in kind is packaging — those concerns arrive as one Apache-2.0-licensed project with a shared version line rather than as separate dependencies.
When to use it — and when not to
Airframe is a library, not a service, so a self-hoster operates nothing beyond the JVM application that embeds it; there is no database, object storage, or SMTP component to run. Teams outside Scala, or teams that have already standardized on a Java-native DI container and serialization stack, gain little from adopting it. The README also leans toward maintainers: it documents the release and binary-compatibility process in detail but shows no installation snippet in the excerpt, and the repository carries 105 open issues, so expect to read the linked module documentation before committing to a version.
project readme (upstream, from github) — read inline
Airframe https://wvlet.org/airframe is essential building blocks for developing applications in Scala, including logging, object serialization using JSON or MessagePack, dependency injection, http server/client with RPC support, functional testing with AirSpec, etc.
Resources
Framework
For Developers
Airframe uses Scala 3 as the default Scala version. To use Scala 2.x versions, run ++ 2.12 or ++ 2.13 in the sbt console.
Releasing
For every PR, release-drafter will automatically label PRs using the rules defined in .github/release-drafter.yml.
To publish a new version, first, create a new release tag as follows:
$ git switch main
$ git pull
$ ruby ./scripts/release.rb
This step will update docs/release-noteds.md, push a new git tag to the GitHub, and
create a new GitHub relese note.
After that, the artifacts will be published to Sonatype (a.k.a. Maven Central). It usually takes 10-30 minutes.
Note: Do not create a new tag from GitHub release pages, because it will not trigger the GitHub Actions for the release.
Binary Compatibility
When changing some interfaces, binary compatibility should be checked so as not to break applications using older versions of Airframe. In build.sbt, set AIRFRAME_BINARY_COMPAT_VERSION to the previous version of Airframe as a comparison target. Then run sbt mimaReportBinaryIssues to check the binary compatibility.
LICENSE
Apache v2
Contributors
Many thanks to everyone who has contributed to our progress:
