nexus
Adapters

Chrome Extension

Configure extension contexts and target background scripts, content documents, or addressed extension pages.

@nexus-js/chrome connects Chrome extension contexts. Configure each participating context with its helper: usingBackgroundScript(), usingContentScript(), usingPopup(), or another exported context helper.

pnpm add @nexus-js/core @nexus-js/chrome

The getting started guide walks through a shared contract, background provider, and content-script caller.

Exact Targets

Use chromeTarget to address a background script, frame, document, built-in page, or custom extension page:

import { chromeTarget } from "@nexus-js/chrome";

const exactBackground = chromeTarget.background();
const exactContent = chromeTarget.contentDocument({
  tabId: 42,
  documentId: "document-1",
});
const exactOffscreen = chromeTarget.offscreenDocument();
const exactPopup = chromeTarget.popup({ windowId: 42 });
const exactPanel = chromeTarget.sidePanel({ windowId: 42 });
const exactOptions = chromeTarget.optionsPage();
const exactDevTools = chromeTarget.devToolsPage({ inspectedTabId: 42 });
const exactCustomPage = chromeTarget.extensionPage({ endpointId: "settings" });

For example, after application code identifies the document, a configured background context can acquire its provider:

import { chromeTarget, usingBackgroundScript } from "@nexus-js/chrome";
import { CaptureToken } from "./shared-contracts";

const backgroundNexus = usingBackgroundScript();
const tabId = 42;
const documentId = "document-1";

const connection = await backgroundNexus.connect({
  target: chromeTarget.contentDocument({ tabId, documentId }),
  where: (contextMeta) =>
    contextMeta.context === "content-script" && contextMeta.isVisible === true,
});
const capture = connection.get(CaptureToken);

The application owns active-tab selection and content-script injection. Pass the resulting address to Nexus. tabId, frameId, and documentId are platform addresses; verified sender facts are exposed through ChromeConnectionMeta, separately from peer-declared identity. Chrome supplies Port.sender on incoming ports only. An outgoing selected target is private adapter route state, not an independent observed.documentId for a where predicate to verify.

The content-script helper does not choose a service target. Pass chromeTarget.background() to connect when the content script needs the background session.

Built-In And Custom Pages

Built-in receiver helpers identify their local Chrome context independently from caller target selection. Use the matching target constructor when another context must actively connect to one instance:

Built-in contextReceiver helperCaller targetCaller-owned exact coordinate
Background scriptusingBackgroundScript()chromeTarget.background()None
Content scriptusingContentScript()chromeTarget.contentFrame({ tabId, frameId }) or chromeTarget.contentDocument({ tabId, documentId })tabId plus frameId or documentId
PopupusingPopup()chromeTarget.popup({ windowId })windowId
Options pageusingOptionsPage()chromeTarget.optionsPage()None; designated profile receiver
DevTools pageusingDevToolsPage()chromeTarget.devToolsPage({ inspectedTabId })inspectedTabId
Offscreen documentusingOffscreenDocument({ reason })chromeTarget.offscreenDocument()None; profile singleton
Side PanelusingSidePanel()chromeTarget.sidePanel({ windowId })windowId

For example, a side-panel entrypoint can provide its service without inventing an application route:

import { usingSidePanel } from "@nexus-js/chrome";
import { PanelToken } from "./shared-contracts";
import { panelService } from "./panel-service";

const panelNexus = usingSidePanel();
panelNexus.provide(PanelToken, panelService);

From a configured content script, background, or another extension page:

import { chromeTarget } from "@nexus-js/chrome";
import { PanelToken } from "./shared-contracts";

const connection = await contentNexus.connect({
  target: chromeTarget.sidePanel({ windowId: 42 }),
});
const panel = connection.get(PanelToken);

Define PanelToken once in shared code; the service implementation imports that same contract. The helper identifies the currently running Side Panel from its browser window internally. The target selects the browser window from the caller side. Chrome tab-specific or global panel configuration remains application UI configuration; Nexus targets the running Side Panel endpoint for a window and does not expose a tab-specific Side Panel target. Structural coordinates are routing inputs, not identity or authorization facts.

The other built-in helpers also identify their receiver independently of caller target selection: usingPopup() resolves its current windowId with windows.getCurrent(), usingDevToolsPage() reads chrome.devtools.inspectedWindow.tabId, and usingContentScript() receives its native frame/document route from Chrome. usingOptionsPage() is the designated profile receiver, while usingOffscreenDocument({ reason }) is the profile singleton. These helpers do not ask callers to repeat those facts as route IDs. Only one live usingOptionsPage() receiver may own the profile target. A second Options page fails readiness explicitly; after the owner closes, a replacement can acquire the target.

Opening a popup, opening or focusing options, opening or activating Side Panel, creating an offscreen document, opening DevTools, and injecting a content script are separate application or Chrome lifecycle operations. connect({ target }) only acquires or dials an already-created, ready receiver; it does not perform any of those operations. Popup reopenings create new sessions, so callers must reconnect after the old popup closes.

Custom extension pages have no adapter-owned structural address. Keep an application-owned endpointId only for usingExtensionPage or createExtensionPageConfig, and dial those pages with chromeTarget.extensionPage({ endpointId }):

const settingsNexus = usingExtensionPage(
  { context: "settings-page" },
  { endpointId: "settings" },
);

const settingsConnection = await contentNexus.connect({
  target: chromeTarget.extensionPage({ endpointId: "settings" }),
});

Keep custom addresses unique among live custom pages. Applications own custom address assignment, discovery, page creation, and readiness. A missing page is not opened automatically.

The adapter puts the destination in its native Port name and filters incoming ports before handing them to Core. Chrome still distributes runtime.connect() at extension scope; the name is an adapter routing label, not authentication or a Chrome-native unicast guarantee. Unrelated and nonmatching ports are ignored.

The routing responsibilities are intentionally split:

  • Application code chooses the target instance: it discovers caller-side windowId, inspectedTabId, tabId, frameId, and documentId values for exact targets, assigns custom endpointId values only to custom pages, starts pages, and waits for readiness. The receiver helper separately auto-identifies its local Chrome context where Chrome exposes that fact.
  • The Chrome adapter enforces platform capabilities and translates an explicit target into runtime.connect() or tabs.connect().
  • Nexus Core owns the handshake, authorization, connection lifecycle, RPC, and Relay after the native Port is selected.

Context metadata still identifies the peer after the Nexus handshake. Targets are routing, ContextMeta is identity, and policy remains authorization. An offscreen entrypoint uses the singleton target and does not accept an application route:

const offscreenNexus = usingOffscreenDocument({
  reason: "audio-processing",
});

The background connects to that singleton document:

const audioConnection = await backgroundNexus.connect({
  target: chromeTarget.offscreenDocument(),
});

Connection Capabilities

Local contextTargets it can dial
BackgroundExact content frame/document, built-in page, custom extension page
ISOLATED content scriptBackground, built-in page, custom extension page
Popup, options, side panel, DevTools, ordinary extension pageBackground, built-in page, custom extension page, exact content frame/document
Offscreen documentBackground, built-in page, custom extension page

Connections are bidirectional once established. Content scripts and offscreen documents cannot call tabs.connect() to initiate a content connection. Explicitly expose a gateway in a tab-capable context when an intermediate peer is required. Nexus does not add transparent multi-hop targets or force ordinary page-to-content calls through the background.

Multiple Connections

Use connectMulticast for a snapshot of already available connections, then get the service from each member:

const captures = await backgroundNexus.connectMulticast({
  where: (contextMeta, _connectionMeta) =>
    contextMeta.context === "content-script" && contextMeta.isVisible === true,
});
const resources = captures.get(CaptureToken);

Supply targets when Nexus must acquire the connections; do not call connect for each target first. Target acquisition is strict, while service availability remains a per-member Result. Handle a missing service alongside call failures:

const outcomes = await Promise.allSettled(
  resources.map(async ({ result }) => {
    if (result.isErr()) throw result.error;
    return await result.value.capture();
  }),
);

This assumes the shared CaptureToken contract declares capture(). Use native Promise results directly; a separate multicast proxy or report type is unnecessary.

Session Lifecycle

Navigation or context teardown invalidates the associated proxies and refs. Observe the acquired connection and acquire replacements after the new context is ready; see connection lifecycle.

Choose a frame target when the address is a frame slot, or a document target when the operation must remain tied to a specific document. Use that address consistently in a workflow: frame and document targets are distinct, and targeting the same context through both may produce multiple sessions. A document target does not silently switch to the replacement document after navigation.

Offscreen documents can dial background or page targets. Application code owns chrome.offscreen.createDocument() and its readiness coordination; usingOffscreenDocument({ reason }) configures Nexus but does not create the page. Likewise, runtime.openOptionsPage(), popup creation, Side Panel activation, and DevTools opening are separate lifecycle operations; target acquisition never performs them.

The addressed-port protocol requires all participating contexts to use the same adapter protocol version. Upgrade peers together; legacy unnamed Nexus ports are not accepted by the addressed protocol.

Transport Limits

The adapter automatically enables binary packets on Google Chrome 152+ when the MV3 extension opts into Structured Clone messaging in manifest.json:

{
  "manifest_version": 3,
  "message_serialization": "structured_clone"
}

The adapter checks the Google Chrome brand and major version through navigator.userAgentData.brands, together with the manifest setting. Older versions, other browser brands, missing Client Hints, and extensions without the opt-in use JSON packets with Base64-encoded binary attachments. Both paths support binary RPC values. Binary packets are copied; transferables remain unsupported. Packet mode is selected automatically; binaryPackets is not configurable.

Configure the frame, message, and aggregate buffering limits through the helper’s transport option. Defaults are 64 KiB, 16 MiB, and 64 MiB respectively:

usingBackgroundScript({
  transport: {
    maxFrameBytes: 64 * 1024,
    maxMessageBytes: 16 * 1024 * 1024,
    maxBufferedBytes: 64 * 1024 * 1024,
  },
});
Edit this page on GitHub