@zonekit/runtime

Framework-agnostic runtime primitives for Zonekit shells and hosts.

Use @zonekit/runtime when you need config-driven routing, shell context, flow orchestration, handoffs, or federation loading outside the React bindings. Most teams start here for router and shell state, then add federation once their remote contract is stable.

Installation

pnpm add @zonekit/runtime

Quick start

import {
  createRouter,
  createShellContext,
  loadRemoteModule,
  resolveNavigation,
} from "@zonekit/runtime";

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

const resolvedConfig = {
  tenant: { dimensions: { product: "default", tenant: "acme" } },
  remotes: {
    dashboard: {
      url: "https://cdn.example.com/dashboard/remoteEntry.js",
      module: "dashboard",
    },
  },
  routes: [],
  navigation: [{ id: "dashboard", label: "Dashboard", route: "/dashboard" }],
  flags: { dashboard_enabled: true },
  resolvedAt: new Date().toISOString(),
};

const zones = [
  {
    id: "dashboard",
    type: "remote",
    basePath: "/dashboard",
    rendering: "client",
    federation: {
      exposes: {
        "./DashboardApp": "./src/DashboardApp.tsx",
      },
    },
  },
];

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

const router = createRouter(
  {
    transitions: [
      {
        from: "shell",
        to: "dashboard",
        trigger: "open-dashboard",
        mode: "federated",
        federation: { module: "./DashboardApp" },
      },
    ],
  },
  "shell",
  {
    guardEvaluator: (guard) => resolvedConfig.flags[guard.featureFlag ?? ""] === true,
  },
);

const navigation = resolveNavigation(resolvedConfig.navigation, {
  flags: resolvedConfig.flags,
});

const dashboardModule = await loadRemoteModule("dashboard", "./DashboardApp", {
  zones,
  remotes: resolvedConfig.remotes,
  scriptLoader,
});

void shellContext;
void router;
void navigation;
void dashboardModule;

Recommended adoption order

1. Start with createRouter, buildRouteTree, and resolveNavigation to prove your config-driven shell.
2. Add createShellContext when remotes need auth, tenant information, or an event bus.
3. Add loadRemoteModule or createResilientLoader when you are ready to compose remotes at runtime.
4. Add flow and handoff APIs only where you have real cross-zone workflow needs.

Key exports

Zone routing

• createRouter(config, currentZone, options) for guarded zone-to-zone transitions.
• buildRouteTree(config) for indexing resolved routes.
• resolveNavigation(items, options) for flag and guard-aware navigation.

Flow engine

• createFlowEngine(flow, options) for step-based progression with skip or block guards.

Handoff strategies

• buildHandoffPayload(input) for typed payload construction.
• executeCookieHandoff, executeTokenRedirectHandoff, executeSessionHandoff, and executeInMemoryHandoff for transport-specific execution.
• validateHandoffPayload(payload, options) and HandoffPayloadTooLargeError for payload safety checks.

Federation

• loadRemoteModule(zoneId, module, options) for remote loading with cache reuse.
• createResilientLoader(options) for timeout, retry, and circuit-breaker behavior.
• clearModuleCache() for global or targeted cache eviction.
• getRemoteEntryUrl(zoneId, options) and isRemoteAvailable(zoneId, options) for diagnostics.
• generateFederationConfig(zone) and getFederationManifest(zoneId, options) for federation metadata.

Shell and context

• createShellContext(options) for auth, tenant, config, and auth lifecycle state.
• createEventBus() for cross-zone communication.

Resilience

• createCircuitBreaker(options) for per-zone failure isolation.
• createResilientLoader(options) for retries around remote loading.

Federation notes

• Pass resolvedConfig.remotes when you have resolved remotes for the current tenant or product. That gives deterministic remote selection.
• Use clearModuleCache({ zoneId, moduleName }) after a config change, remote URL change, or manual retry flow.
• Use clearModuleCache({ zoneId, moduleName, remoteEntryUrl }) if you need to surgically evict one resolved remote entry without disturbing others.

All modules are SSR-safe -- no DOM or window access in core logic. Inject server-safe adapters via options.

License

MIT

Read more:

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