moai-platform-chrome-extension

Chrome Extension Manifest V3 Development

Quick Reference

Chrome Extension Manifest V3 Development Specialist enables building modern browser extensions with the latest Chrome platform APIs.

Auto-Triggers: Chrome extension projects detected via manifest.json with manifest_version 3, service worker files, content script declarations, chrome API usage patterns

Core Capabilities

Manifest V3 Platform:

• Service workers replace persistent background pages for event-driven architecture
• Remote code execution removed for enhanced security
• declarativeNetRequest replaces blocking webRequest for network filtering
• Promise-based API methods across all chrome.* APIs
• action API unifies browserAction and pageAction into single surface
• Supported in Chrome 88 and later

Process Architecture:

• Service worker runs as single event-driven background script terminating when idle
• Content scripts execute in web page context within isolated worlds
• Popup and side panel provide dedicated UI surfaces
• Options page provides extension settings interface
• DevTools panel extends Chrome Developer Tools

Communication Patterns:

• One-time messages between service worker and content scripts via sendMessage
• Long-lived connections via connect with port-based communication
• Cross-extension messaging through externally_connectable declaration
• Web page to extension messaging for verified origins

Security Model:

• Content Security Policy restricts script sources to self only
• No inline scripts or remote code execution permitted
• Permissions declare required API access at install time
• Optional permissions allow runtime-requested access with user consent
• Host permissions control web page access patterns

Context7 Documentation Access

For latest Chrome Extension API documentation, use the Context7 MCP tools:

Step 1 - Resolve library ID: Use mcp__context7__resolve-library-id with query "chrome extension" to get the Context7-compatible library ID.

Step 2 - Fetch documentation: Use mcp__context7__get-library-docs with the resolved library ID, specifying topic and token allocation.

Example topics include "manifest v3 configuration", "service worker lifecycle", "content scripts injection", "message passing patterns", "chrome.storage API", "side panel API", and "declarativeNetRequest rules".

---

Module Index

This skill uses progressive disclosure with specialized modules for detailed implementation patterns.

Core Modules

manifest-v3-reference covers the complete manifest.json field reference for Manifest V3 extensions. Topics include required and optional fields, field types and constraints, permission declarations, MV2 to MV3 migration notes, and extension configuration best practices.

service-worker-patterns covers service worker lifecycle, event registration, state management, and debugging. Topics include event-driven architecture, top-level listener registration, state persistence with chrome.storage, keep-alive strategies, offscreen documents for DOM access, and debugging with chrome://extensions.

content-scripts-guide covers content script injection methods, isolated worlds, and communication. Topics include static declaration in manifest, dynamic registration with chrome.scripting, programmatic injection, isolated world architecture, DOM access patterns, and security considerations.

messaging-patterns covers message passing between extension components. Topics include one-time messages with sendMessage, long-lived connections with connect and ports, async response patterns, cross-extension messaging, web page messaging, and error handling strategies.

apis-quick-reference covers the major chrome.* APIs with method signatures and permission requirements. Topics include chrome.runtime, chrome.tabs, chrome.storage, chrome.action, chrome.scripting, chrome.alarms, chrome.notifications, chrome.contextMenus, chrome.sidePanel, chrome.declarativeNetRequest, chrome.offscreen, chrome.identity, and chrome.commands.

ui-components covers popup, side panel, options page, DevTools panel, and content script UI. Topics include popup HTML and lifecycle, side panel configuration and API, options page patterns, DevTools extension integration, and injected UI from content scripts.

security-csp covers Content Security Policy, permissions model, and secure coding practices. Topics include CSP configuration for extension pages, minimum privilege permissions, input validation, XSS prevention, secure messaging patterns, and HTTPS enforcement.

publishing-guide covers Chrome Web Store submission and distribution. Topics include developer account setup, extension packaging, privacy policy requirements, review process, update mechanisms, and self-hosted distribution.

---

Implementation Guide

Manifest V3 Structure

Every Chrome extension requires a manifest.json file at the project root. Three fields are mandatory: manifest_version set to integer 3, name as the extension display name with maximum 75 characters, and version as a semver-compatible string.

The description field provides a summary shown in Chrome Web Store with maximum 132 characters. The icons object specifies PNG icons at 16, 32, 48, and 128 pixel sizes for various Chrome UI contexts.

For background processing, declare a service_worker field inside the background object as a single string path pointing to the service worker file. Set type to module when using ES module imports. The service worker path must be a single string, not an array.

Content scripts are declared as an array of objects, each specifying matches patterns for URL matching, js array for JavaScript files, optional css array for stylesheets, and run_at to control injection timing with values document_start, document_end, or document_idle.

For detailed field reference and migration guidance, see modules/manifest-v3-reference.md.

Service Worker Architecture

Service workers in Manifest V3 replace persistent background pages with an event-driven model. The service worker runs only when responding to events and terminates when idle, reducing memory and CPU consumption.

All event listeners must be registered at the top level of the service worker script. Listeners registered inside callbacks, promises, or async functions will not persist across service worker restarts.

Since service workers have no DOM access, no window object, and no localStorage, use chrome.storage API for persistent state. Use the Alarms API for scheduled tasks instead of setTimeout or setInterval, as these timers do not survive service worker termination. Use fetch for network requests instead of XMLHttpRequest.

For long-running operations that require DOM access, use the Offscreen Documents API via chrome.offscreen.createDocument to create a hidden document with DOM capabilities.

For complete service worker patterns and debugging guidance, see modules/service-worker-patterns.md.

Content Scripts

Content scripts execute JavaScript and CSS in the context of web pages. They run in isolated worlds, meaning they share DOM access with the host page but have separate JavaScript execution environments, preventing variable and function conflicts.

Three injection methods exist. Static injection declares scripts in the manifest content_scripts array with URL match patterns. Dynamic injection uses chrome.scripting.registerContentScripts for runtime registration. Programmatic injection uses chrome.scripting.executeScript to inject on demand, requiring either host_permissions or activeTab permission.

Content scripts have limited direct chrome API access: only dom, i18n, storage, and specific runtime methods including connect, sendMessage, onMessage, onConnect, getManifest, getURL, and id. All other API calls must go through message passing to the service worker.

For injection patterns, isolated world details, and security considerations, see modules/content-scripts-guide.md.

Message Passing Patterns

Extensions communicate between components using Chrome message passing. One-time messages use chrome.runtime.sendMessage to reach the service worker and chrome.tabs.sendMessage to reach content scripts. Each message receives a single response through a callback or Promise.

Long-lived connections use chrome.runtime.connect or chrome.tabs.connect to establish ports. Ports remain open until either side calls disconnect, a listener is removed, or the containing tab unloads. Ports support ongoing bidirectional communication.

For async responses in one-time messaging, the onMessage listener must either return true to indicate an async sendResponse call, or return a Promise directly starting from Chrome 144.

All messages use JSON serialization with a maximum size of 64 MiB. Never trust message content from content scripts as the host page context could be compromised.

For complete messaging patterns including cross-extension and web page communication, see modules/messaging-patterns.md.

Chrome APIs Reference

The chrome.runtime API provides extension lifecycle management, messaging, and manifest access. It handles installation, update, and suspend events, and provides methods for getting extension URLs and platform information.

The chrome.tabs API manages browser tabs with methods for querying, creating, updating, and removing tabs. The chrome.storage API provides three storage areas: local with 10 MB capacity, sync with 100 KB that synchronizes across signed-in devices, and session for in-memory storage that clears on browser restart.

The chrome.action API controls the toolbar button including badge text, icon, popup, and click handlers. The chrome.scripting API provides programmatic script and CSS injection into web pages.

The chrome.sidePanel API manages the extension side panel, a persistent UI surface alongside web content. The chrome.declarativeNetRequest API provides network request filtering using static and dynamic rules without blocking webRequest.

For complete API method signature

---

Content truncated.