@decentralchain/browser-bus

@decentralchain/browser-bus

Cross-window browser communication library for DecentralChain DApps and wallet applications.

Overview

Enables secure message passing between browser windows, tabs, and iframes using the postMessage API. Used for DApp-to-wallet communication, transaction signing popups, and multi-tab synchronization.

Part of the DecentralChain SDK.

Installation

npm install @decentralchain/browser-bus

Requires Node.js >= 24 and an ESM environment ("type": "module").

Quick Start

Parent window with iframe

import { Bus, WindowAdapter } from '@decentralchain/browser-bus';

const url = 'https://some-iframe-content-url.com';
const iframe = document.createElement('iframe');

WindowAdapter.createSimpleWindowAdapter(iframe).then((adapter) => {
  const bus = new Bus(adapter);

  bus.once('ready', () => {
    // Received message from iframe
  });
});
iframe.src = url;
document.body.appendChild(iframe);

Iframe side

import { Bus, WindowAdapter } from '@decentralchain/browser-bus';

WindowAdapter.createSimpleWindowAdapter().then((adapter) => {
  const bus = new Bus(adapter);

  bus.dispatchEvent('ready', null);
});

API Reference

Bus

Creates a bus instance for sending and receiving events and requests.

Constructor:

• adapter — an Adapter instance for the messaging transport
• timeout (optional) — default response timeout in milliseconds (default: 5000)

dispatchEvent(name, data)

Send an event to all connected Bus instances.

bus.dispatchEvent('some-event-name', jsonLikeData);

request(name, data?, timeout?)

Send a request and receive a response. Returns a Promise.

const result = await bus.request('some-method', jsonLikeData, 100);

on(name, handler)

Subscribe to an event.

bus.on('some-event', (data) => {
  // handle event
});

once(name, handler)

Subscribe to an event once.

bus.once('some-event', (data) => {
  // fires only once
});

off(eventName?, handler?)

Unsubscribe from events.

bus.off('some-event', handler); // Unsubscribe specific handler
bus.off('some-event'); // Unsubscribe all from 'some-event'
bus.off(); // Unsubscribe from everything

registerRequestHandler(name, handler)

Register a handler for incoming requests.

bus.registerRequestHandler('get-random', () => Math.random());

Handlers may return Promises:

bus.registerRequestHandler('get-data', () => Promise.resolve(someData));

WindowAdapter

Adapter implementation for cross-window communication via postMessage.

WindowAdapter.createSimpleWindowAdapter(iframe?, options?)

Factory method that creates a WindowAdapter for simple parent/iframe communication.

Adapter

Abstract base class for custom transport implementations.

Development

Prerequisites

• Node.js >= 24 (see .node-version)
• npm >= 10

Setup

git clone https://github.com/Decentral-America/browser-bus.git
cd browser-bus
npm install

Scripts

Command	Description
npm run build	Build distribution files
npm test	Run tests with Vitest
npm run test:watch	Tests in watch mode
npm run test:coverage	Tests with V8 coverage
npm run typecheck	TypeScript type checking
npm run lint	ESLint
npm run lint:fix	ESLint with auto-fix
npm run format	Format with Prettier
npm run validate	Full CI validation pipeline
npm run bulletproof	Format + lint fix + typecheck + test
npm run bulletproof:check	CI-safe: check format + lint + tc + test

Quality Gates

• ESLint with strict TypeScript rules
• Prettier formatting
• 90%+ code coverage thresholds
• Bundle size budget enforcement
• Package export validation (publint + attw)

Related packages

Package	Description
@decentralchain/signer	Transaction signing orchestrator
@decentralchain/cubensis-connect-provider	CubensisConnect wallet provider
@decentralchain/signature-adapter	Multi-provider signing adapter

Contributing

See CONTRIBUTING.md.

Security

To report a vulnerability, see SECURITY.md.

License

MIT — Copyright (c) DecentralChain