postmessage-json-rpc

JSON-RPC over window.postMessage, with a Promise-based API.

This package provides a server and client written in JavaScript that can communicate with each other across browser windows or iframes using a subset of JSON-RPC 2.0.

Code Example

ES2015

import {Client, Server} from 'postmessage-json-rpc';
const client = new Client();
const server = new Server({
	hello(who) {
		return Promise.resolve(`Hello ${who}!`);
	}
});

client.mount(window);
server.mount(window);

client.request('hello', window, 'world, of course')
	.then(answer => console.log(answer));

// Hello world, of course!

ES5

var rpc = require('postmessage-json-rpc');
var client = new rpc.Client();
var server = new rpc.Server({
	hello: function(who) {
		return Promise.resolve('Hello ' + who + '!');
	}
});

client.mount(window);
server.mount(window);

client.request('hello', window, 'world, of course').then(function (answer) {
	return console.log(answer);
});

// Hello world, of course!

Motivation

I had a need to quickly "componentize" a legacy web app from an older project, so I could run it in an iframe in a new project and invoke bits of its internal API. I implemented a basic RPC server (for the legacy app) and client (for the host app) using window.postMessage/window.onmessage as the communication channel and (at the moment, loosely) JSON-RPC 2.0 as the message format, and that became the basis of postmessage-json-rpc.

There were already some libraries that did something like this, but I really wanted a fully Promise-based async API on both the client and server side. So I coded one myself 😄

Status/Caveats

The JSON-RPC 2.0 implementation here is not complete, in that batch requests (at least) are not implemented, and there may be some other subtle discrepancies at the moment. Still, for what it does, the module is quite usable.

Installation

npm install --save postmessage-json-rpc

Use Browserify / Webpack to include this module in your front-end code.

API Reference

Basic documentation is available on GitHub.

Tests

Clone this repo, and then run:

npm install
karma start --single-run

Contributors

I welcome and greatly appreciate bug reports, feature ideas, and pull requests in all areas.

License

MIT