# @livechat/postmessage > A library which makes [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) communication easier. It's responsible for: Latest version **0.3.6** (published 2025-11-06) · MIT license · 0 weekly downloads ## Install ```sh npm install @livechat/postmessage pnpm add @livechat/postmessage yarn add @livechat/postmessage bun add @livechat/postmessage ``` ## Health **Score 50/100 (C)** — status: stable. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.3.6 | | Published | 2025-11-06 | | First published | 2018-11-13 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 24 | | Unpacked size | 115 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | ziggykraus, andarist, konradk, walaszczykm, klarzynskik, jawinski, stanislaw-rakowski, yrobag, b.stiskun-text | ## Links - npm: https://www.npmjs.com/package/@livechat/postmessage - npm.io page: https://npm.io/package/@livechat/postmessage ## Dependencies (24) - [callbag-map](https://npm.io/package/callbag-map.md) ^1.0.1 - [callbag-lazy](https://npm.io/package/callbag-lazy.md) ^2.0.0 - [callbag-take](https://npm.io/package/callbag-take.md) ^1.0.0 - [callbag-defer](https://npm.io/package/callbag-defer.md) ^1.1.0 - [callbag-merge](https://npm.io/package/callbag-merge.md) ^2.0.0 - [callbag-retry](https://npm.io/package/callbag-retry.md) ^1.0.0 - [callbag-share](https://npm.io/package/callbag-share.md) ^1.0.2 - [@babel/runtime](https://npm.io/package/@babel/runtime.md) 7.28.4 - [@livechat/mitt](https://npm.io/package/@livechat/mitt.md) ^0.1.3 - [callbag-create](https://npm.io/package/callbag-create.md) ^2.0.1 - [callbag-filter](https://npm.io/package/callbag-filter.md) ^1.0.1 - [callbag-flatten](https://npm.io/package/callbag-flatten.md) ^1.7.0 - [callbag-subject](https://npm.io/package/callbag-subject.md) ^1.0.2 - [callbag-timeout](https://npm.io/package/callbag-timeout.md) ^1.0.1 - [callbag-debounce](https://npm.io/package/callbag-debounce.md) ^2.1.1 - [callbag-for-each](https://npm.io/package/callbag-for-each.md) ^1.0.1 - [callbag-from-event](https://npm.io/package/callbag-from-event.md) ^1.0.0 - [callbag-take-until](https://npm.io/package/callbag-take-until.md) ^2.0.0 - [callbag-to-promise](https://npm.io/package/callbag-to-promise.md) ^1.0.1 - [@livechat/dom-utils](https://npm.io/package/@livechat/dom-utils.md) ^0.2.5 - [callbag-throw-error](https://npm.io/package/callbag-throw-error.md) ^1.0.1 - [@livechat/data-utils](https://npm.io/package/@livechat/data-utils.md) ^1.0.2 - [callbag-last-element](https://npm.io/package/callbag-last-element.md) ^1.0.1 - [@livechat/promise-utils](https://npm.io/package/@livechat/promise-utils.md) ^1.0.1 ## Recent versions - 0.3.6 (latest) — 2025-11-06 - 0.3.4-2 (beta) — 2022-01-25 - 0.3.5 — 2023-07-31 - 0.3.4-1 — 2020-03-24 - 0.3.4-0 — 2020-03-23 - 0.3.3 — 2020-03-20 - 0.3.2 — 2020-03-09 - 0.3.2-1 — 2020-03-09 - 0.3.2-0 — 2020-03-09 - 0.3.1 — 2020-03-06 - 0.3.0 — 2020-03-06 - 0.3.0-0 — 2020-03-06 - 0.2.0 — 2019-09-06 - 0.1.0 — 2019-06-11 - 0.1.0-5 — 2019-06-11 - … 17 more at https://npm.io/package/@livechat/postmessage/versions ## README # @livechat/postmessenger A library which makes [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) communication easier. It's responsible for: - establishing a connection between a parent page and a child iframe, - allowing promisified remote procedure calls, - allowing events to be dispatched to the listener on the other side. It's using a custom protocol for a communication - it's using a distinct shape of passed frames. The protocol was designed with different frame types in mind (currently handshake, response, call & emit). Given global nature of `window.postMessage` communication, it annotates all sent frames with: - "unique" fingerprint (namespaced string), - owner ID (allows multiple copies of the library to coexist on a single page), - instance ID (allows multiple instances to be created on a single page). ## Terminology ### Handshake Handshake is the point in time when we know that the connection has been established and it's safe to send data between parties. Both sides of the communication receive a promise object which resolves after the so-called handshake. It's the point in time when we know that the connection has been established and it's safe to send data to the "other side". ### Model Object consisting of data & methods given to the initialization function. Data (plain values) are being sent to the "other side" and are given to the consumer on the "other side" when initialization promise resolves. Methods are being registered within instance and can be called remotely by the instance existing on the other side of the communication using `instance.call('methodName', ...args)`. ## Types ```ts type Api = { call: (method: string, ...args: any[]) => Promise, emit: (event: string, data: any) => void, off: (event: string, callback: (...args: any[]) => any) => void, on: (event: string, callback: (...args: any[]) => any) => void, once: (event: string, callback: (...args: any[]) => any) => void, } type Model = { [key: string]: string | number | (...args: any[]) => any } type Destroy = () => void type IframeInstance = { destroy: Destroy, frame: HTMLIFrameElement, promise: Promise } type ParentInstance = { promise: Promise } ``` ## API ### createIframe ```ts function createIframe( { container, url, targetOrigin, handshakeRetry, }: { container: string url: string targetOrigin?: string handshakeRetry?: { interval?: number; count?: number } }, model?: Model, ): IframeInstance ``` ### connectToParent ```ts function connectToParent( model?: Model, options?: { handshakeTimeout?: number }, ): IframeInstance ``` ## Inspired by - [postmate](https://github.com/dollarshaveclub/postmate) --- _Source: https://npm.io/package/@livechat/postmessage · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._