ScalaPB: Protocol Buffer Code Generation for Scala

ScalaPB's Code Generation Contract

ScalaPB solves the impedance problem between Protocol Buffer schemas and ordinary Scala source code. Its README describes it as a `protoc` plugin for Scala that generates case classes, parsers, and serializers. The intended users are Scala developers whose services communicate through `.proto` schemas, particularly teams that want generated message types to behave like normal Scala values rather than mutable Java builder objects.

The repository supports both proto2 and proto3. It also documents functional updates through lenses, Scala.js and gRPC integration, JSON conversion, user-defined options, and protobuf extensions. These are separate integration paths rather than automatic features of every generated class. An adoption decision should therefore distinguish the core compiler output, which creates message classes and serialization support, from integrations that require their corresponding libraries or build settings.

ScalaPB places each top-level message and enum in a separate Scala file. The README attributes this layout to improved incremental compilation behavior. Generated types use the `.proto` file as part of their package name, while Java protoc output conventionally uses a CamelCase file-derived outer class. Scala-generated and Java-generated protobuf types can therefore coexist in one project, which gives a migration path based on package and type boundaries rather than requiring every caller to change at once.

How protoc Becomes Scala Source

The visible data flow is a schema-to-source pipeline. A `.proto` schema is processed through the protobuf compiler environment, where ScalaPB acts as a plugin. Its generated output consists of Scala source files representing messages and enums, together with parsers and serializers for the protocol representation.

That design places ScalaPB before the normal Scala compilation stage. It does not parse network data dynamically. Instead, it produces the source that the Scala compiler then compiles with the rest of the application. The package arrangement is intentional: the proto filename forms part of the generated Scala package, allowing generated Scala code to sit beside Java protoc output without adopting Java's file-named outer-class convention.

Optional conversion methods can translate between Java protocol buffer instances and Scala protocol buffer instances. The README says these methods are useful while a large codebase moves from Java to Scala. There is an important dependency for `fromAscii`: the current implementation delegates ASCII parsing to the Java protobuf implementation. That boundary means Java interoperability is not merely an optional extra for every feature. It is part of the documented mechanism for this operation.

For functional message changes, ScalaPB can generate lens-based update methods. The README presents this as support for nested-structure updates, but it does not provide enough API detail here to prescribe a code sample. Consumers should consult the ScalaPB website before assuming that lenses are included in the base configuration.

Installing the sbt Plugin and Compiler Plugin

The README documents installation through the `sbt-protoc` sbt plugin. It says to create `project/protoc.sbt` and include the plugin declaration and compiler plugin dependency shown below. The versions in this README example are older than some listed releases, so the example should be treated as a documented setup pattern rather than evidence that those exact coordinates define the newest compatible combination.

Add this to `project/protoc.sbt`:

addSbtPlugin("com.thesamet" % "sbt-protoc" % "1.0.6")

libraryDependencies += "com.thesamet.scalapb" %% "compilerplugin" % "0.11.3"

The README then requires a ScalaPB target in `build.sbt`:

Compile / PB.targets := Seq(
  scalapb.gen() -> (Compile / sourceManaged).value / "scalapb"
)

This configuration associates `scalapb.gen()` with the standard managed-source location for the `Compile` configuration. When sbt processes the protobuf build task, the generated Scala files are directed below `sourceManaged` under the `scalapb` directory. The README links to the `ScalaPB SBT Settings` documentation for additional options, including configuration beyond this minimal target.

For a first use, add or reference the project's `.proto` definitions and run the normal sbt build process that invokes `PB.targets`. The README does not document a complete first-message tutorial, a sample generated class, or the exact sbt task used to trigger generation, so inventing those details would be misleading. The documented next destination is the ScalaPB website, while the repository's `examples/basic/` and `examples/custom_options/` directories provide the concrete starting points visible in the repository layout.

Java Interoperation and Migration Boundaries

The strongest project-specific feature is coexistence with Java-generated protobuf code. A Scala service can use generated Scala case classes while Java services or libraries continue using their existing protoc output. Optional generated conversion methods connect the two representations.

That design is useful for gradual migration, but it does not remove compatibility work from the project. Package naming differs between ScalaPB and Java protoc output, and `fromAscii` relies on the Java implementation. Teams retaining Java components must preserve compatible schemas and ensure that both generated sides are available where conversion is required. The repository includes Java-related end-to-end material through `e2e-withjava/`, which indicates that interoperability is treated as a distinct integration area rather than an incidental example.

The README also lists SparkSQL compatibility through a helper library. That does not mean arbitrary SparkSQL applications can use any ScalaPB message without setup. It identifies a supported route, while the omitted configuration details remain outside the available documentation. Similarly, JSON conversion is listed as a capability, but no serializer library, dependency, or runtime configuration is named here. These features should be evaluated as separate adoption checks rather than bundled into the core generation claim.

Verification, Compatibility, and Release State

ScalaPB's development model centers on differential tests against Java protobuf behavior. According to the README, its test process generates varied `.proto` schemas, populates test data, and checks that generated Scala code behaves like the reference Java implementation. The suite varies the number of files, cross-file references, and message nesting. A smaller `e2e` suite exercises the sbt plugin by compiling proto files and running ScalaCheck checks over the outputs.

The full tests are documented with:

sbt test

The README says this suite takes a few minutes. The smaller end-to-end suite is documented as:

./e2e.sh

These commands are repository verification instructions, not evidence that a particular consumer project will pass. Consumer projects still need compatible Scala versions, plugin versions, schema layout, and optional integration dependencies. The repository includes Scala 3 compatibility material, Scala-specific runtime directories, gRPC code, and generated-code fixtures, but the README excerpt does not define a complete compatibility matrix for every release.

The repository is not archived, and its last push was on 2026-10-15. Recent releases listed for the repository include `v0.11.21` on 2026-10-06, plus `v1.0.0-alpha.6` on 2026-07-06 and `v1.0.0-alpha.5` on 2026-05-27. The presence of both a 0.11 release and 1.0 alpha releases is a version-selection issue, not evidence that all versions are interchangeable. The README's install example still shows `compilerplugin` version `0.11.3`, so adopters must reconcile documented setup with current release compatibility.

ScalaPB is licensed under Apache-2.0. That identifier permits use under its license terms, but obligations such as notices and license distribution should be checked against the actual `LICENSE` file and the project's dependency context. The repository layout also includes `CHANGELOG.md`, `CONTRIBUTING.md`, compatibility scripts, and several runtime modules, which adds maintenance surface beyond a single compiler binary.

When ScalaPB Is the Wrong Choice

ScalaPB is the wrong tool for a project that refuses generated source code or has no protobuf compiler integration in its build. Its core output depends on running protoc through `sbt-protoc`, then compiling the generated Scala files. A build restricted to handwritten sources will not receive message classes from the documented setup.

It is also unsuitable when Java interoperability is mandatory but the delegation to Java protobuf cannot be accepted. The README specifically identifies the Java implementation as the current delegate for `fromAscii`. A team seeking a Scala-only ASCII parser would need behavior that this documented implementation does not claim to provide.

Finally, teams treating lenses, Scala.js, gRPC, SparkSQL, JSON, extensions, or user-defined options as turnkey features are misreading the scope of the README. The highlights establish supported directions, but the excerpt does not show the dependencies or configuration for each one. The project should be adopted only after the required integration path has been identified and its current documentation has been checked.

Editorial conclusion

ScalaPB is appropriate for Scala projects that want native case classes, functional updates, or a gradual path from Java-generated protobuf code. It is a poorer fit when the team will not add an sbt code-generation step or does not want generated sources tied to the protobuf toolchain. Verify the current `sbt-protoc` and `compilerplugin` versions against the official settings documentation, confirm the generated package layout with the planned `.proto` files, and test Java conversion before committing to a migration.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. scalapb/ScalaPB on GitHub