Module Fedaration support for Uniwind

[dlebedynskyi]

Support for Module Federation (multiple remotes sharing one Uniwind runtime)

I'd like to open a discussion about first-class support for Module Federation in Uniwind — specifically, letting multiple independently-built remotes share a single
Uniwind runtime on both web and native without their styles colliding.

Today Uniwind works great in a single-bundle app. But in a Module Federation setup, a host loads several remotes that were each built separately (often by different teams,
on different release cadences) and may be present on screen at the same time. In that world, a few of Uniwind's current assumptions break down.

Metro now fully supports MF 2.0, and we're starting to use it for our app(s) — so this isn't hypothetical need for us and, if this does not land, we probably would have to fork or patch. However, I believe that problem is better solved at lib level.

Refs:

• Module Federation 2.0 — Metro

I don't have a fully-formed solution to propose yet — I want to align on whether this is in scope, and on the shape of the problems. I've done some exploration and I'll show how it could potentially be made possible.

Concrete problems

Web

• Remotes emit ordinary global utility-class selectors (.bg-surface, .flex) and theme variables into the shared document. Two remotes built independently can generate
  the same class name with different definitions, so which one "wins" depends on load order — a non-deterministic styling bug.
• There's no built-in way to namespace a remote's own local classes while leaving genuinely shared classes shared.

From what I've gathered, on web we're effectively using a single document as the root for the CSS stylesheets. This works as long as classes and vars don't collide.

Potentially we could use Tailwind's prefix to resolve collisions while keeping the same root. Alternatives like a ShadowRoot per remote are possible to isolate stylesheets, but IMO more complex.

/* remote-a global.css — prefix the remote's own utilities/theme (Tailwind v4) */
@import "tailwindcss" prefix(rma);
@import "uniwind";

<!-- source className stays "flex bg-surface"; remote-local classes resolve prefixed -->
<div class="rma:flex rma:bg-surface"></div>

Refs:

• Tailwind v4 — prefix
• ShadowRoot + rendering React into a ShadowRoot via createPortal (React 18+)

Native

• The generated native CSS bundle initializes the store by replacing the stylesheet registry wholesale (reinit). When a remote loads, it can wipe the styles registered by the host or an earlier remote.
• Registration is effectively last-writer-wins, and remotes can load in any order — so behavior is order-dependent.

Potentially we could merge if we can avoid name collisions (via the Tailwind v4 prefix), or we move the store from a singleton into React Context to allow overrides at a remote boundary.

// today — replaces the whole registry
Uniwind.__reinit(rt => generatedStyles, themes)

// proposed — merge under an owner id instead of replacing
Uniwind.__mergeStyles('remote-a', rt => generatedStyles, themes)

// context alternative — store scoped at the remote boundary
<UniwindProvider prefix="rma">
  <RemoteApp />
</UniwindProvider>

What is the minimal set of changes?

At the very least we'd need to support merging styles instead of a whole reinit. That alone lets consumers use prefix explicitly to avoid collisions.

Is there a better way?

We could make it an opt-in build option, following the existing pattern of wrapping Metro with withUniwind. This probably works better — we can tell the build "this bundle is a remote: use these common classes (Preflight / other host-provided commons), and prefix everything else."

// metro.config.js (remote) — opt-in, no effect when omitted
const { withUniwindConfig } = require('uniwind/metro');

module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/global.css',
  federation: {
    role: 'remote',      // 'host' | 'remote'
    prefix: 'rma',       // stable per remote; not a build version
    // sharedClassNames provided by the host (Preflight / common utilities)
  },
});

Properties of this approach:

• It won't break existing single-bundle apps — it's opt-in.
• Uniwind would be configured to use the merge strategy for remotes regardless, and MF 2.0 configured so the changes are co-located.
• Ideally it has no impact on how people write their code internally — authors shouldn't have to remember to prefix every class.

Questions

1. Is Module Federation support something maintainers would consider in scope for core, or better elsewhere (patching may be tricky but feasible)?
2. Is the web-namespacing + native-merge split the right seam, or is there a simpler model?
3. Anyone already running Uniwind across federated remotes — how are you handling collisions today?

Happy to prototype and contribute a PR if there's appetite.

[Brentlok]

1. Is Module Federation support something maintainers would consider in scope for core, or better elsewhere (patching may be tricky but feasible)?

It wasn't requested before, and we don't really use module federation inside our own projects.
If the required change is minimal and won't affect single-bundle apps we can add it into the core

2. Is the web-namespacing + native-merge split the right seam, or is there a simpler model?

I don't have a better solution in mind right now

Happy to prototype and contribute a PR if there's appetite.

Could you open PR with just adding a new apps/module-federation with some minimal styles rendered and conflicting using module federation so I could play with it?

[dlebedynskyi]

@Brentlok published Draft PR with demos

#613

Note: took a bit of work to setup MF2.0 with uniwind wrapper in expo. This was not the focus of this discussion but probably worthy to look at in scope of broad MF support.