How to override configuration with environment variables in Lightbend Config?

Use substitutions like ${?ENV_VAR} in HOCON files for optional overrides, or set -Dconfig.override_with_env_vars=true to allow any environment variable starting with CONFIG_FORCE_ to override values. The README details the syntax and name mangling rules.

Lightbend Config vs Spring Boot configuration: which should I use?

Lightbend Config is library-agnostic with HOCON focus and immutable APIs, ideal for non-Spring JVM projects. Spring Boot's configuration integrates tightly with Spring ecosystem and supports YAML/profiles. Choose Lightbend for its HOCON features and thread safety, or Spring if you're already using Spring.

How to handle optional settings without throwing exceptions?

Use Config.hasPath() to check existence, or the ${?path} syntax in HOCON for optional substitutions. The README warns against using ConfigException.Missing for control flow due to performance and recommends defining defaults in reference.conf.

What is HOCON and why is it better than JSON for config?

HOCON is a human-friendly JSON superset that adds comments, includes, substitutions, and lenient syntax. It's designed for readability and maintenance, while still parsing to standard JSON, making it easier to write and manage complex configurations.

How to debug why my config values aren't loading?

Set -Dconfig.trace=loads to log file loads, or use config.root().render() to see a resolved config with origins. The README also mentions checking classloader issues if loading from non-main threads.

Can I use Lightbend Config with Kotlin or Scala?

Yes, it's a Java library with no dependencies, so it works directly. There are also wrappers like config4k for Kotlin and Ficus for Scala listed in the README for enhanced language-specific integration.

config — JVM HOCON Configuration Library

What is config?

Lightbend Config is a configuration library for JVM languages that provides a unified way to manage application settings using HOCON, JSON, and properties files. It solves the problem of handling complex, multi-environment configurations by supporting merges, substitutions, and type-safe access. The library is designed to be immutable and thread-safe, making it suitable for modern JVM applications.

Target Audience

JVM developers building applications in Java, Scala, Kotlin, or other JVM languages who need robust, maintainable configuration management. It is especially useful for projects with multiple deployment environments or complex configuration hierarchies.

Value Proposition

Developers choose Lightbend Config for its human-friendly HOCON syntax, strong support for variable substitution and includes, and its immutable, thread-safe API. It is a mature, widely-adopted library that integrates seamlessly with system properties and environment variables, reducing boilerplate and configuration errors.

configuration library for JVM languages using HOCON files

Use Cases

Best For

Managing application settings across development, staging, and production environments
JVM projects that need to merge configuration from multiple files or formats
Applications requiring environment-specific overrides via system properties or environment variables
Teams wanting a type-safe, immutable configuration API to avoid runtime errors
Projects using HOCON files for human-readable configuration with comments and substitutions
Libraries that need to provide default configurations while allowing app-level overrides

Not Ideal For

Applications requiring real-time configuration updates without restarts, as the library is immutable and lacks built-in hot reloading.
Non-JVM projects, since it's specifically designed for Java Virtual Machine languages and doesn't support other platforms natively.
Teams heavily invested in YAML configuration ecosystems, as Lightbend Config does not support YAML out of the box and would require conversion or custom handling.
Simple command-line tools or microservices where a lightweight, zero-dependency config parser suffices, due to the library's comprehensive but heavier feature set and Java dependency.

Pros & Cons

Pros

Human-Optimized HOCON Syntax

Uses a JSON superset with comments, includes, and substitutions, making configuration files more readable and maintainable than plain JSON or properties files, as detailed in the HOCON.md spec.

Immutable and Thread-Safe API

Based on immutable Config instances, ensuring safe concurrent access and predictable behavior in multi-threaded environments without synchronization overhead.

Flexible Configuration Loading

Supports loading from files, URLs, classpath resources, and system properties with automatic merging and priority-based overriding, simplifying multi-environment deployments.

Automatic Type Conversion

Converts values between strings, booleans, durations, and sizes (e.g., '10 seconds' or '512k'), reducing parsing boilerplate and potential errors as highlighted in the features list.

Cons

No Built-in Hot Reload

Configurations are immutable and loaded once; updating settings at runtime requires manual reloading with ConfigFactory.invalidateCaches() or custom code, which can be cumbersome for dynamic environments.

Complex Custom Source Integration

The library limits itself to config files, so loading from databases or other custom sources requires writing additional code, as admitted in the README's overview section.

Limited Schema Validation

Lacks a formal schema language; validation relies on manual checks using methods like checkValid() or external tools, which may not catch all errors early and increases boilerplate for complex configs.

Frequently Asked Questions

What is config?

Target Audience

Value Proposition

Use Cases

Best For

Managing application settings across development, staging, and production environments
JVM projects that need to merge configuration from multiple files or formats
Applications requiring environment-specific overrides via system properties or environment variables
Teams wanting a type-safe, immutable configuration API to avoid runtime errors
Projects using HOCON files for human-readable configuration with comments and substitutions
Libraries that need to provide default configurations while allowing app-level overrides

Not Ideal For

Applications requiring real-time configuration updates without restarts, as the library is immutable and lacks built-in hot reloading.
Non-JVM projects, since it's specifically designed for Java Virtual Machine languages and doesn't support other platforms natively.
Teams heavily invested in YAML configuration ecosystems, as Lightbend Config does not support YAML out of the box and would require conversion or custom handling.
Simple command-line tools or microservices where a lightweight, zero-dependency config parser suffices, due to the library's comprehensive but heavier feature set and Java dependency.

Pros & Cons

Pros

Human-Optimized HOCON Syntax

Uses a JSON superset with comments, includes, and substitutions, making configuration files more readable and maintainable than plain JSON or properties files, as detailed in the HOCON.md spec.

Immutable and Thread-Safe API

Based on immutable Config instances, ensuring safe concurrent access and predictable behavior in multi-threaded environments without synchronization overhead.

Flexible Configuration Loading

Supports loading from files, URLs, classpath resources, and system properties with automatic merging and priority-based overriding, simplifying multi-environment deployments.

Automatic Type Conversion

Converts values between strings, booleans, durations, and sizes (e.g., '10 seconds' or '512k'), reducing parsing boilerplate and potential errors as highlighted in the features list.

Cons

No Built-in Hot Reload

Complex Custom Source Integration

The library limits itself to config files, so loading from databases or other custom sources requires writing additional code, as admitted in the README's overview section.

Limited Schema Validation

Frequently Asked Questions

config

What is config?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

config

What is config?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?