chrome-extension

A comprehensive guide for building, debugging, and publishing Chrome extensions with Manifest V3, structured as a routing document. The main file is read first to understand the architecture and decision points, after which only the relevant, self-contained reference file is loaded for implementation detail. Reference files cover manifest.json setup and versioning, the service worker lifecycle and state persistence, content scripts and isolated versus main world injection, messaging and RPC layers, UI surfaces (popup, options page, side panel, context menus, commands, notifications, omnibox, devtools panel), chrome.storage usage and quotas, network and CSP handling, permissions, web-accessible resources, TypeScript build setup, publishing to the Chrome Web Store, execution-context flow diagrams, and common debugging mistakes. It is aimed at AI coding agents and requires git and node, with declared tools spanning file edits and git, gh, and npm commands.

The architecture overview explains that an extension has up to five execution contexts that communicate by message passing: the service worker (background, no DOM, ephemeral, with access to all chrome.* APIs), the popup, options page, and side panel (all with full DOM and APIs), and, on the web page itself, the content script in an isolated world and a main world script in the page context. Diagrams show that the content script shares the DOM but has its own JS scope and chrome.runtime and chrome.storage access while being subject to CSP for network only, whereas the main world script has full page access but no chrome.* APIs and is fully subject to CSP. The two communicate via window.postMessage through the shared DOM.

Communication patterns are summarized in tables: chrome.runtime.sendMessage for one-shot request/response from any extension context to the service worker (the most common case), chrome.tabs.sendMessage for pushing data from the service worker to a specific tab by tabId, chrome.runtime.connect ports for bidirectional streaming and progress (including service worker to popup), and window.postMessage for bridging worlds on the same page. Because the service worker is ephemeral and cannot push directly to extension pages, the guide directs readers toward ports or chrome.storage.onChanged, which fires across all contexts simultaneously, and points to the execution-contexts reference for deeper flow diagrams and per-context capability and limit breakdowns. The skill explicitly states it should not be used for framework-specific questions.