Federation helpers

Low-level helpers in @numueg/theme-sdk that interact with the storefront's federation runtime. You almost never need these. They exist for the SDK's own internals and for advanced themes that load extra modules dynamically.

`registerSdkSingleton()` / `getSdkSingleton()`

function registerSdkSingleton(sdk: unknown): void;
function getSdkSingleton(): unknown | null;

The SDK calls these internally on import to detect "two copies of the SDK loaded" (which would indicate a build misconfiguration). The host calls registerSdkSingleton first; the bundle's import resolves to the same instance via the import map; the singleton check passes.

If you're seeing Multiple SDK instances detected at mount, your theme's vite.config.ts is bundling the SDK instead of externalizing it. Add "@numueg/theme-sdk" to build.rollupOptions.external.

`registerReactSingleton()` / `getReactSingleton()`

Same shape, for React. Mostly an internal check. Themes shouldn't call these.

`isSdkAvailable()`

function isSdkAvailable(): boolean;

Returns true once the SDK is fully initialized. Useful for SSR/CSR boundaries — though in practice, themes only render after mount() is called, so by then the SDK is always available.

`assetUrl(path)`

function assetUrl(path: string): string;

Resolves a theme asset to its content-hashed URL. The plugin's asset pipeline (Phase 2.5) emits assets/* to dist/assets/<hash>.ext and writes a manifest. assetUrl() looks up the hash + returns the full URL.

<img src={assetUrl("hero.jpg")} alt="Hero" />
// → "https://r2.numueg.app/themes/abc123/v5/assets/hero.a1b2c3.jpg"

In dev (numu-theme dev), it returns /assets/hero.jpg (no hash, no CDN). In production, the URL resolves to R2.

Why a separate "federation" namespace

The federation runtime is the weak point of the architecture — most theme breakage comes from a misconfigured build leaking a second React or a second SDK into the page. Keeping these helpers in a separate namespace makes them grep-able and signals "if you're calling this, you're doing something unusual."

If you're not sure whether to use one of these, you probably shouldn't. Open an issue or ask in #dev-platform.

Federation helpers

registerSdkSingleton() / getSdkSingleton()#

registerReactSingleton() / getReactSingleton()#

isSdkAvailable()#

assetUrl(path)#

Why a separate "federation" namespace#

`registerSdkSingleton()` / `getSdkSingleton()`

`registerReactSingleton()` / `getReactSingleton()`

`isSdkAvailable()`

`assetUrl(path)`

Why a separate "federation" namespace