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/iframeWhen 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, andendpoint.connectToare whole-field replacements when explicitly providedpolicyis a whole-field replacement when explicitly provided; omitted policy keeps previous layerspolicy: undefinedclears inherited policy when callers intentionally need to remove itprovidersreplace bytoken.id; the later provider replaces both service and policy
Security Notes
- Use exact origins for parent
frames[].originand childparentOriginwhenever possible. originandparentOriginmust match the browserMessageEvent.originexactly, including scheme, host, and port.allowAnyOrigin: truepermits wildcard origin matching and should only be used for intentionally public frames.- Use
noncewhen 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.canConnectandpolicy.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.