Skip to main content

RuntimePort

RuntimePort is the universal message bus for the extension runtime, enabling cross-context messaging, lifecycle hooks, and extension reload.

Context​

  • Availability: Universal
  • Source: packages/ports/src/general/runtime/runtime.port.ts

Key Methods​

  • sendMessage(message: any): Promise<any> - Send a message to the extension's background listener and await a response.
  • onMessage(callback: (message: any, sender: webExt.runtime.MessageSender, sendResponse: (response?: any) => void) => void): () => void - Register a message listener, returns an unsubscribe function.
  • onSuspend(callback: () => void): void - Register a callback for service worker suspension.
  • reload(): void - Reload the entire extension.

Usage​

import { RuntimePort } from '@hexajs-dev/ports';
import { Injectable, HexaContext } from '@hexajs-dev/common';

@Injectable({ context: HexaContext.Background })
export class MessageRouterService {
  constructor(private readonly runtime: RuntimePort) {}

  initialize() {
    const unsubscribe = this.runtime.onMessage((message, sender) => {
      if (message.type === 'FETCH_CONFIG') {
        return { config: this.getConfig() };
      }
    });
    this.runtime.onSuspend(unsubscribe);
  }

  private getConfig() {}
}

API Reference Appendix​

Below is the exhaustive, auto-generated technical reference for all types, interfaces, and signatures associated with this API.

Classes​

RuntimePort​

import { RuntimePort } from '@hexajs-dev/ports';
class RuntimePort { ... }

Methods​

connect()

Opens a long-lived connection to another extension context (e.g. an offscreen document) using runtime.connect.

Unlike sendMessage, a dedicated port isolates its traffic from the shared one-shot message bus, so heavy worker RPC does not congest unrelated messaging (BUG-007).

connect(connectInfo?: HexaWebRuntimeConnectInfo): HexaWebPort

getURL()

getURL(path?: string): string

onConnect()

Registers a listener for incoming runtime.connect connections.

onConnect(callback: (port: HexaWebPort) => void): () => void

onMessage()

onMessage(callback: (message: any, sender: webExt.runtime.MessageSender, sendResponse: (response?: any) => void) => boolean | void): () => void

onMessageExternal()

onMessageExternal(callback: (message: any, sender: webExt.runtime.MessageSender, sendResponse: (response?: any) => void) => boolean | void): () => void

onSuspend()

onSuspend(callback: () => void): void

reload()

reload(): void

sendMessage()

sendMessage(message: any): Promise<any>