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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HttpPostMessage
✓ import { HttpPostMessage } from 'http-post-message';
✗ const HttpPostMessage = require('http-post-message').HttpPostMessage;
The primary class for creating an HTTP-style message sender. Named import is standard.
IPostMessage
✓ import type { IPostMessage } from 'http-post-message';
TypeScript interface used to define the contract for the postMessage proxy. Use `type` import where available.
HttpPostMessage.addTrackingProperties
✓ import { HttpPostMessage } from 'http-post-message';
// ... then use HttpPostMessage.addTrackingProperties
✗ import { addTrackingProperties } from 'http-post-message';
These are static methods on the `HttpPostMessage` class, typically used to configure `window-post-message-proxy` for correct message processing.
Demonstrates how to instantiate `HttpPostMessage` with a basic proxy and perform `get` and `post` requests, illustrating the HTTP-style API.
import { HttpPostMessage } from 'http-post-message';
import { WindowPostMessageProxy } from 'window-post-message-proxy';
// 1. Set up a mock postMessage proxy (for demonstration)
// In a real app, you would use WindowPostMessageProxy configured correctly.
const stubPostMessageProxy = {
postMessage: (message: any, targetOrigin?: string, targetWindow?: Window) => {
console.log('Sending message:', message);
// Simulate receiving a response after a delay
return Promise.resolve({
id: message.id, // Important for correlation
data: { status: 200, body: `Echo: ${JSON.stringify(message.data)}` },
error: null
});
},
};
// 2. Instantiate HttpPostMessage with the proxy
const httpPostMessage = new HttpPostMessage(stubPostMessageProxy);
// 3. Make an HTTP-style GET request
async function runExample() {
try {
console.log('Making GET request to target/path...');
const response = await httpPostMessage.get('target/path', { headers: { 'X-Custom-Header': 'value' } });
console.log('Received response:', response.body);
// 4. Make an HTTP-style POST request
console.log('\nMaking POST request to /api/data...');
const postResponse = await httpPostMessage.post('/api/data', { item: 'new item' });
console.log('Received POST response:', postResponse.body);
} catch (error) {
console.error('Request failed:', error);
}
}
runExample();
/* Example output (simplified):
Sending message: { id: '...', url: 'target/path', method: 'GET', data: {}, headers: { 'X-Custom-Header': 'value' } }
Received response: Echo: {}
Making POST request to /api/data...
Sending message: { id: '...', url: '/api/data', method: 'POST', data: { item: 'new item' }, headers: {} }
Received POST response: Echo: {"item":"new item"}
*/
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'postMessage')
`HttpPostMessage` was instantiated without a valid `IPostMessage` implementation, or the provided object does not have a `postMessage` method.
fixEnsure an object implementing the `IPostMessage` interface (e.g., an instance of `WindowPostMessageProxy`) is passed as the first argument to the `HttpPostMessage` constructor.
Promise never resolves for http-post-message request.
The `window-post-message-proxy` (or equivalent) on the receiving end is not correctly configured to track messages or is not sending back correlation IDs required by `http-post-message`.
fixVerify that `window-post-message-proxy` on both sending and receiving sides uses `HttpPostMessage.addTrackingProperties` and `HttpPostMessage.getTrackingProperties` in its `processTrackingProperties` configuration.
Error: Request failed with status code 500 (or other HTTP error code), but the underlying message was not an error.
The `isErrorMessage` configuration in `window-post-message-proxy` is not correctly identifying error responses from the receiving frame.
fixEnsure `window-post-message-proxy` is configured with `isErrorMessage: HttpPostMessage.isErrorMessage` during its instantiation to properly classify incoming messages as errors based on HTTP semantics.
Audit
Dependencies
window-post-message-proxyrequiredThis library requires an implementation of `IPostMessage` to handle the actual `window.postMessage` transport. `window-post-message-proxy` is the recommended and typical dependency for this.