Background

The background service worker runs behind the scenes — handles events, messaging, and long-lived logic.

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 background is the single egress point for extension-wide features. 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).

If no background surface is explicitly added, ChromeShip injects a dev background proxy automatically so messaging and the console bridge still work.

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

Background workers can be terminated by the browser when idle (typically after 30 seconds of inactivity). Use chrome.storage for persistent state — never rely on global variables surviving across worker restarts. All state must be persisted.

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.