Uni

Essential Scala Utilities — Refined for Scala 3 with minimal dependencies.

Documentation

https://wvlet.org/uni/

For AI coding agents: read llms.txt (page index) or
llms-full.txt (all docs in one file), and see
Uni for AI Agents for canonical imports and an Airframe migration table.

Modules

uni and uni-test are cross-platform: JVM, Scala.js, and Scala Native.

Getting Started

Add the dependencies you need to your build.sbt (replace <version>
with the version shown in the Maven Central badge above):

// Core utilities (Design, logging, JSON, MessagePack, Rx, HTTP client, etc.)
libraryDependencies += "org.wvlet.uni" %% "uni" % "<version>"

// Netty-based HTTP server (JVM only; pulls in uni transitively)
libraryDependencies += "org.wvlet.uni" %% "uni-netty" % "<version>"

// Testing framework
libraryDependencies += "org.wvlet.uni" %% "uni-test" % "<version>" % Test
testFrameworks += new TestFramework("wvlet.uni.test.Framework")

On sbt 1.x, use %%% for uni and uni-test in Scala.js or Scala
Native projects (sbt 2.x uses %% for all platforms):

libraryDependencies += "org.wvlet.uni" %%% "uni" % "<version>"
libraryDependencies += "org.wvlet.uni" %%% "uni-test" % "<version>" % Test

Using uni

A minimal example using the logging API:

import wvlet.uni.log.LogSupport

class MyService extends LogSupport:
  def greet(name: String): String =
    info(s"Greeting ${name}")
    s"Hello, ${name}!"

@main def hello =
  val service = MyService()
  println(service.greet("World"))

See the reference docs for Design, Rx,
JSON/MessagePack, HTTP, and more.

Using uni-netty (HTTP server on the JVM)

uni-netty provides a Netty-based HTTP server:

import wvlet.uni.http.{Request, Response}
import wvlet.uni.http.netty.NettyServer
import wvlet.uni.rx.Rx

NettyServer
  .withPort(8080)
  .withRxHandler { request =>
    Rx.single(Response.ok(s"Hello from ${request.path}"))
  }
  .start { server =>
    println(s"Listening on ${server.localAddress}")
  }

See the REST Server guide for the
annotation-based router, filters, and the Scala.js / Scala Native
server backends (which need only uni).

Using uni-test

Write a test by extending UniTest:

import wvlet.uni.test.UniTest

class MyTest extends UniTest:
  test("addition works") {
    (1 + 1) shouldBe 2
  }

Run with sbt test. See the UniTest guide
for assertions, property-based testing, and more.

sbt 2.x Plugins

Uni also ships sbt plugins for sbt 2.x, usable in any sbt 2.x project
(with or without the uni library):

Add the ones you need to project/plugins.sbt:

// HTTP/RPC client generation + background fork-run (~uniRestart)
addSbtPlugin("org.wvlet.uni" % "sbt-uni" % "<version>")

// Cross-build one source tree for JVM, Scala.js, and Scala Native
addSbtPlugin("org.scala-js"     % "sbt-scalajs"          % "1.22.0")
addSbtPlugin("org.scala-native" % "sbt-scala-native"     % "0.5.12")
addSbtPlugin("org.wvlet.uni"    % "sbt-uni-crossproject" % "<version>")

// Run Scala.js tests in a real browser
addSbtPlugin("org.wvlet.uni" % "sbt-uni-playwright" % "<version>")

For example, sbt-uni-crossproject defines cross-platform projects with
shared sources in src/ and platform-specific code in .jvm/, .js/,
and .native/ folders:

lazy val core = crossProject(JVMPlatform, JSPlatform, NativePlatform)
  .crossType(CrossType.Pure)
  .in(file("core"))
  .settings(/* shared settings */)

See the build plugin docs for
details.

License

Apache License 2.0