📚 Scala Library Template

A reusable template for Scala libraries deployed to Maven Central.

"Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." — Antoine de Saint-Exupéry.

📋 What's included?

1. Everything from Scala Library Config, including reasonable Scalafmt settings, CI piplines for build integrity, and some IDE config.
2. Automatic deployment to Maven Central using sbt-ci-release.
3. Example build configuration and setup instructions.

🔨 How to use this template

1. Create your repository

Click 'Use this template' on GitHub, and follow the instructions to create a new repository for your library. All files herein will be copied as-is.

2. Configure build.sbt and release.sbt

Replace every placeholder with real values for your project. The sbt settings necessary for publishing are defined by sbt-ci-release and are documented here.

Settings to update in release.sbt:

Name	Purpose	Example
organization	Your organisation's package namespace.	org.nohungrydogs
organizationName	Your organisation's name.	No Hungry Dogs
organizationHomepage	Your organisation's website.	nohungrydogs.org
versionScheme	What does the version number say about binary compatibility?	strict
licenses	The license under which your library is released. Update LICENSE.md to match.	MIT
developers	The individual developers who contribute to your library.	SgtSwagrid

Settings to update in build.sbt:

Name	Purpose	Example
packagePrefix	IntelliJ's implicit package prefix for all code files.	org.nohungrydogs
Name of subproject (following lazy val)	Your library's name, or the name of a particular module.	dog-food-finder

Multiple modules

Each subproject listed in build.sbt is published as a separate artefact on Maven (albeit under the same versioning), which is useful if you want a modular design whereby downstream users need not include all facets of your library. Typically in this case you'll introduce one top-level subdirectory for each subproject.

A note on sbt settings

Settings are read from every .sbt file in the project root. It doesn't matter what they are called, other than that sbt simply concatenates their contents in alphabetical order of their names. A division between build information and publishing information is introduced for convenience.

3. Set up your Maven Central account

1. Create an account on Maven Central to enable publishing, if you don't already have one.
2. Register your namespace (e.g. org.nohungrydogs). This should match the organization setting in release.sbt.
3. Generate a user token. This will give you a username and password, which you can add as repository secrets (see step 5).

4. Generate a PGP key for signing releases

Execute the following on your local machine to generate a PGP key:

# Generate a new PGP key, making sure to remember your passphrase:
gpg --gen-key

# Expose the secret key in base64, using the public key provided by the above:
gpg --armor --export-secret-keys <PUBLIC_KEY> | base64

# Upload the public key to a keyserver:
gpg --keyserver keyserver.ubuntu.com --send-keys <PUBLIC_KEY>

5. Add repository secrets

Add the following secrets to your repository on GitHub, to allow publishing as part of an automated workflow:

Secret	Value
SONATYPE_USERNAME	Username from Maven user token in step 3.
SONATYPE_PASSWORD	Password from Maven user token in step 3.
PGP_SECRET	Base64-encoded PGP private key from step 4.
PGP_PASSPHRASE	Passphrase used when generating the PGP key in step 4.
GH_TOKEN	Your GitHub PAT with administrator to access your repository.
CLAUDE_CODE_OAUTH_TOKEN	API key from Claude for agentic workflows (optional).

Secrets can be added from the GitHub web interface by nagivating as follows from your repository's page:

Settings → Secrets and variables → Actions

6. Publish the Scaladoc documentation with Github Pages

This project is configured to automatically extract and publish all Scaladoc content as a stand-alone website using GitHub Pages.

All you need to do is configure GitHub to deploy the site from the branch named gh-pages, which will be automatically created following the first release. You can find this setting under:

Settings → Pages

👮‍♂️ License

The included MIT license should be considered only as part of the template, and is not binding. This repository is hereby released to the public domain, to be used freely. In particular, and contra LICENSE.md, you may remove the license text from copies.

🤝 Contributing

CONTRIBUTING.md is also part of the template, and does not necessarily apply to contributions to the template itself. The most important thing to know is that many of the configuration files are automatically synced from Scala Config, and should be updated there rather than here.

👁️ See also

• Check out Scala Website Template for a similar template to quickly start a new full stack website in Scala.
• This project is configured by Scala Library Config.

⬆️ Delete • Keep ⬇️

✨ My Library

A very cool Scala library that does something great.

⬇️ Installation

Add the following dependency to your build.sbt:

libraryDependencies += "com.alecdorrington" %% "scala-library-template" % "0.2.1"

👁️ See also

• This library was made using Scala Library Template.