framecast

framecast

TypeScript cross-frame communication library.

Installation

Framecast is available on npm, you can install it with either npm or yarn:

npm install framecast
# or:
yarn install framecast

Broadcasts

Broadcasts allow you to send one-way communications. The broadcast event is emitted when a valid broadcast is received.

You can add many listeners to the broadcast event.

The only argument contains an object with a deserialized message.

Example

Parent

import Framecast from 'framecast';

const target = document.querySelector('iframe').contentWindow;
const framecast = new Framecast(target);

framecast.on('broadcast', (message: any) => {
  console.log(message);
});

Child

import Framecast from 'framecast';

const target = window.parent;
const framecast = new Framecast(target);

framecast.broadcast('Hello world');

Functions

Framecast allows you to call functions across frames. The function:* event is emitted when the call is made. The returned value of the listener is passed back to the calling frame.

Note, unlike the broadcast event, function:* events can only have one listener.

Creating a function

Create a function by adding a listener for the function:* event where * is the name of the function. So in the example below the function name is getElementId so we name the event function:getElementId.

Child

import Framecast from 'framecast';

const target = window.parent;
const framecast = new Framecast(target);

framecast.on('function:getElementId', (selector) => {
  return document.querySelector(selector).getAttribute('id');
});

Calling a function

To call the function from another frame, we use call. Note, that all functions return a promise, even if the handler on the other end is a synchronous function.

Parent

import Framecast from 'framecast';

const target = document.querySelector('iframe').contentWindow;
const framecast = new Framecast(target);

const bodyId = await framecast.call('getElementId', 'body');

Handling errors

You handle errors the exact same way as if the function was in the same frame. Wrap the function call in a try/catch.

try {
  const bodyId = await framecast.call('getElementId', 'body');
} catch (error) {
  console.log('Something went wrong', error);
}

By default Framecast will throw an error if the handler take more than 10 seconds to complete. You can customize this with the config.functionTimeoutMs option.

API

constructor(target: Window, config: FramecastConfig);


// broadcasts
on(type: 'broadcast', listener: (message: any) => void);
off(type: 'broadcast', listener: (message: any) => void);
broadcast(message: any);

// functions
on(type: `function:${string}`, listener: (...args: any[]) => void);
off(type: `function:${string}`, listener: (...args: any[]) => void);
call(type: `function:${string}`, ...args: any[]) => Promise<any>;


type FramecastConfig = {
  origin: string | null;
  channel: string | null;
  self: Window | null;
  functionTimeoutMs: number;
};

Inspired by Tabcast