iframe-link

iframe-link

Overview

iframe-link is a minimalist JavaScript and TypeScript library designed to facilitate seamless communication between an iframe and its parent page. By leveraging Promise-based remote procedure calls (RPC) and robust event messaging over window.postMessage, this library simplifies the implementation of bidirectional communication in web applications.

Key Features

• Bidirectional RPC: Enables method calls between the parent and iframe, enhanced with Promise resolution for better control.
• Event Messaging: Emit and listen to events efficiently, fostering real-time interaction between the parent and iframe.
• Ready/ACK Handshake: Ensures reliable communication by confirming readiness before initiating interactions.
• Simplified API: Focused on iframe communication, this SDK avoids unnecessary complexity, targeting the specific needs of developers.

Why Use iframe-link?

The standard postMessage method lacks a structured approach for handling messages, particularly in terms of request IDs, event routing, and synchronization. iframe-link addresses these gaps by encapsulating the complexities of inter-frame communication. This library minimizes the repetitive setup for each iframe and includes security features, ensuring communication occurs only between trusted origins.

Usage Example

Below are examples demonstrating how to set up iframe-link for both the parent and the iframe:

Parent Implementation

import { connectToIframe } from 'iframe-link';

type ChildApi = {
  getStatus(input: { userId: string }): Promise<{ online: boolean }>
};

const channel = connectToIframe<ChildApi>({
  iframe: '#profile-frame',
  origin: 'https://child.example.com',
  methods: {
    getTheme: async () => ({ accent: '#3b82f6' })
  }
});

channel.on('STATUS_CHANGED', console.log);

const child = await channel.promise;
await child.getStatus({ userId: '42' });

Child Implementation

import { connectToParent } from 'iframe-link';

type ParentApi = {
  getTheme(): Promise<{ accent: string }>
};

const channel = connectToParent<ParentApi>({
  allowedOrigins: ['https://app.example.com'],
  methods: {
    getStatus: async ({ userId }) => ({ userId, online: true })
  }
});

const parent = await channel.promise;
await parent.getTheme();

channel.emit('STATUS_CHANGED', { online: true });

API Overview

The following methods are available:

Considerations for Safety

• It is critical to configure specific trusted origins in production to prevent security vulnerabilities.
• Ensure that both the parent and child validate their communication origins to maintain secure interactions.
• Messages exchanged must be JSON-serializable, and method calls can accept one optional payload.
• The library does not include built-in timeout and cancellation mechanisms.

Conclusion

iframe-link provides a clean and effective solution for developers seeking to establish reliable iframe communication with minimal overhead. It streamlines interactions between the parent and iframe, supporting complex application scenarios while maintaining an easy-to-use interface.