Wab Bridge

Web-Android Bridge (Wab) — a lightweight TypeScript/JavaScript library for bidirectional communication between a WebView and the native Android layer via postMessage. Provides a clean API for calling Kotlin/Java functions from JavaScript, with automatic channel detection.

Quick start

Install

npm install wab-bridge

Usage

Import once from your application entry point (e.g. main.ts, app.ts, or your WebView's index.html script):

ESM (recommended)

import "wab-bridge";

CJS

require("wab-bridge");

After import, the Wab object is available on window.Wab. No further setup is required — the bridge auto-detects the native communication channel (__Wab_Legacy__, __Wab_Listener__, or a MessageChannel port) and begins listening.

Calling native functions

// Synchronous call (blocking, via legacy channel)
const result = Wab.callFunction({
  name: "greet",
  params: { name: "World" },
});

// Asynchronous call (Promise-based)
const data = await Wab.callFunctionAsync({
  name: "fetchData",
  params: { url: "/api/status" },
});

// Get a value from the native side
const serverUrl = Wab.getValue({ name: "getServerUrl" });

Message listeners (onion model)

Add middleware-style listeners to intercept messages before they reach the default handler:

Wab.addMessageListener((event, next, stop) => {
  console.log("Received:", event.data);
  next(); // continue to the next listener
});

Wab.addMessageListener((event, next, stop) => {
  if (event.data.type === "spam") {
    stop(); // halt the chain
    return;
  }
  next();
});

Cleanup

Wab.destroy();

Removes all message and error listeners registered by the bridge.

Native side (Android / Kotlin)

The JavaScript side expects the Android WebView to inject one of the following communication channels before page load:

| Channel | window property | Type | |---|---|---| | Legacy | window.__Wab_Legacy__ | { postMessage(data: string): string } | | Listener | window.__Wab_Listener__ | { postMessage(data: string): void } | | MessageChannel | window.__Wab_Listener__ + a message event with "__setupPort__" and event.ports[0] | MessagePort |

If using the core (meb-core) Android library, these channels are set up automatically — no manual injection needed.

API reference

Wab.addMessageListener(listener)

Wab.removeMessageListener(listener)

Register/unregister an onion-model message listener. Listeners are called in order with (event, next, stop).

Wab.getValue(options): any

Synchronous value retrieval from native. options is a PostMessageBody with a name field.

Wab.getValueAsync(options): Promise<any>

Async version — requires a non-legacy channel (preferChannel >= 1).

Wab.callFunction(options): any

Synchronous native function call.

Wab.callFunctionAsync(options): Promise<any>

Async native function call, returns a Promise.

Wab.destroy()

Tears down all listeners and releases references.

Versioning

Follows the same version as the Android meb-core library.

License

Apache-2.0