browser-tab-ipc

Lightweight cross-tab messaging library for TypeScript / JavaScript. Exchange messages between browser tabs with automatic transport selection and graceful fallback.

---

Browser Support

Transport	Chrome	Firefox	Safari	Edge	Notes
BroadcastChannel	54+	38+	15.4+	79+	Default — fastest, same-origin
SharedWorker	4+	29+	16+	79+	Cross-origin capable
SessionStorage	all	all	all	all	Universal fallback

---

Table of Contents

• Installation
• Quick Start
• How It Works
• API Reference
  • class BrowserTabIPC
  • ConnectionOptions
  • ConnectionState
  • TransportType
  • Events
• SharedWorker Setup
• Troubleshooting
• Contributing
• License

---

Installation

npm:

npm install @lopatnov/browser-tab-ipc

yarn:

yarn add @lopatnov/browser-tab-ipc

CDN (UMD, no bundler required):

<script src="https://lopatnov.github.io/browser-tab-ipc/dist/library.umd.min.js"></script>

---

Quick Start

import {BrowserTabIPC} from '@lopatnov/browser-tab-ipc';

const ipc = new BrowserTabIPC();

// Listen for messages from other tabs
ipc.message((data) => {
  console.log('Received:', data);
});

// Connect and send
await ipc.connect();
await ipc.postMessage({event: 'tab-opened', tabId: crypto.randomUUID()});

Open the same page in multiple tabs — every tab receives the message instantly.

---

How It Works

BrowserTabIPC tries each transport in order and uses the first one that connects successfully:

BroadcastChannel  →  SharedWorker  →  SessionStorage
    (fastest)          (flexible)       (always works)

You can override this by specifying a single transport or a custom fallback list via ConnectionOptions.

---

API Reference

class BrowserTabIPC

BrowserTabIPC extends Node's EventEmitter and provides a clean connect / send / receive interface.

new BrowserTabIPC(options?: ConnectionOptions)

Creates an instance. Options set here apply to all subsequent connect() calls.

import {BrowserTabIPC, TransportType} from '@lopatnov/browser-tab-ipc';

// Default — auto-selects from all three transports
const ipc = new BrowserTabIPC();

// Force a single transport
const ipc = new BrowserTabIPC({
  transportTypes: TransportType.broadcastChannel,
});

// Custom fallback chain
const ipc = new BrowserTabIPC({
  transportTypes: [TransportType.sharedWorker, TransportType.sessionStorage],
  sharedWorkerUri: '/ipc-worker.js',
});

connect(options?: ConnectionOptions): Promise<ConnectionState>

Establishes the connection. Options passed here are merged with constructor options.

const state = await ipc.connect({
  sharedWorkerUri: '/dist/ipc-worker.js',
  storageKey: 'my-app-channel',
  storageExpiredTime: 30_000,
});

console.log(state.connected); // true
console.log(state.type); // e.g. TransportType.broadcastChannel

disconnect(): Promise<ConnectionState>

Closes the active connection and cleans up all listeners and timers.

const state = await ipc.disconnect();
console.log(state.connected); // false

postMessage(message: any): Promise<void>

Broadcasts a serializable value to all connected tabs.

await ipc.postMessage('ping');
await ipc.postMessage({type: 'STORE_UPDATE', payload: {count: 42}});

Event subscription methods

Method	Trigger
message(callback)	A message was received from another tab
connected(callback)	Connection established successfully
connectionError(callback)	Connection attempt failed
disconnected(callback)	Connection was closed

ipc.message((data) => console.log('Message:', data));
ipc.connected((state) => console.log('Connected via', TransportType[state.type!]));
ipc.connectionError((state) => console.error('Connection failed:', state.error));
ipc.disconnected(() => console.log('Disconnected'));

You can also use the EventEmitter API directly with the exported event name constants:

import {EventMessage, EventConnected, EventConnectionError, EventDisconnected} from '@lopatnov/browser-tab-ipc';

ipc.on(EventMessage, (data) => {
  /* ... */
});
ipc.once(EventConnected, (state) => {
  /* ... */
});

---

ConnectionOptions

Option	Type	Default	Description
transportTypes	TransportType | TransportType[]	All three, in order	Transport(s) to try, left to right
sharedWorkerUri	string	GitHub CDN fallback URL	URL to ipc-worker.js (SharedWorker transport)
storageKey	string	'ipc'	Namespace prefix for SessionStorage keys
storageExpiredTime	number	30000	Message TTL in milliseconds (SessionStorage)

---

ConnectionState

Returned by connect() and disconnect(), and passed to event callbacks.

Field	Type	Description
type	TransportType | null	Active transport, or null if none connected
connected	boolean	Whether the connection is currently active
error?	unknown	Error detail when a connection attempt fails

---

TransportType

import {TransportType} from '@lopatnov/browser-tab-ipc';

TransportType.broadcastChannel; // BroadcastChannel API
TransportType.sharedWorker; // SharedWorker
TransportType.sessionStorage; // SessionStorage events

---

Events

Constant	When emitted
EventConnected	A transport connected successfully
EventConnectionError	A transport failed to connect
EventDisconnected	The connection was closed
EventMessage	A message arrived from another tab

---

SharedWorker Setup

The SharedWorker transport requires a worker script served from your own origin to avoid CORS issues. Copy the bundled file into your project:

cp node_modules/@lopatnov/browser-tab-ipc/dist/ipc-worker.js public/

Then point connect() to it:

await ipc.connect({sharedWorkerUri: '/ipc-worker.js'});

Without this step, the library falls back to a GitHub-hosted worker — which only works on the same origin as the CDN.

---

Troubleshooting

Module '"events"' can only be default-imported using the 'allowSyntheticDefaultImports' flag

Add to tsconfig.json:

{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true
  }
}

Messages are not received in other tabs

• All tabs must be on the same origin (protocol + host + port).
• BroadcastChannel and SessionStorage are strictly same-origin.
• SharedWorker can bridge origins if the worker file is served from the target origin.

SharedWorker fails silently

• Open DevTools → Application → Shared Workers and check for errors.
• Verify the sharedWorkerUri path is accessible from the browser (check for 404).
• If the file is missing, copy ipc-worker.js to your public/ folder as shown above.

Connection established but no messages arrive

• Both tabs must call connect() before any messages are sent.
• A tab does not receive its own messages — only other tabs do.

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request.

• Bug reports → open an issue
• Security vulnerabilities → GitHub Security Advisories (do not use public issues)
• Questions → Discussions
• Found it useful? A star on GitHub helps others discover the project

---

Built With

• TypeScript — strict typing throughout
• Rollup — bundled to ESM, CJS, and UMD formats
• BroadcastChannel API — primary transport
• SharedWorker API — cross-tab shared execution context
• Web Storage API — universal fallback transport
• Node.js EventEmitter — event-driven API
• Yarn — package management and script runner
• Babel — TypeScript transpilation pipeline for tests
• Puppeteer + Jest — cross-tab integration testing in a real browser
• ESLint + Prettier — linting and formatting

---

License

Apache-2.0 © 2019–2026 Oleksandr Lopatnov · LinkedIn