@mfe-debugger/sdk

Browser SDK for sending micro-frontend runtime diagnostics to MFE Debugger.

It captures and correlates:

• postMessage sends, receives, timeouts, origins, and correlation IDs
• runtime errors and unhandled promise rejections
• client-side JWT claim checks
• host and remote manifests
• release, environment, and project context

Install

npm install @mfe-debugger/sdk

5 Minute Quickstart

Create an API key in the MFE Debugger console, then initialize the SDK in the host shell:

import { createMfeDebugger } from "@mfe-debugger/sdk";

const debuggerClient = await createMfeDebugger({
  apiUrl: "https://api.example.com",
  ingestUrl: "https://ingest.example.com",
  apiKey: "mfdbg_project_key",
  project: "checkout-superapp",
  environment: "production",
  title: "checkout host shell",
  release: {
    version: "2026.04.17",
    buildId: "build-2048"
  },
  manifest: {
    name: "host-shell",
    version: "2.8.1",
    origin: window.location.origin,
    sharedDependencies: {
      react: "19.0.0",
      "react-dom": "19.0.0"
    }
  },
  flushIntervalMs: 2000
});

Send a correlated postMessage from host to remote:

await debuggerClient.postMessage({
  targetWindow: iframe.contentWindow!,
  message: { type: "checkout.auth.request" },
  targetOrigin: "https://payment.example.com",
  expectedOrigin: "https://payment.example.com",
  targetMfe: "payment-mfe",
  channel: "checkout.auth",
  timeoutMs: 2000,
  listenerRegistered: true
});

Track remote-side evidence:

window.addEventListener("message", (event) => {
  debuggerClient.trackMessageReceived({
    event,
    channel: "checkout.auth",
    sourceMfe: "host-shell"
  });
});

debuggerClient.validateJwt({
  token: sessionStorage.getItem("token"),
  expectedIssuer: "https://auth.example.com",
  expectedAudience: "checkout"
});

Runtime Options

| Option | Required | Description | | --- | --- | --- | | apiUrl | yes | Private API base URL. Kept for compatibility and future admin flows. | | ingestUrl | no | Public ingest URL. Falls back to apiUrl when omitted. | | apiKey | yes | Project-scoped ingest key from the console. | | project | yes | Project slug. API key scope wins on the server when present. | | environment | yes | Environment slug, for example production or staging. | | title | yes | Human-readable session title. | | manifest | yes | Host or remote manifest. | | relatedManifests | no | Additional manifests to attach at session creation. | | release | no | Version/build metadata. | | metadata | no | Safe, non-sensitive context. | | sessionId | no | Existing session ID when continuing a session. | | autoStart | no | Defaults to true. | | flushIntervalMs | no | Periodic flush interval. Manual flush() is always available. | | captureWindowMessages | no | Defaults to true. | | captureRuntimeErrors | no | Defaults to true. | | captureUnhandledRejections | no | Defaults to true. | | transport | no | Custom fetch-compatible transport for tests or controlled runtimes. |

Privacy

The SDK sends only what you pass to it plus enabled browser runtime signals. Do not put secrets, full tokens, card data, or personal data in metadata, event payloads, or manifests. For JWT checks, the SDK decodes claims client-side and records claim metadata, not token signatures.

Examples

• examples/next-host.ts
• examples/vite-host.ts
• examples/module-federation-host.ts
• examples/remote-runtime.ts

Compatibility

See COMPATIBILITY.md.

Changelog

See CHANGELOG.md.