Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Version 0.0.8 (Dual Licensed MIT & GPL)

What is it?

postal.xwindow is an add-on for postal.js that provides cross window communication capabilities using a localStoreage hack. A lot of code and boiler plate config is taken from postal.xframe.

What the difference to postal.xframe

postal.xframe needs a reference to the frame to function. There are scenarios where you don't have this reference:

  • separately opened windows of your application
  • opener reloaded, child still exists
  • window chain where some window in the middle of the chain got closed

How does it work?

postal.xwindow uses localStorage as a workaround to let separate windows communicate. The same would be possible with sharedWorkers but browser support is incomplete for it.

  • Each postal.xwindow instance has it's own target/key in localStorage postal.fedx.xwindow.
  • A target contains two keys message and targetTimeout.
  • Each postal.xwindow instance periodically updates its targetTimeout. A cleanup process tidys up the storage area from dead targets.
  • Each postal.xwindow posts its messages to all other targets message key.
  • Each postal.xwindow instance listens to the localStorage events for its own message key.

Run-time Dependencies

This is a postal add-on, so it's assumed that you have postal and lodash loaded already.

How do I use it?

  • see example
  • NOTE: postal.xwindow uses store2, but store2 can't be loaded by webpack yet. you need to mangage the include yourself.
  <script src="../node_modules/store2/dist/store2.js"></script>
  <script src="../node_modules/store2/src/store.bind.js"></script>
  • NOTE: as postal.xwindow uses localStorage you might need to take care of what you post and have popper cleanup.
// this instance of postal *MUST* have a unique identifier, otherwise
// there is no way to differentiate between this instance of postal
// and a remote instance. You can provide your own server-generated
// GUID, or - if you know a unique value ahead of time - you can set
// it via postal.instanceId(id). Calling postal.instanceId() without any
// arguments acts as a getter - it returns the current instance Id.

// You can optionally configure postal.xwindow with the configure call.
// `allowedOrigins` is an array of origins that you can use to determine
// if you want to federate with postal instances loaded in another window
// from those origins.  If another host attempts to federate with you from
// an origin not listed in that array, the local instance of postal will
// not allow it. The local instance of postal will not send any messages to
// (nor process any from) an origin not listed in this array.
	allowedOrigins : [ "", "" ],
	enabled: true // this is redundant - just showing that it's here

Building, Running Tests

  • npm install to install dependencies
  • gulp test to build and run tests
  • gulp coverage to build, run tests and show an istanbul coverage report
  • gulp to build
  • gulp watch to start a file watch which builds as you save changes to the src/ files
  • npm start will start a local web server that lets you run browser-based tests or see a _very_simple example of multiple windows communicating.


  • cope/support origins?!
  • support rename of instance
  • write tests
  • implement cleanup on window close


postal.js add-on providing the ability to federate instances of postal across independent window boundaries



No releases published


No packages published
You can’t perform that action at this time.