RFC: Layer-aware Module Federation

[ScriptedAlchemy]

RFC: Layer-aware Module Federation

Summary

Make Module Federation 1.5 respect Rspack layers when sharing dependencies, exposing modules, and generating manifests. A shared package can have separate server and client variants without giving each variant an unrelated shared key.

Motivation

Layers already distinguish module builds, but federation must carry that distinction through resolution, runtime initialization, tree-shaking, and metadata. Losing it can select the wrong implementation or attribute exports and assets to the wrong variant.

ReactLynx use case

ReactLynx compiles the same component source differently for background and main-thread execution:

flowchart LR
  S["Component source"] --> B["Background layer"]
  S --> M["Main-thread layer"]
  B --> R["Paired Lynx remote bundle"]
  M --> R

Loading

Federation must preserve those variants throughout compilation and delivery:

• exposes.layer selects each compiled variant.
• shared.issuerLayer matches the importing layer; shared.layer selects its provider or fallback.
• Manifests retain each variant’s identity, requirements, and assets.

Realm-qualified share scopes isolate runtime negotiation, but cannot replace compile-time layer selection. Singleton identity remains local to a realm—not shared across threads.

The Lynx federation adapter demonstrates this requirement. The companion Lynx lifecycle changes support loading those bundles; they address a separate transport concern.

Proposal

Option	Meaning
shared.request	Import request to match; defaults to the configuration key.
shared.shareKey	Key used for sharing; independent of the matched request.
shared.issuerLayer	Restrict which importing layer consumes this configuration.
shared.layer	Select the provider and local fallback's module layer.
exposes[key].layer	Build that exposed module in a specific layer.
shareScope	Sharing namespace, or an ordered array such as ['app', 'default'] in enhanced mode.

For example, expose one module in two layers and share an example package separately in each:

const { container } = require('@rspack/core');

module.exports = {
  experiments: { layers: true },
  plugins: [
    new container.ModuleFederationPlugin({
      name: 'app',
      exposes: {
        './server': { import: './src/view.js', layer: 'server' },
        './client': { import: './src/view.js', layer: 'client' },
      },
      shared: [
        { 'ui-runtime': { issuerLayer: 'server', layer: 'server' } },
        { 'ui-runtime': { issuerLayer: 'client', layer: 'client' } },
      ],
    }),
  ],
};

Matching layer configurations take precedence over unlayered fallbacks. Layer names must be nonempty when supplied; omitting the layer preserves unlayered behavior.

Ordered shareScope arrays retain their order through runtime initialization. Initial ordered consumers wait for initialization; existing scalar eager consumers remain synchronous. Scope order does not replace version or loading strategy.

Manifests retain existing fields and add layer/scope identity and expose requirements. Export usage and fallback assets stay associated with the correct identity. Optional per-provider reporting is a separate proposal, not part of this layers implementation.

Compatibility and scope

• Layer options require the enhanced runtime (Module Federation 1.5); legacy configurations retain their behavior.
• Existing unlayered manifests remain usable by older readers. Layer-aware readers need coordinated support.

Trade-offs

Using separate share keys or builds avoids this extension, but forces applications to encode layer identity themselves. Carrying it through federation keeps configuration consistent with Rspack's module graph, at the cost of more runtime/metadata bookkeeping and some binding-size growth.

Delivery and review

The implementation is one ordered stack:

1. #12977: shared matching and identity.
2. #14911: ordered-scope runtime initialization.
3. #14912: layered exposes and integration coverage.
4. #14913: manifest metadata.

Reader/types coordination: module-federation/core#5039.

Review should verify layer isolation, exact versus unlayered matching, ordered startup, provider/export attribution, and unchanged legacy behavior. Feedback requested: are the option boundaries and additive metadata sufficient for other layer-based integrations?

[ScriptedAlchemy]

@2heal1 could you take a look at this layer-aware Module Federation proposal and share your thoughts? In particular, I would appreciate your input on the exposed/shared layer options and keeping the Rspack and enhanced Webpack implementations aligned. The companion core implementation is in module-federation/core#5039.