iframe-helper-sdk

Iframe Helper SDK

Secure, structured communication between a parent page and cross-domain iframes.

iframe-helper-sdk is a zero-dependency TypeScript SDK for iframe integrations. It wraps window.postMessage with exact origin validation, ready-first handshakes, session routing, bounded queueing, request/response timeouts, fire-and-forget events, opt-in iframe resizing, diagnostics, optional compile-time typed contracts, and an optional child runtime for iframe apps.

Use it when you need a small, auditable bridge between your application and an embedded iframe without building a custom protocol from scratch.

Install

npm install iframe-helper-sdk

pnpm add iframe-helper-sdk

yarn add iframe-helper-sdk

Types are included. No separate @types/* package is required.

Quick Start

Parent Page

The SDK runs in the parent page. Give it a container and an iframe URL, wait for the iframe to complete the handshake, then start communicating.

import { IframeBridgeError, createIframeBridge } from 'iframe-helper-sdk';

const bridge = createIframeBridge({
  container: '#partner-frame',
  src: 'https://partner.example/app',
  iframeAttributes: {
    title: 'Partner application',
  },
  securityProfile: 'strict',
});

try {
  await bridge.whenReady();

  const user = await bridge.request<{ id: string }, { name: string }>('user:get', {
    id: '123',
  });

  console.log(user.name);
} catch (error) {
  if (error instanceof IframeBridgeError) {
    console.error('Bridge failed:', error.code, error.details);
  } else {
    throw error;
  }
}

Iframe Application

The iframe application does not need to install this SDK. It implements the wire protocol directly by reading the bootstrap parameters and replying with protocol envelopes.

const params = new URLSearchParams(window.location.search);
const sessionId = params.get('__iframeBridgeSessionId');
const parentOrigin = params.get('__iframeBridgeParentOrigin');

if (!sessionId || !parentOrigin) {
  throw new Error('Missing iframe bridge bootstrap parameters.');
}

window.parent.postMessage(
  {
    protocol: 'iframe-bridge',
    version: 1,
    sessionId,
    type: 'bridge:ready',
  },
  parentOrigin,
);

window.addEventListener('message', (event) => {
  if (event.origin !== parentOrigin) return;

  const message = event.data;
  if (message?.protocol !== 'iframe-bridge' || message?.version !== 1) return;
  if (message.sessionId !== sessionId) return;

  if (message.type === 'bridge:request' && message.name === 'user:get') {
    window.parent.postMessage(
      {
        protocol: 'iframe-bridge',
        version: 1,
        sessionId,
        type: 'bridge:response',
        requestId: message.requestId,
        payload: { name: 'Ada Lovelace' },
      },
      parentOrigin,
    );
  }
});

See the full Wire Protocol for every envelope type and validation rule.

Iframe Application With Child SDK

If the iframe app can install the package, use the child SDK instead of hand-writing the protocol boilerplate:

import { createIframeChildBridge } from 'iframe-helper-sdk/child';

const bridge = createIframeChildBridge({
  allowedParentOrigins: ['https://host.example'],
});

await bridge.whenConnected();
await bridge.sendEvent('cart:changed', { itemCount: 3 });
bridge.on('theme:changed', (payload) => {});
bridge.handleRequest('user:get', async (payload) => ({ name: 'Ada' }));
bridge.destroy();

allowedParentOrigins?: readonly string[] | null may be omitted or set to null to accept the bootstrap parent origin. Non-empty arrays require exact origin match; empty arrays are invalid. If you omit the allowlist, rely on server-side/browser embedding controls such as CSP frame-ancestors.

The child bridge has no request() method. Child request handlers respond to parent bridge:request; the child does not initiate bridge:request.

Why This SDK

Raw postMessage is intentionally low-level. Every window, iframe, tab, and extension can send messages on the same channel. A production iframe integration needs more structure than a message event listener.

Concern	Raw postMessage	Iframe Helper SDK
Origin validation	Manual and easy to miss	Exact origin enforced per bridge
Handshake	None or custom	Ready-first handshake with timeout
Message format	Ad hoc JSON	Versioned iframe-bridge envelopes
Request queueing	Not built in	Bounded pre-ready queue
Timeouts	Manual timers	Configurable operation timeouts
Typed contracts	Manual type assertions	Compile-time narrowing via contract maps
Error handling	Generic errors	IframeBridgeError with code-based branching
Diagnostics	Console logging	Opt-in diagnostic recorder and logger hooks

Features

• Strict origin enforcement - exact targetOrigin and allowedOrigin checks. Wildcard origins are rejected.
• Ready-first handshake - the parent waits for bridge:ready, validates the sender, then responds with bridge:connected.
• Iframe app SDK - optional iframe-helper-sdk/child runtime for child-side handshake, events, and parent request handlers.
• Session-scoped routing - every bridge gets a session id so messages from unrelated iframes are ignored.
• Bounded pre-ready queue - operations called before readiness are queued and flushed after handshake, with a configurable limit.
• Request/response API - bridge.request() sends a method call and resolves with the iframe response.
• Event API - bridge.sendEvent(), bridge.on(), and bridge.waitForEvent() cover one-way and inbound event flows.
• Iframe resize - opt into child-driven width and height updates with parent-side bounds, offsets, and an applied-resize callback.
• Typed contracts - createTypedIframeBridge narrows method names, payloads, and responses at compile time with no runtime cost.
• Structured errors - every SDK error is an IframeBridgeError with a stable code and optional details.
• Diagnostics - use createDiagnosticRecorder or a custom logger to observe lifecycle, handshake, queue, and filtering decisions.
• Small runtime - zero runtime dependencies, tree-shakable package output, and a compact browser payload.

Communication Patterns

You want to	Use
Wait until the iframe is ready	bridge.whenReady()
Ask the iframe for a result	bridge.request(method, payload)
Notify the iframe without waiting for a body	bridge.sendEvent(name, payload)
Subscribe to iframe events	bridge.on(name, handler)
Wait for one matching iframe event	bridge.waitForEvent(name, options?)
Let the iframe resize itself	resizePlugin() + iframe-bridge:resize event
Recreate a failed bridge attempt	bridge.remount()
Remove listeners, timers, and the iframe	bridge.destroy()

Child-Driven Resize

Resize is opt-in and tree-shakable. Import the resize plugin from the iframe-helper-sdk/resize subpath, register it on the parent, then have the iframe send the reserved iframe-bridge:resize event after the bridge connects.

import { createIframeBridge } from 'iframe-helper-sdk';
import { resizePlugin } from 'iframe-helper-sdk/resize';

const bridge = createIframeBridge(
  {
    container: '#partner-frame',
    src: 'https://partner.example/app',
  },
  {
    plugins: [
      resizePlugin({
        minWidthPx: 320,
        maxWidthPx: 1200,
        minHeightPx: 240,
        maxHeightPx: 900,
        offsetHeightPx: 16,
        onResize({ width, height }) {
          console.log('iframe resized to', width, height);
        },
      }),
    ],
  },
);

The iframe sends the requested dimensions through a standard bridge:event named iframe-bridge:resize. The parent still validates origin, source window, session id, protocol, version, and envelope shape before applying dimensions to the owned iframe element.

Iframe apps that use the child SDK can import the tree-shakable child resize plugin from iframe-helper-sdk/child/resize:

import { createIframeChildBridge } from 'iframe-helper-sdk/child';
import { childResizePlugin } from 'iframe-helper-sdk/child/resize';

const bridge = createIframeChildBridge(
  { allowedParentOrigins: ['https://host.example'] },
  { plugins: [childResizePlugin({ axis: 'both' })] },
);

Child resize must be imported from iframe-helper-sdk/child/resize, not iframe-helper-sdk/child.

offsetWidthPx and offsetHeightPx add fixed parent-side pixels before min/max bounds are applied. In development mode, the SDK warns if resize is enabled without max bounds for every active axis; in securityProfile: 'strict', missing active max bounds throw CONFIG_INVALID_RESIZE.

Full guide: Resize Plugin.

Type-Safe Bridge

Use createTypedIframeBridge when your integration has enough methods or events that repeated generics become noisy. The contract exists only at compile time. It does not validate runtime payloads and is not a security boundary.

import { createTypedIframeBridge } from 'iframe-helper-sdk';

type PartnerContract = {
  requests: {
    'user:get': {
      payload: { id: string };
      response: { name: string; email: string };
    };
    'order:create': {
      payload: { productId: string; quantity: number };
      response: { orderId: string };
    };
  };
  outboundEvents: {
    'analytics:track': { action: string; label?: string };
  };
  inboundEvents: {
    'cart:changed': { itemCount: number };
  };
};

const bridge = createTypedIframeBridge<PartnerContract>({
  container: '#partner-frame',
  src: 'https://partner.example/app',
});

await bridge.whenReady();

const user = await bridge.request('user:get', { id: '123' });
// user is { name: string; email: string }

await bridge.sendEvent('analytics:track', { action: 'opened' });

bridge.on('cart:changed', (payload) => {
  console.log(payload.itemCount);
});

Read more in the Type-Safe Bridge guide.

Security Model

This SDK is a transport and lifecycle layer, not a complete application security solution. It reduces common postMessage mistakes, but authentication, authorization, payload validation, CSRF protection, and server-side business rules remain your responsibility.

Enforced by the SDK:

• Parent-to-iframe messages always use an exact target origin.
• Inbound messages are validated against origin, source window, session id, protocol name, protocol version, and envelope shape.
• HTTPS iframe URLs are required by default. HTTP is only allowed for explicit localhost development mode.
• Unsafe URL schemes such as javascript:, data:, blob:, and srcdoc are rejected.
• securityProfile: 'strict' turns risky production settings into config errors.
• destroy() removes SDK-owned listeners, timers, pending requests, event waits, and the owned iframe.

Production checklist:

• Use HTTPS for both parent and iframe origins.
• Set securityProfile: 'strict' once local development is complete.
• Keep targetOrigin, allowedOrigin, and child allowedParentOrigins exact. Do not use wildcard origins.
• Add parent-side CSP such as frame-src https://partner.example.
• Add iframe-side CSP such as frame-ancestors https://host.example.
• Review iframe sandbox and allow attributes before enabling browser capabilities.
• Validate critical payloads in your application layer or backend.

Read the full Security guide before shipping a cross-domain integration.

API Surface

Import parent public APIs from the package root. Child APIs and optional plugins use documented subpath exports such as iframe-helper-sdk/child, iframe-helper-sdk/resize, and iframe-helper-sdk/child/resize; never import from internal src or dist paths.

import {
  BRIDGE_MESSAGE_TYPES,
  BRIDGE_PROTOCOL_NAME,
  BRIDGE_PROTOCOL_VERSION,
  IframeBridgeError,
  createDiagnosticRecorder,
  createIframeBridge,
  createTypedIframeBridge,
  isBridgeEnvelope,
  normalizeBridgeRemoteError,
  validateBridgeEnvelope,
} from 'iframe-helper-sdk';

import { resizePlugin } from 'iframe-helper-sdk/resize';
import { createIframeChildBridge } from 'iframe-helper-sdk/child';
import { childResizePlugin } from 'iframe-helper-sdk/child/resize';

Export	Kind	Purpose
createIframeBridge	Function	Create a parent-side iframe bridge
createTypedIframeBridge	Function	Create the same bridge with contract-narrowed types
createIframeChildBridge	Function	Create a child-side bridge inside an iframe app
createDiagnosticRecorder	Function	Capture diagnostic events in a bounded recorder
IframeBridgeError	Class	SDK error with code, message, and details
BRIDGE_MESSAGE_TYPES	Constant	Tuple of protocol message type strings
BRIDGE_PROTOCOL_NAME	Constant	Protocol name, currently 'iframe-bridge'
BRIDGE_PROTOCOL_VERSION	Constant	Protocol version, currently 1
isBridgeEnvelope	Function	Type guard for bridge envelopes
validateBridgeEnvelope	Function	Validate and return a typed bridge envelope
normalizeBridgeRemoteError	Function	Normalize iframe-side error responses
resizePlugin	Function	Optional child-driven resize plugin from ./resize
childResizePlugin	Function	Optional child-side resize plugin from ./child/resize

Bridge Instance

type IframeBridge = {
  readonly iframe: HTMLIFrameElement;
  readonly state:
    | 'created'
    | 'mounting'
    | 'waiting_for_handshake'
    | 'ready'
    | 'handshake_failed'
    | 'destroyed';
  request<TPayload, TResponse>(
    method: string,
    payload: TPayload,
    options?: OperationOptions,
  ): Promise<TResponse>;
  sendEvent<TPayload>(name: string, payload: TPayload, options?: OperationOptions): Promise<void>;
  waitForEvent<TPayload>(name: string, options?: OperationOptions): Promise<TPayload>;
  on<TPayload>(name: string, handler: (payload: TPayload) => void): () => void;
  whenReady(): Promise<void>;
  remount(): IframeBridge;
  destroy(): void;
};

Full reference: API Reference.

Error Handling

All SDK errors use IframeBridgeError. Branch on error.code instead of parsing strings.

import { IframeBridgeError } from 'iframe-helper-sdk';

try {
  await bridge.whenReady();
  const result = await bridge.request('report:generate', payload, {
    timeoutMs: 30_000,
  });
  console.log(result);
} catch (error) {
  if (error instanceof IframeBridgeError) {
    switch (error.code) {
      case 'HANDSHAKE_TIMEOUT':
        console.error('The iframe did not complete the handshake.');
        break;
      case 'REQUEST_TIMEOUT':
        console.error('The iframe did not respond in time.');
        break;
      case 'REQUEST_REMOTE_ERROR':
        console.error('The iframe returned an error:', error.details);
        break;
      default:
        console.error(error.code, error.message, error.details);
    }
  } else {
    throw error;
  }
}

Common codes:

Code	Meaning
HANDSHAKE_TIMEOUT	The iframe did not send a valid bridge:ready in time
REQUEST_TIMEOUT	A request was sent, but no matching response arrived in time
REQUEST_REMOTE_ERROR	The iframe responded with an explicit error object
EVENT_WAIT_TIMEOUT	waitForEvent() did not receive the expected event in time
OPERATION_ABORTED	The provided AbortSignal cancelled the operation
BRIDGE_NOT_READY	Queueing is disabled and an operation ran before readiness
BRIDGE_DESTROYED	The bridge was destroyed before the operation could complete
QUEUE_LIMIT_EXCEEDED	Too many operations were queued before the iframe became ready

See the Error Codes reference for the complete list and recovery actions.

Diagnostics

Diagnostics are opt-in. Use the built-in recorder for local debugging or plug your own logger into monitoring.

import { createDiagnosticRecorder, createIframeBridge } from 'iframe-helper-sdk';

const recorder = createDiagnosticRecorder({ maxEntries: 100 });

const bridge = createIframeBridge({
  container: '#partner-frame',
  src: 'https://partner.example/app',
  diagnostics: {
    debug: true,
    logger: recorder.logger,
  },
});

await bridge.whenReady();

console.table(recorder.entries);

Diagnostics are sanitized by design and do not include raw application payloads by default. See Debugging & Diagnostics.

Documentation

Full documentation: furkankaynak.github.io/iframe-helper-sdk

Section	Pages
Introduction	Home, Getting Started, Core Concepts
Guides	Configuration, Type-Safe Bridge, Wire Protocol, Security, Use Cases, Debugging
Child Iframe SDK	Overview, Security, Events And Requests, Plugins, Resize
Reference	API Reference, Error Codes
Help	Troubleshooting, FAQ

Documentation source lives in documentation/docs.

Examples

The repository includes a working parent and iframe playground under playground/manual.

npm run build

Then run the parent and iframe dev servers in separate terminals:

npm run example:manual:parent

npm run example:manual:iframe

Open http://127.0.0.1:5173/. The parent server runs on port 5173, and the iframe server runs on port 5174.

Compatibility

• Runtime: Browser environments with window, document, HTMLIFrameElement, and postMessage.
• SSR: Browser-only. Create bridges inside client-only lifecycle hooks such as React useEffect, Vue onMounted, or Svelte onMount.
• Build target: ES2020 browser output.
• Package formats: ESM and CommonJS, with TypeScript declarations for both import styles.
• Node.js: >=18 for development, build, and package tooling.
• Dependencies: Zero runtime dependencies.

Development

npm install
npm run build
npm run typecheck
npm run test
npm run lint
npm run format:check

Script	Description
npm run build	Production build with Vite, TypeScript declarations, and CJS type prep
npm run test	Vitest test suite
npm run typecheck	TypeScript type checking with tsc --noEmit
npm run lint	ESLint
npm run format	Format source, tests, playground, docs, config, and README files
npm run format:check	Prettier format check
npm run verify	Full release gate: typecheck, test, lint, format, build, publint, attw, pack
npm run docs:dev	Start the Docusaurus documentation server
npm run docs:build	Build the documentation site

Contributing

Issues and pull requests are welcome on GitHub. For changes to the public API, update the documentation and README examples in the same pull request.

Before opening a PR, run:

npm run verify
npm run docs:build

License

MIT