scala3.ce3.g8

Unofficial opinionated Giter8 template for sbt-based scala 3 projects making usage of the typelevel stack. The template can be helpful for both web servers and CLIs.

Run

Using sbt

Assuming sbt is available, generate a new project using

sbt new [email protected]:alessandrocandolini/scala3.ce3.g8.git  --name=<project name>

or from a local clone of this repo

sbt new file:///<local-checkout-dir>/scala3.ce3.g8/  --name=<project name>

Using g8

On MAC OS X, Giter8 is available via the Homebrew package manager:

brew update
brew install giter8

For more options, refer to the original documentation http://www.foundweekends.org/giter8/setup.html

Once g8 is installed on the machine (see next section), it is also possible to generate a new project from a local clone of the repo

g8 file:///<local-checkout-dir>/scala3.ce3.g8/ --name=<project name>

See http://www.foundweekends.org/giter8/usage.html#Usage for more details

Description

The generated project includes the following dependencies:

• cats-core and cats-effects 3.x
• fs2 3.x for effectful, resource-safe streams
• tapir to describe HTTP endpoints as values and derive implementation of client, server etc; compatible with http4s and sttp, and many others
• decline for command-line argument parsing
• pureconfig-core to parse resources/application.conf configuration
• skunk for postgresql database access
• scalacheck for property-based testing, with scalacheck-effect to test effectful code

the following sbt-plugins:

• scalafmt configuration (via sbt-scalafmt sbt plugin)
• sbt-assembly plugin to generate "fat" jars (remove it if the goal is to build a library)

and will setup opinionated compiler options, eg, -language:strictEquality", -Yexplicit-nulls, -source:future, etc.

The generated project is setup to run unit and integration tests (with sbt test and sbt it:test respectively)

The generated project contains a simple .github/workflow/scala.yml configuration to setup github actions to run sbt assembly. It's a very basic setup, completely independent from the scala project. If you are not using github, just remove the .github folder. If you want a more advanced setup, you might be interested in exploring sbt-github-actions.

Todo

• the CI is relying on g8test, unfortunately this does not easily detect issues like An unexpected error occurred while processing the template. Check that all literal '$' are properly escaped with '\$' due to foundweekends/giter8#334
• scaffolding (to generate a cli or a server)
• improve github actions pipeline
• consider using make-g8

Giter8 crash course

• Giter8 generates a project that has exactly the same structure of the src/main/g8 folder
• template variables are defined in the default.properties file
• template variables can be accessed as $name of the variable$ (ie, between $) from everywhere
• $ is the reserved symbol, whenever you need to use a $ for purposes other than referring to a template variable be sure to escape it as \$; this is a typical source of errors

A more comprehensive guide here: http://www.foundweekends.org/giter8/Contents+in+Depth.html

Template license

Written in 2021 by Alessandro Candolini [email protected]

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this template to the public domain worldwide. This template is distributed without any warranty. See http://creativecommons.org/publicdomain/zero/1.0/.