🐕 Buddy

Dead simple cross-domain iframe messaging

Installation

yarn add @poool/buddy

Usage

import { on, send } from '@poool/buddy';

// Register handler inside child window
on('getInfos', async event => {
  console.log('You have a message from some window :', event.data);

  // You can even pass methods to child window and retrieve its return value
  // using promises or async/await:'
  console.log(await event.data.someMethod());

  // You can even send data back to parent, EVEN METHODS \o/
  // Parent will only have to await `send()` method promise to get the result
  return { someOtherMethod: () => 30 };
}, { source: someParentWindow });

// And send some message from parent window
send(someChildWindow, 'getInfos', { infos: 'some string', someMethod: () => 25 }, { origin: '*' });

Buddy serializes all the primitive types (using JSON.parse) and even methods, using custom back & forth Promise logic.

IE Compatibility

As part of a global effort to deprecate Internet Explorer, we decided not to include IE polyfills by default. You can still manually import a version containing all the necessary polyfills for IE >= 11:

import * as buddy from '@poool/buddy/dist/ie/buddy.esm.js';

Please note that this build will probably add more than 150kb to your final bundle.

Configuration

Global options can be updated using setGlobalOptions method:

import { setGlobalOptions } from '@poool/buddy';

setGlobalOptions({ logLevel: 0 });

Options

timeout

• Type: Number
• Default: 5000

Message expiration time, after which an error will be thrown.

logLevel

• Type: Number
• Default: 1

Either 0 (disabled), 1 (error), 2 (warn), 3 (info), 4 (debug), 5 (log)

Documentation

on(name, callback, options)

• name {String} Event name
• callback {Function}
  • event {Object}
• options {Object}
  • source {Window} Source window
  • origin {String} Origin expected from source window. * (default) or any other origin.
  • ...globalOptions

send(target, name, data, options)

• target {Window} Target window
• name {String} Event name
• data {Object} Data to be serialized & sent to child
• options {Object}
  • origin {String} Origin expected from source window. * (default) or any other origin.
  • pingBack {Boolean} Mostly used internally. Whether sender should await a response from receiver or not. true (default) or false
  • ...globalOptions

Contributing

Please check the CONTRIBUTING.md doc for contribution guidelines.

Development

Install dependencies:

yarn install

Run examples at http://localhost:64000/ with webpack dev server:

yarn serve

And test your code:

yarn test

License

This software is licensed under MIT.

Contributors

Ugo Stephant 💻 📖 🔧	Nicolas Auger 💻