Fullstack Scala application with Smithy4s

This is a full-stack Scala application (simple key-value management store), made with the following excellent libraries and technologies:

1. Scala 3
2. Smithy4s and Smithy for the API and protocol definition between backend and frontend (and in tests)
3. Scala.js and Laminar for the SPA frontend
4. PostgreSQL and Skunk for database access
5. Weaver-Test for unit and integration testing
6. Playwright tests for frontend testing, using the dedicated Weaver integration

The entire app is auto-deployed to Fly.io, you can see the live version here. This has moved to my own cluster, live version here. Fly.io specific code left in the repository, but the app won't be deployed there anymore.

It started out as a trimmed down version of an app I've built in my 4-part blogpost series about full-stack Scala and Smithy4s. The blog series should answer a lot of the design questions you might have in much greater detail than the margins of this tome allow.

What is it for?

Starting a full stack application with Smithy4s is by far not the most lightweight approach, but if you are comfortable with some of the technologies involved, this puts your project immediately on a more solid footing than if you started small and re-wrote later (such rewrites tend to rarely happen, instead cruft is being added on and accumulated).

By using Smithy as the contract between frontend and backend, we immediately turn backend into a solid API, and ensure that the interaction between the two never goes out of sync.

This template incorporates some of the lessons I've learned after deploying several personal full stack applications:

1. Frontend is deployed separately from the backend, with NGINX serving both
2. We use smithy4s-fetch to significantly reduce bundle size on the frontend
3. The Dockerfile is multi-stage and self-contained, producing a working application just by running docker build . -t smithy4s-fullstack

The current choices of the libraries on the backend is deliberate, it makes it possible to soon run the backend on Scala Native.

Running

While most of the defaults are already configured, the only missing bit is the Postgres communication. It can be picked up from the environment, but best way to do it would be to put a file named .env at the root of the project with a JDBC-compatible Postgres URL:

DATABASE_URL=postgres://postgres:mysecretpassword@localhost:5432/postgres

1. To run just the backend, run ~app/reStart in SBT shell, it will continuously restart the backend on any changes

2. To run the frontend development server, go to ./modules/frontend and run npm run dev there. In a separate SBT shell run ~frontend/fastLinkJS to continuously rebuild the frontend. Go to http://localhost:5173 (or whatever port Vite chooses) to see the full app running

Features

• Database

  • uses Skunk for database access and Dumbo to apply migrations

• Deployment

  • sbt-native-packager to bundle a JVM app into something runnable

  • Vite and NPM package the Scala.js frontend

  • NGINX is used to serve both the static assets and the backend API

• Testing

  • stub tests that use in-memory database implementation and don't exercise the network or SQL queries

  • integration tests that start a PostgreSQL container using Testcontainers, migrate a fresh copy of the database, start the actual HTTP server and run the tests through that

  • frontend tests that use Playwright to launch the browser and execute some basic tests to make sure the frontend works correctly