Registry / http-networking / post-robot

post-robot

JSON →
library8.0.32jsnpmunverified

post-robot is a JavaScript library that simplifies secure cross-domain communication between browser windows (e.g., parent/iframe, opener/popup) using the native HTML5 `postMessage` API. It provides a robust, promise-based listener/sender pattern, abstracting away the complexities of serialization and asynchronous communication. A key differentiator is its ability to automatically serialize and deserialize complex data types, including functions, Promises (wrapped in `ZalgoPromise`), and Error objects, enabling advanced inter-window interactions. The library ensures reliable messaging with built-in error handling, timeouts, and options for securing channels by specifying target windows or domains. The current stable version is 8.0.32, and while a strict release cadence isn't explicitly stated, it is actively maintained by KrakenJS. This library is crucial for applications requiring seamless interaction between different origins.

npm install post-robot
INSTALL
IMPORT
SIG · POST-ROBOT
P
post-robot
http-networkingjavascriptv8.0.32
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

postRobot
import postRobot from 'post-robot';
const postRobot = require('post-robot');
Primarily consumed as a default ESM import. CommonJS `require` is also supported but often less preferred in modern build systems. The package exposes `postRobot` as the main entry point for all its functionalities like `on`, `send`, `once`.
send
import postRobot from 'post-robot'; postRobot.send(someWindow, 'messageType', data);
import { send } from 'post-robot'; // Incorrect destructuring
`send` is a method of the default `postRobot` export, not a named export itself. All core functionalities are accessed via the `postRobot` object.
on
import postRobot from 'post-robot'; postRobot.on('messageType', handler);
import { on } from 'post-robot'; // Incorrect destructuring
`on` is also a method of the default `postRobot` export. Do not attempt to destructure it directly from the package import.

This quickstart demonstrates setting up a `post-robot` listener in one window and sending a message to it from another window. It showcases passing data, handling asynchronous responses with Promises, and even invoking functions that were returned across the domain boundary. It includes basic error handling for timeouts.

import postRobot from 'post-robot'; // --- Listener Window (e.g., in an iframe) --- postRobot.on('getUserDetails', function(event) { const userId = event.data.id; console.log(`Listener received request for user ID: ${userId} from ${event.origin}`); // Simulate fetching user data asynchronously return new Promise(resolve => { setTimeout(() => { if (userId === 123) { resolve({ id: userId, name: 'Alice Smith', email: 'alice@example.com', // Functions can also be returned and invoked remotely logStatus: (status) => console.log(`[Remote Log] Alice's status: ${status}`) }); } else { resolve(null); // User not found } }, 500); }); }); console.log('post-robot listener initialized for getUserDetails.'); // --- Sender Window (e.g., parent window) --- // This would typically be in a *different* window context, e.g., the parent window calling the iframe. // For demonstration, we'll simulate the call. // In a real scenario, 'someWindow' would be window.frames[0] or a popup window reference. const someWindow = window.opener || window.parent; // Placeholder, adjust for actual target window if (someWindow && someWindow !== window) { postRobot.send(someWindow, 'getUserDetails', { id: 123 }, { timeout: 3000 }) .then(function(event) { const user = event.data; if (user) { console.log(`Sender received user: ${user.name} from ${event.origin}`); user.logStatus('active'); // Call a function passed from the other window } else { console.log('Sender: User not found.'); } }) .catch(function(err) { console.error('Sender error:', err.message); }); } else { console.warn('Sender simulation: Target window not found. This code needs to run in a separate context to function.'); }
Debug
Known issues
gotchaWhen functions or Promises are passed across domains, post-robot wraps them with its internal `ZalgoPromise` implementation. If you are expecting native `Promise` instances for `instanceof` checks or specific promise library interoperability, this could lead to unexpected behavior.
fix
Be aware that received Promises are `ZalgoPromise` instances. If compatibility with native Promises is critical, manually convert them (e.g., `Promise.resolve(zalgoPromise)`) or adjust checks to account for `ZalgoPromise`.
affects: >=1.0.0
breakingOlder versions (prior to v7) might have different API signatures or behaviors, especially regarding error handling and serialization. While the core `on`/`send` pattern remains, internal mechanics and advanced options have evolved.
fix
Always consult the official documentation for your specific `post-robot` version. When upgrading, review the release notes for breaking changes. For example, some configuration options might have changed names or structures.
affects: <7.0.0
gotchaImproper configuration of the `domain` option (e.g., `postRobot.on('event', { domain: 'http://specific-domain.com' }, handler)`) can lead to messages being ignored or `SecurityError` exceptions if the message's origin does not match the specified domain. Conversely, omitting a specific domain can open up security vulnerabilities if not intended.
fix
Always explicitly define the `domain` option on both `on` and `send` calls to match the expected origin for secure and reliable communication. Use `*` sparingly and only when you fully understand the security implications. For same-domain communication, `window.location.origin` can be used.
affects: >=1.0.0
gotchaMessages sent via `post-robot` have a default timeout. If the listening window does not respond within this period, the sending promise will reject with a timeout error. This is by design to prevent hanging calls, but can be unexpected if not accounted for.
fix
Handle promise rejections from `postRobot.send` calls to gracefully manage timeouts. Adjust the `timeout` option (e.g., `postRobot.send(window, 'msg', data, { timeout: 5000 })`) if you expect longer processing times on the receiving end.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: postRobot.send is not a function
The `postRobot` object was not correctly imported or is not available in the global scope.
fix
Ensure `import postRobot from 'post-robot';` (ESM) or `const postRobot = require('post-robot');` (CommonJS) is at the top of your file where `postRobot` is used. Verify your bundler configuration if using a module system.
Error: Message timeout: No response from window
The target window or listener did not send a response within the configured timeout period.
fix
Check the listening window for errors or long-running operations. Increase the `timeout` option in the `postRobot.send` call if a longer processing time is expected on the receiver side (e.g., `{ timeout: 10000 }`). Ensure the listener function actually returns a value or a Promise that resolves.
SecurityError: Blocked a frame from accessing a cross-origin frame.
The browser's same-origin policy is preventing direct JavaScript access to another window's content. This error typically occurs when attempting to directly manipulate an iframe's `contentWindow` or `contentDocument` from a different origin, and not directly related to `post-robot`'s message passing.
fix
`post-robot` is designed to *circumvent* this exact problem for message passing. Ensure you are using `postRobot.send()` and `postRobot.on()` correctly for communication, and not attempting direct DOM manipulation or property access across origins. Also, verify that the `domain` option in `postRobot.on` and `postRobot.send` is correctly configured.
Error: Can not accept message from https://evil-domain.com
The `postRobot.on` listener was configured with a specific `domain` option (or `window` option), and the incoming message's origin did not match the allowed source.
fix
Review the `domain` (and `window`) option provided to `postRobot.on`. Ensure it correctly specifies the expected origin(s) from which messages should be accepted. If messages are expected from multiple specific origins, the `domain` option can often accept an array of strings.
Upgrade
Version history
8.0.32latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
post-robot — npm install post-robot · libregistry