Module Naming Strategy for Core Extensions vs. Independent Projects (JPMS)

[cescoffier]

During the Community Call on Jan 20, 2026, we discussed the ongoing effort to modularize Quarkus to support the Java Platform Module System (JPMS). As @dmlloyd is working through the core extensions, we have hit a conflict between our Extension Structure ADR and "Independent Projects" that live within the Quarkus repository (specifically Arc and Qute).

We need to decide on a naming strategy that satisfies javac constraints (you cannot have 2 modules with the same name) while keeping our ecosystem logical.

The Problem

The current ADR suggests that extension runtime modules should follow the naming convention io.quarkus.<name>.

However, we have internal projects like Arc that:

• Are independent libraries (usable outside Quarkus).
• Already own the API namespace io.quarkus.arc.
• Have a corresponding Quarkus Extension wrapper, which, if we follow the ADR, would have the same name.

Under JPMS, javac strictly forbids two different artifacts on the module path from claiming the same module name. We cannot have the Arc Library (io.quarkus.arc) and the Arc Extension Runtime (io.quarkus.arc) coexist if they are separate modules.

Currently, we are working around this by naming the extension module io.quarkus.arc.runtime. However, this results in a module name that does not match the package name (which remains io.quarkus.arc to avoid breaking changes), which is generally considered a bad practice in the JPMS world.

Proposed Solutions

We discussed a few paths forward and would like community feedback:

1. The "Shading" Approach (Suggested by @Sanne ) We could merge the independent library and the extension runtime into a single artifact at build time (shading).

• Pros: The user sees a single module: io.quarkus.arc. No naming conflict.
• Cons: Increases build complexity. Makes it harder (or different) for users who want to use Arc/Qute outside of Quarkus (they would need to depend on the shaded jar, or we continue publishing the standalone lib for non-Quarkus use).

2. The "Prefix" Approach (Suggested by @dmlloyd ) We could introduce a standard prefix for extension modules, such as io.quarkus.ext.<name> or io.quarkus.x.<name>.

• Pros: Clear separation between the "Core Library" and the "Quarkus Extension." Avoids conflicts across the broad io.quarkus namespace.
• Cons: We would likely have module names that do not match package names (unless we move packages, which is a breaking change).

3. Status Quo / Specific Exceptions We accept that for these specific projects (Arc, Qute), the extension module is named io.quarkus.arc.runtime, despite the package name mismatch, or change the name of the independent project (io.quarkus.arc.lib or io.quarkus.arc.main or io.quarkus.lib.arc)

Questions

• How important is it that we maintain the ability to use Arc/Qute as standalone libraries separate from the Quarkus extension mechanism?

• Is the mismatch between Module Name (...runtime) and Package Name (io.quarkus.arc) acceptable in this context? It's just a few exceptions.

• Should we revisit the Extension Structure ADR to mandate a prefix (ext) for all extensions to prevent namespace pollution?

Check the meeting notes for the full context of the discussion.

\CC: @dmlloyd @Sanne @mkouba

[cescoffier]

@dmlloyd @Sanne No opinion?

[dmlloyd]

Oh, I have plenty of opinions. :-)

I think that even if we decide that ArC can never be useful outside of Quarkus (which I do not agree with), I think we can't assume that the io.quarkus.<name> namespace is fully available for extension use. Quarkus is too large of a system for this, and the possibilities of conflict will only increase over time. By partitioning extensions into a sub-namespace of io.quarkus.ext.<name>, we remove the possibility of conflict between extensions and other non-extension components. So, as a long-term solution, I think we should add .ext. in that location to the ADR for module and package names, and deal with the discrepancy of existing extensions gradually over time.

And look, if we renamed deployment to build at the same time, I wouldn't be mad. 😉

I think that any mismatch of module and package is acceptable for existing code. We can fix this opportunistically over time. For new subprojects and extensions, we absolutely should be strict about proper namespacing including matching package name and module name, which in turn should align with group ID and artifact ID in a sensible way.

[dmlloyd]

We might even want to establish the concept of a namespace registry for io.quarkus.<xxx> sub namespaces. Then package/module names can be "claimed" by subsystems and conflicts and split package situations can be avoided.

[mkouba]

By partitioning extensions into a sub-namespace of io.quarkus.ext.<name>, we remove the possibility of conflict between extensions and other non-extension components. So, as a long-term solution, I think we should add .ext. in that location to the ADR for module and package names, and deal with the discrepancy of existing extensions gradually over time.

I agree that io.quarkus.ext.<name> would be intelligible.

And look, if we renamed deployment to build at the same time, I wouldn't be mad. 😉

💯