Background

Centralize browser events, cross-surface messages, and work that must continue after a visible surface closes.

Add a background worker

In Settings → Surfaces, click Background. ChromeShip creates src/app/background/index.ts with a pre-configured message handler and registers type: "module" in the manifest.

Architecture

The generated worker provides the shared runtime layer for your extension. It:

Imports and runs the side panel behavior registration at the top (chrome.sidePanel.setOptions + setPanelBehavior) if the side panel surface is enabled.
Registers a message handler for inter-surface communication.
Acts as the console bridge — other surfaces forward their logs to it, and it streams them to the Studio.
Is built as an ES module (type: "module" in the manifest).

When product code does not need a background surface, ChromeShip can still provide its development bridge without adding that bridge to the production ZIP.

Message handling

Register handlers for messages from popup, side panel, and content scripts. The generated handler already knows about PING, GET_ACTIVE_TAB_INFO, and CONTENT_UI_MOUNTED — add your own types for product logic.

import { registerMessageHandler } from "@/shared/messaging";

registerMessageHandler(async (message) => {
  if (message.type === "FETCH_DATA") {
    const data = await fetchFromAPI();
    return { ok: true, data };
  }
  return { ok: false, error: "Unknown message type" };
});

Service worker lifecycle

Manifest V3 service workers are event-driven and Chrome may stop them when idle. Persist important state in Chrome storage and rebuild transient state whenever the worker wakes.

Console logs

Every console.log from the background worker appears in the Studio under Logs → Extension. No DevTools needed. Logs from popup, side panel, and options are forwarded through the background to the Studio automatically.