full-zio-stack

A client/server app with a full scala 3/zio 2 stack. These are some of the technologies I'm using, I briefly describe why and mention some options in case my choices are not yours. One of the most difficult thing in our field is to be able to choose a set of technologies for a project that fit well together (or can be easily made to fit), are well supported, are easy to find developers who know them (or easy to train in them), modern, etc.

Currently on the stack

ZIO Based

zio-http

Caliban

zio-config

zio-logging

zio-test

zio-json

zio-jdbc

zio-sql

doobie

Not strictly zio, but with the cats zio interop, it's super easy to combine

quill

Non-ZIO tech

scala.js (https://www.scala-js.org/)

I really wouldn't use anything else right now to create web pages. My biggest complaint about scala-js is that because all the source documents are scala it puts graphic web designers at a disadvantage. It really forces you to separate the graphic design domain (css) from the web content (traditionally html, now scala produced html), this is not necessarily a bad thing, but it may force your developers to do things that normally the graphic design team takes care of.
Alternatives: https://www.playframework.com/

scalajs-react (https://github.com/japgolly/scalajs-react)

I've been using scalajs-react for a long time, so historical reasons lead me to choose it. I particularly like it's use of it's zio-like Callback (it would be even better if it actually morphed to use zio). If I was choosing today, I'd probably give slinky a strong consideration, at least at first reading it seems a bit easier to use. Alternatives: https://github.com/shadaj/slinky

scalablytyped (https://github.com/oyvindberg/ScalablyTyped)

An amazing project (that I've participated in, so I'm biased) that takes every typescript project from http://definitelytyped.org/ and creates scala bindings for it. For React projects you can choose slinky or scalajs-react flavors. Also, coming soon, an sbt plugin that lets you chose exactly what javascript libraries you want to wrap.

semantic ui (https://react.semantic-ui.com/)

I really like how the set of react components from the semantic library look and feel, it's very themable as well. Alternatives: https://material-ui.com/, https://react-bootstrap.github.io/, http://nikgraf.github.io/belle/#/?_k=dyoot9

MySQL

I use mySQL mostly because I'm more familiar with it, switching the app to use something else should not be too difficult Alternatives: mariadb, postgress, oracle, sql server, etc... or if you want to go nosql: cassandra, mongoDB

How the app is put together

Configuring, compiling and running the app

Database

You'll need to have mysql running. To initialize the database, just run the scripts in the server/src/main/sql directory in order. Once you do that, you should configure the access to the database in server/src/main/resources/application.conf, change the database url, username and password as needed

Shared code (model subproject)

The common subproject gets compiled in both jvm and js flavors, since I want to be able to share it between subprojects of both types

Server (api subproject)

In general a few parameters in server/src/main/resources/application.conf will control the application, tell it what port to run on, where to find the static web pages (the staticContentDir variable), etc. Once all is configured, in sbt, you should be able to run:

  ~server/reStart

This will start the server, any changes you make will automatically be recompiled and the server restarted.

Web client (client subproject)

You need to compile all of the scala.js code into a nicely packaged js file. There's a dist command that will generate your distribution directory

Utilities (util subproject)

currently empty

Generated scalablyTyped code (full-zio-stack-stLib subproject)

The code in this subproject is automatically generated by the scalablyTyped plugin and contains all the facades for the typescript libraries.

Here's how to do some common tasks

Note that I've put a bunch of "//TODO"s throughout the code that in places where I think you can expand or put additional stuff.

Adding a new web page

For the most part, I follow the architecture laid out by scalajs-react, the documentation there is pretty awesome.

Adding a new model object

• Add the model object itself in model/shared/src/main/scala/model typically these objects are scala case classes
• TODO what're the requirements to get CRUD for each object?

Adding a new javascript library

Assuming you are using ScalablyTyped, you need to add to build.sbt the typings for the javascript library (read the ScalablyTyped documentation ), as well as adding the library itself to the bundler (the npmDependencies section). If the library is a react library, you should choose a flavor of react bindings (currently either japgolly or Slinky bindings). Once you do that you should be good to go!

Testing

Most of this project is boilerplate, so by definition there's not much to test. The question is always "what to test?". Business logic of course. In this architecture business logic resides in the following places:

• The server's Service classes. I suggest you keep your routes simple and create either methods within those classes or separate business class logic. I'll write a couple of tests to show how to test the routes
• The database specific Repository... because we're not using a full ORM library, a lot of the mapping from Relational to OO happens in the DAO, it's a good idea to test these. these are considered integration tests and are in the server/src/it path
• The web application itself, I personally find it very hard to write unit tests against user interface, you should read:
  • https://www.scala-js.org/libraries/testing.html
  • https://github.com/japgolly/scalajs-react/blob/master/doc/TESTING.md

Production

Creating production artifacts is a bit beyond the scope of this project (it's meant to get you started, not to get you finished); however I do use sbt-native-packager to create a debian package of the server portion. I'd like to integrate that to create a full package that also includes the web application.

Acknowledgements

• This blog post uses a stack that's very similar to the one described here, I borrowed from it extensively, mostly in it's use of zio.
• Oyvindberg has been super, super helpful with not only the ScalablyTyped project but with looking over my shoulder as I make mistakes.
• All the people from all the projects above that work to make the scala culture so amazing!