@zonekit/runtime-react

React bindings for Zonekit shells.

@zonekit/runtime-react gives you the provider, hooks, and remote rendering components for a Zonekit React application. Most apps should start with ZonekitProvider. initZonekit() is the escape hatch for mixed React or non-React hosts where a provider tree is not practical.

Installation

pnpm add @zonekit/runtime-react @zonekit/runtime

Quick start

import { createShellContext, loadRemoteModule } from "@zonekit/runtime";
import { RemoteBoundary, ZonekitProvider } from "@zonekit/runtime-react";

declare const zonekitConfig: any;
declare const resolvedConfig: any;
declare function scriptLoader(
  zoneId: string,
  moduleName: string,
  remoteEntryUrl: string,
): Promise<unknown>;

const shellContext = createShellContext({
  auth: { accessToken: "demo-token" },
  tenant: resolvedConfig.tenant,
  config: resolvedConfig,
});

function App() {
  return (
    <ZonekitProvider
      config={zonekitConfig}
      currentZone="shell"
      resolvedConfig={resolvedConfig}
      shellContext={shellContext}
      loadRemoteModule={(zoneId, moduleName) =>
        loadRemoteModule(zoneId, moduleName, {
          zones: zonekitConfig.zones,
          remotes: resolvedConfig.remotes,
          scriptLoader,
        })
      }
    >
      <RemoteBoundary
        zoneId="dashboard"
        moduleName="./DashboardApp"
        fallback={<p>Loading...</p>}
        errorFallback={(error, retry) => <button onClick={retry}>Retry</button>}
      />
    </ZonekitProvider>
  );
}

RemoteBoundary renders the loaded component by default. If you need to wrap the loaded component or inject props, pass a render-function child instead of plain children.

Feature requirements

Different hooks need different pieces of context. ZonekitProvider makes that explicit:

| Feature | Required provider or initZonekit() inputs | |---|---| | useZone, useFlow | config, currentZone | | useResolvedConfig, useRoutes, useNavigation | resolvedConfig | | useAuth, useTenant, useShellContext, useShellContextInstance, useEventBus, useEvent, useAuthLifecycle | shellContext | | useRemoteModule, RemoteBoundary, DynamicRoutes | loadRemoteModule |

DynamicRoutes also needs resolvedConfig, because it builds its route tree from the resolved client config.

API overview

Components

• ZonekitProvider for config, flow, resolved config, and shell state.
• RemoteBoundary for remote module loading with timeout, retry, and error or loading UI.
• DynamicRoutes for shells that want Zonekit to materialize the resolved route tree as lazy components.

Hooks

• useZone() and useFlow(flowId) for core zone and flow state.
• useResolvedConfig(), useRoutes(), and useNavigation(options) for resolved client config.
• useAuth(), useTenant(), useShellContext(), and useShellContextInstance() for shell data.
• useEvent(type, handler) and useEventBus() for cross-zone events.
• useRemoteModule(zoneId, module, options) for remote loading state and retries.
• useConfigRefresh(refresher, pathname) and useAuthLifecycle() for shell lifecycle concerns.
• useShellSnapshot(instance) for low-level shell subscriptions.

Utilities

• initZonekit(options) for non-Provider usage. It only supports the features whose required inputs you pass.
• createFlowStore(options) for shared flow state outside the default provider wiring.

All hooks and components are SSR-safe. Remote module loading happens client-side after hydration.

SSR usage

During server-side rendering, RemoteBoundary renders its fallback prop. Remote modules are fetched after hydration on the client.

function Page() {
  return (
    <ZonekitProvider
      config={config}
      currentZone="shell"
      resolvedConfig={resolvedConfig}
      shellContext={shell}
      loadRemoteModule={loadRemote}
    >
      <RemoteBoundary
        zoneId="dashboard"
        moduleName="./Overview"
        fallback={<OverviewSkeleton />}
        errorFallback={(error, retry) => <button onClick={retry}>Retry</button>}
      />
    </ZonekitProvider>
  );
}

Hooks like useResolvedConfig, useAuth, and useTenant return stable values during SSR and rehydrate on the client.

Browser compatibility

All packages target ES2022. This covers:

• Chrome/Edge 94+
• Firefox 93+
• Safari 16.4+
• Node.js 20+

No polyfills are required for the listed browsers.

Peer dependencies

| Package | Version | |---|---| | react | ^18.0.0 \|\| ^19.0.0 | | react-dom | ^18.0.0 \|\| ^19.0.0 |

License

MIT

Read more:

• Quickstart
• @zonekit/runtime-react package docs
• Federation concepts