How to Build a ZIO Full-Stack Web Application

Scala/ScalaJS

Scala build here is driven by SBT in a rather classic way, except for the shared project that will be cast in two different worlds .jvm and .js Generated build contains documentation on details. Please take a look and don’t hesitate to ask question/provide PR on the g8.

For ScalaJS

• “org.scala-js” % “sbt-scalajs” % “1.17.0”
• “ch.epfl.scala” % “sbt-scalajs-bundler” % “0.21.1” will bundle the app
• “ch.epfl.scala” % “sbt-web-scalajs-bundler” % “0.21.1” will expose the bundle as classpath resource for sbt-web (websjar).

Cross Building

“org.portable-scala” % “sbt-scalajs-crossproject” % “1.3.2”

This is the plugin that will allow to spread project resources between JS and JVM worlds. Shared project configuration 👇

• Server project aka Scala JVM depends share.jvm variant
• Client project aka Scala JS depends on shared.js variant

ScalaJS and ScalaJS bundler are smart enough to cross-compile and deploy module/shared/src/main/scala sources in both target.

JS Integration

JS integration is also a classical one with NPM and Vite, here a again specific configuration is limited to vite.config.js

import { defineConfig } from "vite";
import scalaJSPlugin from "@scala-js/vite-plugin-scalajs";

export default defineConfig({
  plugins: [
    scalaJSPlugin({
      // path to the directory containing the sbt build
      // default: '.'
      cwd: "../..", // (1)

      // sbt project ID from within the sbt build to get fast/fullLinkJS from
      // default: the root project of the sbt build
      projectID: "client", // (2)

      // URI prefix of imports that this plugin catches (without the trailing ':')
      // default: 'scalajs' (so the plugin recognizes URIs starting with 'scalajs:')
      uriPrefix: "scalajs",
    }),
  ],
  build: {
    sourcemap: true,
  },
  // base: "/zio-laminar-demo",
});

Where most of the work is achieved by @scala-js/vite-plugin-scalajs plugin, which needs to know:

• (1) the location of the sbt build and which project to use
• (2) the sbt project ID to get fast/fullLinkJS from

During development, the sbt project must be bundled as ESModule. If you are using the g8 template, this is already the case.

In this setup:

• fastLinkJS runs the Scala to JS process in watch mode.
• Vite will serve the app in localhost and reload the client automatically.

This setting will allow Vite to hot reload changes on the fly, giving an incredible developer experience.

ZIO

A library for asynchronous and concurrent programming in Scala. There’s a lot to say about it and Rock the JVM teaches this in detail in a dedicated ZIO course, but we’ll cover the essentials below.

ZIO is a data type that represents an effectful program that when evaluated:

• will require an element of type R to execute
• may produce a value of type A
• may fail with an error of type E

Sometimes an oversimplified mental model is to represent ZIO as:

  type ZIO[R, E, A] = R => Either[E, A]

But ZIO is much more than that, it is an extensive library that provides a lot of utilities to handle effects, blocking, concurrency, retry, and so on. Very importantly, ZIO is a monad, and as such it provides a lot of combinators to handle effects, errors and dependencies.

A ZIO aka program, workflow, or effect:

• can be combined with other effects
• can handle errors, returning new effects as result
• will release resources when acquired

At a glance, ZIO[–R,+E,+A] uses variance annotations to allow a very convenient constructions like our Server side application:

object HttpServer extends ZIOAppDefault {

  val runMigrations: ZIO[FlywayService, Throwable, Unit] = [...]              // (1)

  val server: ZIO[PersonService & Server, Nothing, Unit] = [...]              // (2)

  val program: ZIO[FlywayService & PersonService & Server, Throwable, Unit] = // (4)
    for {
      _ <- runMigrations                                                      // (3)
      _ <- server
    } yield ()

  override def run =
    program
      .provide( // (5)
         Server.default,
        // Service layers
        PersonServiceLive.layer,
        FlywayServiceLive.configuredLayer,
        // Repository layers
        UserRepositoryLive.layer,
        Repository.dataLayer
        // Uncomment to get a mermaid diagram of the dependencies is compilation logs.
        //,       ZLayer.Debug.mermaid
      )
}

• Two ZIO effects are running in this application:
  • (1) runMigrations is a ZIO[FlywayService,…] that depends on a FlywayService, and that will handle the database migrations.
  • (2) server is a ZIO[PersonService & Server,…] that depends on a PersonService and a Server and that will handle the HTTP server.
• Those two effects combine in a for comprehension (3) to produce a new ZIO (4) that accumulate the dependencies: ZIO[FlywayService & PersonService & Server,…]

To be runnable, those dependencies need to be satisfied (5). This is what layers are made for. A layer is a ZIO concept that will provide a service, and that can depend on other services. Letțs see how ZIO, assembles the application, one layer after another.

object Repository {

  private def datasourceLayer: TaskLayer[DataSource] =
                                    Quill.DataSource.fromPrefix("db")            // (1)

  def quillLayer: URLayer[DataSource, Postgres[SnakeCase.type]] =
                                    Quill.Postgres.fromNamingStrategy(SnakeCase) // (2)

  def dataLayer: TaskLayer[Postgres[SnakeCase.type]] =
                                    datasourceLayer >>> quillLayer               // (3)

}

User Repository

The User Repository is a classic repository that will handle the User entity.

trait UserRepository:                            // (1)
  def create(user: User): Task[User]
  def getById(id: Long): Task[Option[User]]

                                                 // (2)
class UserRepositoryLive private (quill: Quill.Postgres[SnakeCase]) extends UserRepository {

  import quill.*

  inline given SchemaMeta[User] = schemaMeta[User]("users")     // (3)
  inline given InsertMeta[User] = insertMeta[User](_.id)
  inline given UpdateMeta[User] = updateMeta[User](_.id, _.creationDate)

  override def create(user: User): Task[User] =
    run(query[User].insertValue(lift(user)).returning(r => r)) // (4a)
  override def getById(id: Long): Task[Option[User]] =         // (4b)
    run(query[User].filter(_.id == lift(Option(id)))).map(_.headOption)
}

object UserRepositoryLive: // (5)                                        (6)
  def layer: RLayer[Postgres[SnakeCase], UserRepositoryLive] = ZLayer.derive[UserRepositoryLive]

• (1) Repository trait
• (2) Repository implementation, with Quill Postgres injection
• (3) Quill Meta, to map the User case class to the users table
• (4) Quill queries
• (5) Repository layer
• (6) One of the many ZIO macro that will generate the layer for you, from the constructor of the class (2).

Note how ZLayer.derive[UserRepositoryLive] is used to generate the layer from the constructor of the class, and how this layer is then depends on the Postgres[SnakeCase].

Quill is a compile-time query language for Scala and SQL. It allows to write queries in Scala and compile them to SQL.

Quill compiles (4a) and (4b) to SQL like this:

INSERT INTO users (name,email,age,creation_date) VALUES (?, ?, ?, ?) RETURNING id, name, email, age, creation_date;
SELECT x4.id, x4.name, x4.email, x4.age, x4.creation_date AS creationDate FROM users x4 WHERE x4.id IS NULL AND ? IS NULL OR x4.id = ?;

Flyway Service

In the same way, Flyway service is a layer that will handle the database migrations.

object FlywayServiceLive {

  private val DATASOURCE_PATH = "db"

  def live: RLayer[FlywayConfig, FlywayService] = ZLayer( // (1)
    for {
      config <- ZIO.service[FlywayConfig]
      flyway <- ZIO.attempt(Flyway.configure()
                   .dataSource(config.url, config.user, config.password).load())
    } yield new FlywayServiceLive(flyway)
  )

  val configuredLayer: TaskLayer[FlywayService] = Configs.makeConfigLayer[FlywayConfig](DATASOURCE_PATH)
                                                             >>> live  // (2)
}

• (1) is a layer that will provide a FlywayService, it depends on the availability of FlywayConfig service.
• (2) Inject a FlywayConfig in a the previous layer and the remove the dependency on the config.

trait PersonService {             // Service trait
  def register(person: Person): Task[User]
}
                                  // Dependency injection
class PersonServiceLive private (userRepository: UserRepository) extends PersonService {
  def register(person: Person): Task[User] =
    if person.age < 18 then ZIO.fail(TooYoungException(person.age))
    else userRepository.create(
      User(
        id = None,
        name = person.name,
        email = person.email,
        age = person.age,
        creationDate = ZonedDateTime.now()
      )
    )
}

object PersonServiceLive {           // Layer derivation (macro) from the constructor
  val layer: RLayer[UserRepository, PersonService] = ZLayer.derive[PersonServiceLive]
}

class PersonServiceLive private (userRepository: UserRepository, notificatonService: NotificationService) extends PersonService {
  def register(person: Person): Task[User] =
    if person.age < 18 then ZIO.fail(TooYoungException(person.age))
    else for {
      user <- userRepository.create(
        User(
          id = None,
          name = person.name,
          email = person.email,
          age = person.age,
          creationDate = ZonedDateTime.now()
        )
      )
      _ <- notificatonService.notify(user)
    } yield user
}

object PersonServiceLive:
  val layer: RLayer[UserRepository & NotificationService, PersonService] =
     ZLayer.derive[PersonServiceLive]

private val server: ZIO[PersonService & Server, IOException, Unit] =
    for {
      _            <- Console.printLine("Starting server...")
      apiEndoints  <- HttpApi.endpointsZIO        // (1)
      docEndpoints = SwaggerInterpreter()         // (2)
                       .fromServerEndpoints(endpoints, "zio-laminar-demo", "1.0.0")
      _            <- Server.serve(               // (3)
             ZioHttpInterpreter(serverOptions)
               .toHttp(metricsEndpoint :: webJarRoutes :: endpoints ::: docEndpoints)
                                                  // (4)
           )
    } yield ()

object HttpApi {
  private def gatherRoutes(
    controllers: List[BaseController]
  ): List[ServerEndpoint[Any, Task]] =
    controllers.flatMap(_.routes)

  private def makeControllers: URIO[PersonService, List[BaseController]] = for {
    healthController <- HealthController.makeZIO
    personController <- PersonController.makeZIO
  } yield List(healthController, personController)

  val endpointsZIO: URIO[PersonService, List[ServerEndpoint[Any, Task]]] =
                makeControllers.map(gatherRoutes)
}

Shared Endpoint Definitions

In the shared module, the API endpoints are defined as immutable data structures.

object PersonEndpoints {
  val get: Endpoint[Unit, Unit, String, Person, Any] = endpoint.get
    .in("person")
    .out(jsonBody[Person])
    .errorOut(stringBody)
    .summary("Get a person by id")

  val create: Endpoint[Unit, Person, Throwable, User, Any] = baseEndpoint
    .tag("person")
    .name("person")
    .post
    .in("person")
    .in(
      jsonBody[Person]                                         // (1)
        .description("Person to create")
        .example(Person("John", 30, Left(Cat("Fluffy"))))
    )
    .out(jsonBody[User])
    .description("Create person")

}

This is a simple GET endpoint that will return a Person and a POST endpoint that will create a Person and return a User.

From this definition, Tapir will help generate the client and server side code, the documentation and the tests.

Server Side

On the server side, Tapir Endpoints.create will be implemented by a ZIO effect, through the zServerLogic combinator.

                                           // (1)
class PersonController private (personService: PersonService) extends BaseController {
  [...]

  val create: ServerEndpoint[Any, Task] = PersonEndpoint.createEndpoint
    .zServerLogic(                                                // (2)
      p => personService.register(p)
    )

  val routes: List[ServerEndpoint[Any, Task]] =
    List(create, get, ...)                                        // (3)
}

object PersonController {
  def makeZIO: URIO[PersonService, PersonController] =            // (4)
    ZIO.service[PersonService]                                    // (4a)
      .map(personSevice => new PersonController(personService))   // (4b)
}

Here are the important bits:

• (1) Dependency Injection.
• (2) Controller implementation, where json codec are transparently handled by Tapir:
  • p: Person is the payload of the request as describe in the endpoint definition.
  • personService.register(p) is the ZIO effect that will register the person.
• (3) List of endpoints that will be served by the controller.
• (4) Service instantiation: URIO[PersonService, PersonController]
  • (4a) Get the PersonService from the environment.
  • (4b) Instantiate the PersonController with the PersonService.

Everything is described as ZIO effects. URIO[PersonService, PersonController] is a ZIO that needs a PersonService and will produce a PersonController and cannot fail.

URIO is a type alias for a ZIO that cannot fail:

type URIO[R, A] = ZIO[R, Nothing, A]

zServerLogic is part of the Tapir ZIO support, and bridges a ZIO in the Rest API. Itis a combinator that will transform a ZIO effect into a server logic, it will handle the error and the success case.

Tapir provides a lot of combinators to handle the ZIO effect, Cats Effect or Future.

Client Side

On the client side, Tapir will allow to interact as client, it will leverage the same endpoint definition to generate the client side code.

It will smartly generate the client side code, that will be used in the Laminar UI.

HTTP Client, Unsecured and Secured

On the client side, Tapir will allow to interact as client, is a very straightforward way:

 Button(
  "-- Post -->",
  onClick --> { _ =>     // (1)
    PersonEndpoint       // (2)
      .createEndpoint(
        personVar.now()  // (2a)
      )                  // (2b)
      .emitTo(           // (3a)
        userBus          // (3b)
      )
  }
)

We have:

• (1) the handling of a Laminar UI event
• (2) a HTTP endpoint
  • (2a) reads the current value of a Laminar Var
  • (2b) turns into ZIO effect to handle the HTTP request
• (3) an effect that, when evaluated
  • (3a) will push its value to an event bus
  • (3B) which is consumed by the Laminar UI

This is a lot of magic in a single line!

In the same way that on server side zServerLogic bridges ZIO in Tapir through an extension method, on client side two extension methods are used:

• From laminar to ZIO
• From ZIO back to Laminar

This is the power of Scala 3 extension methods, that allows to extend existing classes with new methods.

A first extension, turns this endpoint value into a function:

extension [I, E <: Throwable, O](endpoint: Endpoint[Unit, I, E, O, Any])
    /**
     * Call the endpoint with a payload, and get a ZIO back.
     * @param payload
     * @return
     */
    def apply(payload: I): RIO[BackendClient, O] =
      ZIO.service[BackendClient]
        .flatMap(_.endpointRequestZIO(endpoint)(payload))

When called, this turns the enhanced endpoint to a function that:

• can take arbitrary input I
• can use a provided BackendClient
• and will produce a ZIO effect producing an arbitrary output O

Simply said, with this extension in scope, now createEndpoint can be used as a function:

def createEndpoint[I, O](payload: I): RIO[BackendClient, O]

Note: RIO is just a type alias where error are Throwable:

type RIO[R, A]= ZIO[R, Throwable, A]

This effect needs a BackendClient to run - look at ZIO.service[BackendClient].

This is what the second extension will satisfy in a glimpse of Scala:

extension [E <: Throwable, A](zio: ZIO[BackendClient, E, A])
    /**
     * Emit the result of the ZIO to an EventBus.
     *
     * @param bus
     */
    def emitTo(bus: EventBus[A]): Unit =
      Unsafe.unsafe { implicit unsafe =>                           // (1)
        Runtime.default.unsafe.fork(                               // (2)
          zio
            .tapError(e => Console.printLineError(e.getMessage())) // (3)
            .tap(a => ZIO.attempt(bus.emit(a)))                    // (4)
            .provide(BackendClientLive.configuredLayer)            // (5)
        )
      }

This extension will allow to run the ZIO effect and emit the result to an EventBus.

• (1) Unsafe is a ZIO utility to run unsafe code.
• (2) Runtime is the ZIO runtime forked (worker maybe ?).
• (3) tapError will log the error if any.
• (4) tap will emit the result to the EventBus.
• (5) provide the BackendClient service to the effect, with a layer.

BackendClientLive.configuredLayer is the layer that will provide the BackendClient service, this is where most of the magic happens.

object BackendClientLive:
  val layer = ZLayer.derive[BackendClientLive]

  val configuredLayer: ULayer[BackendClient] = {
    val backend: SttpBackend[Task, ZioStreams] = FetchZioBackend()
    val interpreter                            = SttpClientInterpreter()
    val config                                 = BackendClientConfig(Some(uri"${Constants.backendBaseURL}"))

    ZLayer.succeed(backend) ++ ZLayer.succeed(interpreter) ++ ZLayer.succeed(config) >>> layer
  }

In short term, in this one-liner we:

• open a channel to a Rest API in a full type safe manner
• serialised the case class to a JSON payload
• wait for the result.
• piped the deserialized result in UI.

Secured Endpoint

In the same way, a secured client can be defined, that will handle the authentication and the authorization.

Of course, it will be a bit more complex, but the same principles will apply.

Tapir does distinguish the secured endpoints from the unsecured ones, and will generate the client side code accordingly.

For example, a secured endpoint will be defined like this:

val profile: Endpoint[String, Boolean, Throwable, (User, Option[Pet]), Any] = baseEndpoint
    .securityIn(auth.bearer[String]())
    .tag("person")
    .name("profile")
    .get
    .in("profile")
    .in(query[Boolean]("withPet").default(false))
    .out(jsonBody[(User, Option[Pet])])
    .description("Get profile")

Notice the first type parameter of the endpoint, it is a String, that will be the token, and that will be used to authenticate the request.

This is a secured endpoint, that will require a bearer token to be called.

trait SecuredBaseController[SI, Principal](
    principalExtractor: SI => Task[Principal]                       // (1)
):
  /** Enriches an endpoint with security logic
    */
  extension [I, O, R](endpoint: Endpoint[SI, I, Throwable, O, R])   // (2)
    /** ZIO security logic for a server endpoint
      *
      * Extracts the user principal from
      * the request Security Input, and applies
      *
      * @param logic,
      *   curryied function from user principal
      *   to request to response
      * @return
      */
    @SuppressWarnings(Array("org.wartremover.warts.Any"))
    def securedServerLogic(
        logic: Principal => I => Task[O]                            // (3)
    ): ServerEndpoint[R, Task] =
      endpoint
        .zServerSecurityLogic(principalExtractor)
        .serverLogic(principal => input => logic(principal)(input))

class PersonController private (personService: PersonService, jwtService: JWTService)
    extends BaseController
    with SecuredBaseController[String, UserID](jwtService.verifyToken) {    // (1)


  val profile: ServerEndpoint[Any, Task] =
    PersonEndpoint.profile.securedServerLogic { userId => withPet =>        // (2)
      personService.getProfile(userId, withPet)
  }
}

val userBus = new EventBus[(User, Option[Pet])]

def apply() = div(
                child <-- session(                                    // (1)
                  div(h1("Please log in to view your profile"))       // (2)
                )(_ =>
                  div(
                    onMountCallback { _ =>                            // (3)
                      PersonEndpoint.profile(false).emitTo(userBus)   // (4)
                    },
                    h1("Profile Page"),                               // (5)
                    // Display the user profile

extension [I, E <: Throwable, O](endpoint: Endpoint[String, I, E, O, Any])    // (1)
  /** Call the secured endpoint with a payload, and get a ZIO back.
    * @param payload
    * @return
    */
  @targetName("securedApply")
  def apply[UserToken <: WithToken](                                          // (2)
      payload: I
  )(using session: Session[UserToken]): RIO[SameOriginBackendClient, O] =     // (3)
    ZIO
      .service[SameOriginBackendClient]
      .flatMap(_.securedEndpointRequestZIO(endpoint)(payload))                // (4)

Take Away on HTTP Client

With this extension methods, secured endpoints can be called in the same way as unsecured endpoints, and the token will be handled in a full type safe manner.

This is part of an external library.