Simple iFrame messaging for Vue.
- Cross-origin iFrame IPC.
- Two-way messaging and async responses.
- The same API for parent and embedded pages.
- Multiple iframe connections on the same page.
- Vue 3 and TypeScript support.
$ npm install @devlsh/embed
Set up a host page at https://example.com and a client page at https://frame.example.com.
Use the same id in both components, otherwise they'll ignore eachothers messages.
import { type DefaultEventsMap } from '@devlsh/embed'; interface Yay { test: number; } export interface CustomEvents extends DefaultEventsMap { yay: (payload: Yay) => void; }
<template> <iframe ref="iframe" src="https://frame.example.com" title="Client page" sandbox="allow-scripts allow-same-origin" /> </template> <script setup lang="ts"> import { useEmbed, type DefaultEventsMap } from '@devlsh/embed'; import { shallowRef } from 'vue'; const iframe = shallowRef<HTMLIFrameElement>(); const host = useEmbed<CustomEvents>('host', { id: 'shared-id', iframe, remote: 'https://frame.example.com', }); host.events.on('yay', (payload) => { console.log(payload); }); onMounted(() => { void host.send<string>('hello-world', { hello: 'world' }); }); </script>
<template> <button type="button" @click="submit">Send event</button> </template> <script setup lang="ts"> import { useEmbed } from '@devlsh/embed'; interface HelloWorld { hello: string; } const client = useEmbed<CustomEvents>('client', { id: 'shared-id', remote: 'https://example.com', }); client.handle<HelloWorld>('hello-world', async ({ hello }) => { return hello === 'world' ? 'hey' : 'go away'; }); function submit() { client.post('yay', { test: 123 }); } </script>
| Option | Type | Default or required | Description |
|---|---|---|---|
id |
string |
Required | Shared connection ID for the host and client. Use a different ID for each iframe connection. |
timeout |
number |
15000 |
Request timeout in milliseconds. |
iframe |
Vue Ref<HTMLIFrameElement | undefined> |
Required in host mode | Reference to the host's iframe element. |
remote |
string |
'*' |
Remote origin for message checks and, when the target origin is readable, outgoing messages. See the security note below. |
debug |
boolean |
false |
Enable debug logs for the connection. |
By default, if you don't supply a remote, the library will process all incoming messages and send events that any party can recieve. By setting this to a URL (See above example), you can limit this and hugely reduce the impact it has on security.
Report bugs through issues or ask questions in Discussions. Report vulnerabilities privately as described in SECURITY.md.
For local development, pull requests, and other contributions, see the Contributing Guidelines.
@devlsh/embed is free and open-source software licensed under the MIT License.
devlsh.com · GitHub: @devlsh · X: @itsdevlsh