Chrome Extension Messaging

All extension contexts are strictly siloed — no shared memory. Communication happens exclusively through async message passing with JSON-serializable data. Choose the right pattern for each use case and enforce type safety through Protocol Maps.

Messaging Patterns

One-Time Request-Response

For standard async tasks (popup requests data from service worker, content script sends page data):

// Sender (popup or content script)
const response = await chrome.runtime.sendMessage({
  action: 'getData',
  query: 'recent',
});

// Receiver (service worker)
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
  if (msg.action === 'getData') {
    fetchData(msg.query).then(sendResponse);
    return true; // CRITICAL: keeps channel open for async response
  }
});

To send to a specific tab's content script:

chrome.tabs.sendMessage(tabId, { action: 'highlight', selector: '.target' });

Long-Lived Ports

For continuous data streams (live AI chat, progress tracking, persistent connections):

// Initiate connection
const port = chrome.runtime.connect({ name: 'ai-chat' });

// Send messages
port.postMessage({ prompt: 'Explain this page' });

// Receive responses
port.onMessage.addListener((msg) => {
  console.log('Response chunk:', msg.text);
});

// Detect disconnection
port.onDisconnect.addListener(() => {
  console.log('Connection closed');
});

When to Use Which

Type-Safe Messaging with Protocol Maps

Use @webext-core/messaging to define TypeScript-enforced message contracts:

// src/utils/messaging.ts
import { defineExtensionMessaging } from '@webext-core/messaging';

interface ProtocolMap {
  getData: (query: string) => DataResult;
  updateSettings: (settings: Settings) => void;
  getTabInfo: () => TabInfo;
}

export const { sendMessage, onMessage } = defineExtensionMessaging<ProtocolMap>();

Usage across contexts:

// Sender — compiler verifies payload and return types
const result = await sendMessage('getData', 'recent');

// Receiver — handler signature enforced by TypeScript
onMessage('getData', ({ data: query }) => {
  return fetchData(query); // Must return DataResult
});

Critical Async Rules

1. Return `true` for async responses. If the onMessage listener performs async work before calling sendResponse, the listener MUST return true to keep the message channel open.

1. Async functions always return a Promise. An async listener that doesn't explicitly return a value resolves to undefined, sending null to the sender and immediately closing the channel.

1. Handle the "no receiver" error. If a content script sends a message while the service worker is waking up, the message may be lost. Handle chrome.runtime.lastError explicitly.

Message Design Rules

• Include action property for routing
• Include to and from for multi-context routing
• Keep payloads JSON-serializable (no functions, DOM nodes, classes)
• Validate all messages from content scripts in the service worker

Additional Resources

Reference Files

• `references/messaging-patterns.md` — Advanced patterns: port management, React hooks, error handling, and multi-context routing