Full Scala Stack
This is an example project that uses a full scala stack, server to client. 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.
I chose http-akka because it's stable, fast, well maintained and actively developed and full featured. I've also been using it since
it was called spray, so there's the historical reason. If I was choosing from scratch today, I would likely not use play
(it's too heavy, I think) and may use some lighter library instead, I'm curious as to where zio-http goes.
My main 2 complaints about http-akka are related: it's not easy to reverse engineer documentation from the routes (as in swagger) and
the routes are not typed (so if you accidentally change the type returned from a complete you can mess up your client)
Alternatives: https://www.playframework.com/, https://http4s.org/, https://github.com/softwaremill/sttp, https://github.com/zio/zio-http
I chose slick because I like it's almost ORM way to do tables, it's main disadvantage is that it's not very functional (in the academic sense), but it is fairly mature and I've been able to write complex CRUD code with it. Alternatives: https://github.com/tpolecat/doobie, https://getquill.io/, http://scalikejdbc.org/
Zio says: Type-safe, composable asynchronous and concurrent programming for Scala. For many reasons it's an excellent replacement for native scala futures, it's easy enough to understand. I have had to write a few bridges to be able to use zio with the rest of my stack, particularly akka-http and slick. Alternatives: Futures, scalaz, cats
Courier is not very well maintained, but there really isn't very much I require of a mail sender library. I did write a zio wrapper as part of this project to talk to courier. I would probably look at zio-email if I was choosing today, there might be other more full-featured mail libraries available. Alternatives: https://github.com/funcit/zio-email
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.
There's way too many json libraries for scala, I had used spray for a long time, but it's not heavily maintained anymore, so I started using upickle. I'd probably give circe a good look, particularly if you're more into pure functional programming Alternatives: https://circe.github.io/circe/, https://www.playframework.com/documentation/2.7.x/ScalaJson, https://github.com/spray/spray-json
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
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
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
You'll need to have mysql running, if you want to try it first without a database, you can always replace the
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
The common subproject gets compiled in both jvm and js flavors, this is where I typically put my model, since I want to be able to share it between subprojects of both types
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:
This will start the server, any changes you make will automatically be recompiled and the server restarted.
You need to compile all of the scala.js code into a nicely packaged js file. There's a
dist command and a
debugDist command, the first one
does full optimization, but it's resulting file will be both harder to read and it will take longer to generate, use the second one for development.
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
common/shared/src/main/scala/modeltypically these objects are scala case classes
- Add the database creation code for your object (I like to put these as sql scripts in
server/src/main/sql), run it against your database
- Use util.CodeGen to re-generate Tables.scala which will contain the stuff that maps your SQL database with our model.
- Add the CRUD (and other) database operations to
src/main/scala/dao/Repository, you'll have to create "live" and "mock" versions of all the methods you create. For every object you'll probably want to declare a CRUDOperations entry.
- Add a service that does basic REST crud operations about your object in
server/src/main/scala/routes, look at
SampleModelObjectRouteas an example
- In the web, you'll need a REST client that can talk to your server, declare one in
- Add the web pages you need to do stuff with your new object (see above).
Assuming you are using ScalablyTyped, you need to add to
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!
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 Slick is not 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:
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.
- 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!