Clarity Angular and React Wrappers in Micro-Frontend: Custom Element Registry Collision and CSS Variable Scoping

Direct Answers

1. Guard pattern: Check customElements.get(tagName) === undefined before calling customElements.define(), or wrap the call in try/catch and ignore DOMException with name 'NotSupportedError'.
2. CSS variable propagation: Set Clarity theming variables (e.g., --clr-primary) on :root or the Angular shell’s host element; they inherit through shadow DOM without piercing. Use ::part() only for internals exposed via declared CSS parts.
3. Version locking: Pin @clr/ui to a single exact version in the top-level package.json and force alignment with npm overrides (v7+) or yarn resolutions so both wrappers resolve to the same core.

Duplicate Registration Guard

Both @clr/angular and @clr/react re-export the same @clr/ui web components and each calls customElements.define() during module initialization. The second load throws DOMException: NotSupportedError if the tag is already registered.

Apply one of these guards at the earliest shared entry point (e.g., Angular shell main.ts or a shared bootstrap module):

// Option A: explicit check
const TAGS = ['clr-button', 'clr-input', 'clr-card', /* …all Clarity tags… */];
TAGS.forEach(tag => {
  if (customElements.get(tag) === undefined) {
    // safe to let the wrapper define it
  }
});

// Option B: try/catch (catches any duplicate)
try {
  customElements.define('clr-button', ClrButton);
} catch (e) {
  if (e instanceof DOMException && e.name === 'NotSupportedError') {
    // already registered — ignore
  } else {
    throw e;
  }
}

Option A is preferable because it avoids the exception overhead and makes intent explicit. Generate the tag list from @clr/ui’s components.json or the wrapper’s exported component map to stay in sync across versions.

Theming Without Piercing Shadow DOM

Clarity’s core web components read CSS custom properties from their host element or :root via standard inheritance through shadow DOM boundaries. Setting variables on the Angular shell’s :root (or a wrapper div that ancestors the React‑mounted components) propagates automatically:

:root {
  --clr-primary: #0066cc;
  --clr-background: #f8f9fa;
  --clr-font-family: 'Inter', system-ui, sans-serif;
}

For internals exposed via ::part() (e.g., ::part(input), ::part(button)), add overrides in the shell’s global stylesheet:

clr-input::part(input) {
  border-radius: 4px;
}

Do not use ::slotted(), ::shadow, or constructible stylesheets to reach non‑part internals — those paths are deprecated and will break.

Version‑Locking Strategy

Peer dependency ranges in @clr/angular and @clr/react often lag @clr/ui releases, so a single @clr/ui version must be enforced at the root:

// package.json (npm v7+)
{
  "dependencies": {
    "@clr/ui": "6.3.0",
    "@clr/angular": "6.3.0",
    "@clr/react": "6.3.0"
  },
  "overrides": {
    "@clr/angular > @clr/ui": "6.3.0",
    "@clr/react > @clr/ui": "6.3.0"
  }
}

For Yarn 1.x/berry, use resolutions in package.json or packageExtensions in .yarnrc.yml. After install, verify with:

npm ls @clr/ui
# or
 yarn list @clr/ui

Only one version should appear. If multiple remain, check transitive dependencies of other packages and extend overrides accordingly.

Verification Checklist

1. Open DevTools console; run customElements.get('clr-button') before and after each wrapper loads — the second load should not throw.
2. Set --clr-primary: #ff0000 on :root, inspect a Clarity button’s shadow root, confirm computed background-color reflects the variable.
3. Run npm ls @clr/ui; single version confirms overrides worked.

Missing Diagnostic Detail

Which bundler and module format (ESM vs. CommonJS) does the Angular shell use for the React micro‑frontend entry point? The answer determines whether the guard runs before or after the React wrapper’s side effects execute, and whether customElements is shared across the same global scope.