working-with-config
Skill325 starsChanged 7 days agoApache-2.0View on GitHub
Quarkus configuration conventions: @ConfigMapping interfaces, config phases, and migration from legacy @ConfigRoot classes.
1 other project uses a version of this; 1 new project in the last 4 weeks, against 0 the 4 before.
Adopted by
Surging: 1 new project took it in the last 4 weeks, none the 4 weeks before.thin data
Most recently taken up by
- quarkusio/quarkusword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- quarkusio/quarkus★ 16k100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- coding-styleSkill
- pull-requestsSkill
- writing-build-stepsSkill
- writing-testsSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Never use Optional and provide a default via .orElse(...) in application code.
- Distinctive: line 52
Use this when mapping a sub-tree of configuration that does not represent an extension's top-level config root.
- Very specific: line 83
Use for settings that affect code generation.
- Distinctive: line 97
Before you add a key, read the keys next to it and use the same form.
- Very specific: line 101
Use a -mode suffix only when the key copies a term of an external system, such as the OIDC response_mode.
- Distinctive: line 103
When the key maps to a term of a tool that users know, such as Docker or Hibernate ORM, use that term and that default value.
- Very specific: line 143
Always specify phase explicitly on @ConfigRoot — the default is BUILD_TIME, which is not injectable via CDI at runtime
- Very specific: line 146
Use RUN_TIME phase unless the config genuinely affects build-time behavior
- Very specific: line 147
Do NOT access RUN_TIME config during build steps — it is not available yet
- Distinctive: line 149
When the code cannot apply a configured value, fail at startup with a message that names the property, or log one warning.
- Very specific: line 153
When adding new quarkus.* properties, always register them in a @ConfigMapping interface.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working with Configuration
Use @ConfigMapping Interfaces (Not Legacy Classes)
Quarkus configuration must use @ConfigMapping interfaces. The legacy
@ConfigRoot-annotated classes with @ConfigItem have been fully removed
(see adr/0008-phasing-out-config-classes.adoc).
Correct (current approach)
@ConfigMapping(prefix = "quarkus.my-extension")
@ConfigRoot(phase = ConfigPhase.RUN_TIME)
public interface MyExtensionRuntimeConfig {
/** Description of the property. */
@WithDefault("default-value")
String myProperty();
/** Optional property (absent means not set by the user). */
Optional<String> optionalProperty();
}Do NOT Use Optional to Define Default Values
Never use Optional and provide a default via .orElse(...) in application
code. The default must be declared in the config mapping itself via
@WithDefault:
// BAD — do not do this
String name = config.optName().orElse("theDefaultName");
// GOOD — declare the default in the config mapping
@WithDefault("theDefaultName")
String name();Non-root @ConfigMapping (without @ConfigRoot)
@ConfigMapping can also be used without @ConfigRoot for non-root
mappings. These are not auto-discovered — you must register them explicitly
(e.g., via @Inject in a CDI bean or programmatically with SmallRye Config).
Use this when mapping a sub-tree of configuration that does not represent an
extension's top-level config root.
@ConfigMapping(prefix = "some.custom.prefix")
public interface MyCustomConfig {
/** A non-root config property. */
String someValue();
}Wrong (legacy approach, do not use)
// DO NOT use this pattern
@ConfigRoot(name = "my-extension", phase = ConfigPhase.RUN_TIME)
public class MyExtensionConfig {
@ConfigItem(defaultValue = "default-value")
String myProperty;
}Config Phases
@ConfigRoot defaults to BUILD_TIME when no phase is specified. Always set
the phase explicitly — omitting it for a config injected at runtime will cause
UnsatisfiedResolutionException because BUILD_TIME configs are not registered
as CDI beans.
BUILD_TIME— Baked into the binary at build time, immutable at runtime. Use for settings that affect code generation. Only available in@BuildStepmethods — not injectable via@Injectin runtime CDI beans.BUILD_AND_RUN_TIME_FIXED— Read at build time, also available at runtime. Cannot change without rebuilding. Available in both@BuildStepmethods and runtime CDI beans.RUN_TIME— Read at application startup. Can change between runs. Available in runtime CDI beans via@Inject. Not available in@BuildStepmethods.
Naming
- Config interfaces:
<Feature>Config.java, or split as<Feature>BuildTimeConfig.java/<Feature>RuntimeConfig.java - Config prefix:
quarkus.<extension-name> - Before you add a key, read the keys next to it and use the same form.
- Name the thing that the key configures, in full words:
index-directories, notdir-mode. An enum value carries the action:quarkus.http.insecure-requests=enabled|redirect|disabled. - Use a
-modesuffix only when the key copies a term of an external system, such as the OIDCresponse_mode. - When the key maps to a term of a tool that users know, such as Docker or Hibernate ORM, use that term and that default value.
- The method name gives the key:
indexDirectories()becomesindex-directories. A rename changes the method, the docs and the tests.
Annotation Processor (quarkus-extension-processor)
The quarkus-extension-processor annotation processor is required for all
extension modules, not just those with @ConfigRoot. It generates metadata
files (including META-INF/quarkus-config-roots.list for config discovery)
that Quarkus needs to wire extensions correctly. Without it, most extension
functionality will silently fail.
Both runtime/ and deployment/ POMs must include:
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<executions>
<execution>
<id>default-compile</id>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-extension-processor</artifactId>
<version>${project.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</execution>
</executions>
</plugin>Most modules already have this. If you create a new module or notice missing
metadata, verify the annotation processor is present in its pom.xml.
Key Rules
- Always specify
phaseexplicitly on@ConfigRoot— the default isBUILD_TIME, which is not injectable via CDI at runtime - Configuration is immutable — never mutate config objects
- Use
RUN_TIMEphase unless the config genuinely affects build-time behavior - Do NOT access
RUN_TIMEconfig during build steps — it is not available yet BUILD_TIMEconfig changes require a rebuild- When the code cannot apply a configured value, fail at startup with a message that names the property, or log one warning. Never ignore the value without a message. Examples: a TLS option that the client does not support, a runtime value that a reload does not apply.
- When adding new
quarkus.*properties, always register them in a@ConfigMappinginterface. Reading them programmatically viaConfig.get().getOptionalValue(...)is fine, but the corresponding key must still be defined in a@ConfigMapping— otherwise SmallRye Config will emit "unknown property" warnings at startup.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

