{"id":14069345,"url":"https://github.com/pureconfig/pureconfig","last_synced_at":"2025-05-13T22:07:00.098Z","repository":{"id":2472650,"uuid":"41600790","full_name":"pureconfig/pureconfig","owner":"pureconfig","description":"A boilerplate-free library for loading configuration files","archived":false,"fork":false,"pushed_at":"2025-04-30T18:37:51.000Z","size":5730,"stargazers_count":1506,"open_issues_count":50,"forks_count":179,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-05-07T23:00:23.878Z","etag":null,"topics":["configuration","hacktoberfest","pureconfig","scala","scala-library","shapeless"],"latest_commit_sha":null,"homepage":"https://pureconfig.github.io","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pureconfig.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-08-29T17:05:50.000Z","updated_at":"2025-04-30T18:37:55.000Z","dependencies_parsed_at":"2024-01-22T22:03:16.087Z","dependency_job_id":"7dc6cfc6-3f58-4192-9842-d5fc0cc111e1","html_url":"https://github.com/pureconfig/pureconfig","commit_stats":{"total_commits":1834,"total_committers":92,"mean_commits":"19.934782608695652","dds":0.6014176663031625,"last_synced_commit":"79b3664c0f9880f880b068ec7875da63df09099f"},"previous_names":["melrief/pureconfig"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pureconfig%2Fpureconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pureconfig%2Fpureconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pureconfig%2Fpureconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pureconfig%2Fpureconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pureconfig","download_url":"https://codeload.github.com/pureconfig/pureconfig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036821,"owners_count":22003654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration","hacktoberfest","pureconfig","scala","scala-library","shapeless"],"created_at":"2024-08-13T07:06:52.776Z","updated_at":"2025-05-13T22:06:55.083Z","avatar_url":"https://github.com/pureconfig.png","language":"Scala","funding_links":[],"categories":["Scala","Table of Contents","Misc"],"sub_categories":["Misc"],"readme":"# PureConfig\n\n\u003cimg src=\"docs/src/main/resources/microsite/img/pureconfig-logo-1040x1200.png\" width=\"130px\" height=\"150px\" align=\"right\"\u003e\n\n[![Build Status](https://github.com/pureconfig/pureconfig/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/pureconfig/pureconfig/actions?query=workflow%3ACI+branch%3Amaster)\n[![Coverage Status](https://coveralls.io/repos/github/pureconfig/pureconfig/badge.svg?branch=master)](https://coveralls.io/github/pureconfig/pureconfig?branch=master)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.pureconfig/pureconfig_2.13/badge.svg)](https://search.maven.org/artifact/com.github.pureconfig/pureconfig_2.13)\n[![Scaladoc](https://javadoc.io/badge/com.github.pureconfig/pureconfig-core_2.13.svg)](https://javadoc.io/page/com.github.pureconfig/pureconfig-core_2.13/latest/pureconfig/index.html)\n[![Join the chat at https://gitter.im/melrief/pureconfig](https://badges.gitter.im/melrief/pureconfig.svg)](https://gitter.im/melrief/pureconfig?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nPureConfig is a Scala library for loading configuration files. It reads [Typesafe Config](https://github.com/lightbend/config) configurations written in [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md#hocon-human-optimized-config-object-notation), Java `.properties`, or JSON to native Scala classes in a boilerplate-free way. Sealed traits, case classes, collections, optional values, and many other [types are all supported out-of-the-box](https://pureconfig.github.io/docs/built-in-supported-types.html). Users also have many ways to [add support for custom types](https://pureconfig.github.io/docs/supporting-new-types.html) or [customize existing ones](https://pureconfig.github.io/docs/overriding-behavior-for-types.html).\n\n\u003cbr clear=\"right\"\u003e \u003c!-- Turn off the wrapping for the logo image. --\u003e\n\n\n## Why\n\nLoading configurations has always been a tedious and error-prone procedure. A common way to do it\nconsists in writing code to deserialize each fields of the configuration. The more fields there are,\nthe more code must be written (and tested and maintained...) and this must be replicated for each project.\n\nThis kind of code is boilerplate because most of the times the code can be automatically generated by\nthe compiler based on what must be loaded. For instance, if you are going to load an `Int` for a field\nnamed `foo`, then probably you want some code that gets the values associated with the key `foo` in\nthe configuration and assigns it to the proper field after converting it to `Int`.\n\nThe goal of this library is to create at compile-time the boilerplate necessary to load a configuration of a\ncertain type. In other words, you define **what** to load and PureConfig provides **how** to load it.\n\n\n## Quick Start\n\nTo use PureConfig in an existing SBT project with Scala 2.13 or a later version, add the following dependency to your\n`build.sbt`:\n\n```scala\nlibraryDependencies += \"com.github.pureconfig\" %% \"pureconfig\" % \"0.17.9\"\n```\n\nFor Scala 3, add the following dependency to your `build.sbt`:\n\n```scala\nlibraryDependencies += \"com.github.pureconfig\" %% \"pureconfig-core\" % \"0.17.9\"\n```\n\nWhile 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](https://pureconfig.github.io/docs/scala-3-derivation.html).\n\nFor a full example of `build.sbt` you can have a look at this [build.sbt](https://github.com/pureconfig/pureconfig/blob/master/example/build.sbt).\n\nEarlier versions of Scala had bugs which can cause subtle compile-time problems in PureConfig.\nAs a result we recommend only using the latest Scala versions within the minor series.\n\nIn your code, import `pureconfig.generic.auto` and define data types and a case class to hold the configuration:\n\n```scala\nimport pureconfig._\nimport pureconfig.generic.auto._\n\ncase class Port(number: Int) extends AnyVal\n\nsealed trait AuthMethod\ncase class Login(username: String, password: String) extends AuthMethod\ncase class Token(token: String) extends AuthMethod\ncase class PrivateKey(pkFile: java.io.File) extends AuthMethod\n\ncase class ServiceConf(\n  host: String,\n  port: Port,\n  useHttps: Boolean,\n  authMethods: List[AuthMethod]\n)\n```\n\nSecond, create an `application.conf` file and add it as a resource of your application (with SBT, they are usually\nplaced in `src/main/resources`):\n\n```\n// src/main/resources/application.conf\nhost = \"example.com\"\nport = 8080\nuse-https = true\nauth-methods = [\n  { type = \"private-key\", pk-file = \"/home/user/myauthkey\" },\n  { type = \"login\", username = \"pureconfig\", password = \"12345678\" }\n]\n```\n\nFinally, load the configuration:\n\n```scala\nConfigSource.default.load[ServiceConf]\n// res4: ConfigReader.Result[ServiceConf] = Right(\n//   ServiceConf(\n//     \"example.com\",\n//     Port(8080),\n//     true,\n//     List(PrivateKey(/home/user/myauthkey), Login(\"pureconfig\", \"12345678\"))\n//   )\n// )\n```\n\n`ConfigReader.Result[ServiceConf]` is just an alias for `Either[ConfigReaderFailures, ServiceConf]`, so you can handle\nit just like you would handle an `Either` value.\n\nThe various `loadConfig` methods defer to Typesafe Config's\n[`ConfigFactory`](https://lightbend.github.io/config/latest/api/com/typesafe/config/ConfigFactory.html) to\nselect where to load the config files from. Typesafe Config has [well-documented rules for configuration\nloading](https://github.com/lightbend/config#standard-behavior) which we'll not repeat. Please see Typesafe\nConfig's documentation for a full telling of the subtleties.\n\nAlternatively, PureConfig also provides a `loadConfigFromFiles` method that builds a configuration from\nan explicit list of files. Files earlier in the list have greater precedence than later ones. Each file can\ninclude a partial configuration as long as the whole list produces a complete configuration. For an example,\nsee the test of `loadConfigFromFiles` in\n[`ApiSuite.scala`](https://github.com/pureconfig/pureconfig/blob/master/tests/src/test/scala/pureconfig/ApiSuite.scala).\n\nBecause PureConfig uses Typesafe Config to load configurations, it supports reading files in [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md#hocon-human-optimized-config-object-notation), JSON, and Java `.properties` formats. HOCON is a superset of both JSON and `.properties` that is highly recommended. As an added bonus it supports [advanced features](https://github.com/lightbend/config/blob/master/README.md#features-of-hocon) like variable substitution and file sourcing.\n\n\n## Documentation\n\nPlease see the [full PureConfig documentation](https://pureconfig.github.io/docs) for more information.\n\n\n## Contribute\n\nPureConfig is a free library developed by several people around the world.\nContributions are welcomed and encouraged. If you want to contribute, we suggest to have a look at the\n[available issues](https://github.com/pureconfig/pureconfig/issues) and to talk with\nus on the [PureConfig Gitter channel](https://gitter.im/melrief/pureconfig?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge).\n\nIf you'd like to add support for types which are not part of the standard Java or Scala libraries, please consider submitting a pull request to create a [module](https://pureconfig.github.io/docs/library-integrations.html). [Pull Request #108](https://github.com/pureconfig/pureconfig/pull/108/files) created a very simple module. It should provide a good template for the pieces you'll need to add.\n\nThe steps to create a new module, called _`nexttopmod`_, are:\n\n1. Define a new project in the root `build.sbt`. There are other examples near the top of the file;\n2. Create a new  `modules/nexttopmod/` subdirectory;\n3. Add a `modules/nexttopmod/build.sbt` defining the module's name and special dependencies;\n4. Implement converters. Typically they're in a `package object` in `modules/nexttopmod/src/main/scala/pureconfig/module/nexttopmod/package.scala`;\n5. Test the converters. Usually tests would be in `modules/nexttopmod/src/test/scala/pureconfig/module/nexttopmod/NextTopModSuite.scala`;\n6. Optionally explain a little bit about how it works in `modules/nexttopmod/README.md`.\n\nPureConfig supports the [Typelevel](http://typelevel.org) [code of conduct](http://typelevel.org/conduct.html) and wants all of its channels (Gitter, GitHub, etc.) to be\nwelcoming environments for everyone.\n\n\n## License\n\n[Mozilla Public License, version 2.0](LICENSE)\n\n\n## Special Thanks\n\nTo the [Shapeless](https://github.com/milessabin/shapeless) and to the [Typesafe Config](https://github.com/lightbend/config)\ndevelopers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpureconfig%2Fpureconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpureconfig%2Fpureconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpureconfig%2Fpureconfig/lists"}