Quick Start

To use PureConfig in an existing SBT project with Scala 2.12 or a later version, add the following dependency to your build.sbt:

libraryDependencies += "com.github.pureconfig" %% "pureconfig" % "0.17.8"

For a full example of build.sbt you can have a look at this build.sbt.

Users of Scala 3 need to add the following dependency to their build.sbt:

libraryDependencies += "com.github.pureconfig" %% "pureconfig-core" % "0.17.8"

While a lot of the documentation will also apply to Scala 3, there is a specific guide for Scala 3’s derivation that you can find here.

Earlier versions of Scala had bugs which can cause subtle compile-time problems in PureConfig. As a result we recommend only using the latest Scala versions within the minor series.

In your code, import pureconfig.generic.auto and define data types and a case class to hold the configuration:

import pureconfig._
import pureconfig.generic.auto._

case class Port(number: Int) extends AnyVal

sealed trait AuthMethod
case class Login(username: String, password: String) extends AuthMethod
case class Token(token: String) extends AuthMethod
case class PrivateKey(pkFile: java.io.File) extends AuthMethod

case class ServiceConf(
  host: String,
  port: Port,
  useHttps: Boolean,
  authMethods: List[AuthMethod]
)

Second, create an application.conf file and add it as a resource of your application (with SBT, they are usually placed in src/main/resources):

// src/main/resources/application.conf
host = "example.com"
port = 8080
use-https = true
auth-methods = [
  { type = "private-key", pk-file = "/home/user/myauthkey" },
  { type = "login", username = "pureconfig", password = "12345678" }
]

Note the usage of different naming conventions for config keys and class fields, which you can customize later.

Finally, load the configuration:

ConfigSource.default.load[ServiceConf]
// res4: ConfigReader.Result[ServiceConf] = Right(
//   ServiceConf(
//     "example.com",
//     Port(8080),
//     true,
//     List(PrivateKey(/home/user/myauthkey), Login("pureconfig", "12345678"))
//   )
// )

ConfigReader.Result[ServiceConf] is just an alias for Either[ConfigReaderFailures, ServiceConf], so you can handle it just like you would handle an Either value.

ConfigSource.default defers to Typesafe Config’s ConfigFactory to select where to load the config files from. Typesafe Config has well-documented rules for configuration loading which we’ll not repeat. Please see Typesafe Config’s documentation for a full telling of the subtleties and see Loading a Config for alternative sources for configuration files.

Because PureConfig uses Typesafe Config to load configurations, it supports reading files in HOCON, JSON, and Java .properties formats. HOCON is a delightful superset of both JSON and .properties that is highly recommended. As an added bonus it supports advanced features like variable substitution and file sourcing.