Skip to content

ParleyJSCross-Window Communication

Type-safe, robust framework for window, tab, and iframe communication

Quick Example

javascript
import { Parley, SYSTEM_EVENTS } from 'parley-js';

// Parent window
const parley = Parley.create({
    allowedOrigins: ['https://child.example.com'],
    timeout: 5000,
});

// Connect to iframe
const iframe = document.getElementById('myFrame');
await parley.connect(iframe.contentWindow, 'child');

// Send message and wait for response
const response = await parley.send(
    'getData',
    { id: 123 },
    {
        targetId: 'child',
    }
);

console.log('Response:', response);
javascript
// Child iframe
const parley = Parley.create({
    allowedOrigins: ['https://parent.example.com'],
});

// Handle incoming messages
parley.on('getData', async (payload, respond) => {
    const data = await fetchData(payload.id);
    respond({ success: true, data });
});

// Connect to parent
await parley.connect(window.parent, 'parent');

Why ParleyJS?

ParleyJS simplifies the postMessage API with a clean, type-safe interface. It handles the complexity of cross-window communication so you can focus on building features.

Before ParleyJS:

javascript
// Complex origin validation
window.addEventListener('message', (event) => {
    if (event.origin !== 'https://trusted.com') return;

    // Manual message routing
    if (event.data.type === 'getData') {
        // Handle request
        const response = { id: event.data.id, data: result };

        // Send response back
        event.source.postMessage(response, event.origin);
    }
});

With ParleyJS:

javascript
parley.on('getData', async (payload, respond) => {
    const result = await fetchData(payload.id);
    respond({ success: true, data: result });
});

Enterprise Ready

  • Security: Origin validation, message sanitization, DoS prevention
  • Reliability: Timeout handling, connection monitoring, error recovery
  • Type Safety: Full TypeScript support with generics
  • Testing: 85%+ test coverage
  • Documentation: Comprehensive guides, API reference, and examples
  • Performance: Optimized for high-throughput scenarios

Use Cases

  • Micro-frontends: Coordinate independent frontend modules
  • iFrame widgets: Embed third-party widgets securely
  • OAuth flows: Popup-based authentication
  • Multi-window apps: Coordinate state across windows
  • Web Workers: Offload heavy computations
  • Analytics: Track events across embedded content

Next Steps

Released under the MIT License.