nexus
AdaptersIframe

Iframe

Configure Nexus parent and child iframe communication.

@nexus-js/iframe connects a parent browser window and iframe children through Nexus RPC over postMessage. Use it for browser pages that own one or more frames and need typed service calls across that boundary.

Install both in parent and child bundles:

pnpm add @nexus-js/core @nexus-js/iframe

When To Use It

Use this adapter when the parent owns the iframe elements and knows their exact origins. For other runtime boundaries, choose another adapter.

Shared Contracts

Import the same service contracts and Tokens in both bundles; see Getting started for the shared contract pattern.

Keep the shared TokenSpace target-free and pass the exact child target when connecting:

import { TokenSpace } from "@nexus-js/core";
import type { IframeAdapterModel } from "@nexus-js/iframe";
import type { GreetingService } from "./service-contract";

const appSpace = new TokenSpace<IframeAdapterModel>({
  name: "iframe-demo",
});

const childServices = appSpace.space("child-services");

export const GreetingToken = childServices.token<GreetingService>("greeting");

For multiple children, use connectMulticast with exact targets or a targetless ready-connection snapshot. See Core acquisition semantics for timeouts and result behavior. The setup below uses an explicit target.

Parent Setup

Configure the parent with each iframe element and its exact expected child origin before creating proxies.

import { nexus } from "@nexus-js/core";
import { usingIframeParent } from "@nexus-js/iframe";
import { GreetingToken } from "./shared";

const iframe = document.querySelector<HTMLIFrameElement>("#preview");
if (!iframe) throw new Error("Missing #preview iframe");

usingIframeParent({
  appId: "iframe-demo",
  frames: [
    {
      frameId: "preview",
      iframe,
      origin: "https://child.example.com",
      nonce: "session-nonce",
    },
  ],
});

const connection = await nexus.connect({
  target: {
    context: "iframe-child",
    appId: "iframe-demo",
    frameId: "preview",
    origin: "https://child.example.com",
  },
});
const greeting = connection.get(GreetingToken);

await greeting.greet("parent");

The parent helper does not register named targets. Keep exact IframeConnectionTarget values in application code and pass them to connect.

Child Setup

Configure the child with the exact expected parent origin. Class services should bind to the configured Nexus instance with @childNexus.Expose(...); object, State, and Relay providers should use provide(...).

import { usingIframeChild } from "@nexus-js/iframe";
import { GreetingToken } from "./shared";

const childNexus = usingIframeChild({
  appId: "iframe-demo",
  frameId: "preview",
  parentOrigin: "https://parent.example.com",
  nonce: "session-nonce",
});

@childNexus.Expose(GreetingToken)
class GreetingServiceImpl {
  async greet(name) {
    return `hello ${name}`;
  }
}

For an already-constructed object implementation, use:

usingIframeChild({
  appId: "iframe-demo",
  frameId: "preview",
  parentOrigin: "https://parent.example.com",
  nonce: "session-nonce",
}).provide(GreetingToken, greetingService);

Startup Connections

Alternatively, the parent can start listening, create the child context, and passively connect({ where, timeout: 10_000 }) before the child is ready. Give the child helper explicit startup targets: connectTo: [{ context: "iframe-parent", appId: "iframe-demo", origin: "https://parent.example.com" }]. The child then connects without calling any parent service. Select the intended child using its identity and validated frame facts. Startup dialing is one-shot, does not block child ready() and is separate from service acquisition.

Child-originated connections wait for document load, then defer to a later task to allow the parent’s iframe navigation cleanup to run before dialing, including when the child starts inside a load handler. Load-blocking subresources delay the dial; close or unload cancels it. No application-level readiness handshake is required.

Configuration Composition

Use configure: false only when composing adapter config with policy, custom endpoints, bootstrap bulk providers, or custom Nexus instances. Without configure: false, usingIframeChild(...) and usingIframeParent(...) configure the shared nexus instance directly and return that instance.

For composition, use composeNexusConfig([...]) instead of raw object spreading:

import { composeNexusConfig, nexus } from "@nexus-js/core";
import { usingIframeParent } from "@nexus-js/iframe";

nexus.configure(
  composeNexusConfig([
    usingIframeParent({
      appId: "iframe-demo",
      frames: [
        { frameId: "preview", iframe, origin: "https://child.example.com" },
      ],
      configure: false,
    }),
    {
      policy: {
        canConnect({ remoteIdentity }) {
          return remoteIdentity.context === "iframe-child";
        },
      },
    },
  ]),
);

Layers apply left-to-right, and later layers win for the same domain.

Compose structural configuration before the runtime bootstrap snapshot. After a Nexus instance is ready, structural configure(...) calls are rejected; live provider registration or replacement after ready goes through provide(...), not configure({ providers }).

Config composition is domain-aware:

  • omitted fields keep previous layers
  • endpoint.meta, endpoint.implementation, and endpoint.connectTo are whole-field replacements when explicitly provided
  • policy is a whole-field replacement when explicitly provided; omitted policy keeps previous layers
  • policy: undefined clears inherited policy when callers intentionally need to remove it
  • providers replace by token.id; the later provider replaces both service and policy

Security Notes

  • Use exact origins for parent frames[].origin and child parentOrigin whenever possible.
  • origin and parentOrigin must match the browser MessageEvent.origin exactly, including scheme, host, and port.
  • allowAnyOrigin: true permits wildcard origin matching and should only be used for intentionally public frames.
  • Use nonce when a parent page may host multiple frame sessions or when an extra channel binding is useful.
  • Source, origin, app id, channel, and nonce checks are adapter transport gates.
  • Application authorization still belongs in core policy.canConnect and policy.canCall; do not treat adapter gates as a replacement for app-level policy.

Lifecycle

The browser postMessage bus does not guarantee a native disconnect signal. The iframe adapter uses the core virtual-port heartbeat to detect unresponsive links; its defaults come from core (5000ms interval / 3 misses unless core exposes different values). Override heartbeat only for tests or environments that need faster or slower disconnect detection.

Iframe reloads replace the child window and Nexus session. Proxies and refs are session-bound, so reconnect, get fresh proxies, and pass fresh refs after an iframe reload, reconnect, or session replacement.

If a parent swaps the iframe element, register the new element in parent setup before creating new proxies. Existing raw proxies do not silently retarget to the replacement session.

Testing Boundary

Use application mocks for consumers of iframe-targeted services. Use browser integration tests for postMessage validation, security gates, heartbeat, reload, and element replacement.

Binary Transport Packets

Iframe endpoints advertise binary Nexus transport packets and transferable support by default. This lets core serialize internal transport packets to ArrayBuffer and pass that buffer in the browser postMessage transfer list when both sides support it.

This only affects Nexus internal transport packets. User RPC binary values use the ordinary value-serialization path and are not transferred, moved, or detached. Configure limits under transport on either endpoint/helper:

usingIframeParent({
  appId: "iframe-demo",
  frames: [{ frameId: "preview", iframe, origin: "https://child.example.com" }],
  transport: {
    maxFrameBytes: 64 * 1024,
    maxMessageBytes: 16 * 1024 * 1024,
    maxBufferedBytes: 64 * 1024 * 1024,
    binaryPackets: true,
  },
});

These limits default to the values shown. binaryPackets is a packet-format preference, not a switch for user binary values. The endpoints select binary packets only when both support them; if either sets binaryPackets: false, the connection uses JSON packets. Set this preference only under transport.

Edit this page on GitHub