chrome-ext-messaging

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

Pattern	Use Case	Lifecycle
sendMessage	One-off request/response	Single exchange, then done
connect / Port	Streaming data, monitoring	Persistent until disconnect

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>();