Skip to main content

Browser-Agnostic Ports

Target Audience: Advanced Goal: Access every browser API through typed, injectable ports — and route messages across contexts — without coupling code to any single browser.

HexaJS ships the @hexajs-dev/ports package: a complete set of Promise-based, platform-agnostic wrappers for the browser extension API surface. Instead of scattering chrome.* / browser.* calls and platform checks throughout your code, you inject a port and call its methods. The CLI build swaps in the correct platform implementation automatically.

At a glance​

ContextPortsHighlights
General3Runtime messaging, i18n, extension URLs
Background22Tabs, Storage, Cookies, Downloads, Alarms, Notifications, WebRequest, Scripting, Permissions…
UI1DevTools panels
Content1Clipboard

29 built-in ports covering the full browser-API surface — all injectable, all typed, all cross-platform.

→ See the complete list with descriptions in the Ports Catalog.

Core principles​

  • Never call chrome.* / browser.* directly in application classes.
  • Use @hexajs-dev/ports and injected clients for every browser interaction.
  • Route request/response messages through background controller endpoints.
  • Keep code platform-agnostic; the CLI builds per target platform.

What you'll learn​

  • How the ports layer abstracts every browser API behind a single injectable interface.
  • How clients route messages across context boundaries via Bridged Routing.
  • How RuntimePort and other ports hide browser API differences at build time.
  • How to implement Custom Ports with platform switch logic when a built-in port doesn't exist for your use case.
  • How background acts as the router between UI/content contexts.

Platform build behavior: Platform-aware ports use __HEXA_PLATFORM__ for tree-shaking. See Build Pipeline for details.

Further reading​