Extension Messaging

You are a browser extension developer. The user wants to set up two-way messaging between extension components (content scripts, background scripts, popups, and options pages).

What to check first

• Verify manifest.json exists and check its version (v2 vs v3 — messaging differs slightly)
• Run grep -r "chrome.runtime" . to see if messaging is already partially implemented
• Check browser console for Unchecked runtime.lastError messages that indicate messaging failures

Steps

1. Define message structure — create a consistent object shape with action and data properties that all components will use
2. In the receiving component, add a listener using chrome.runtime.onMessage.addListener() with a callback that checks the request.action and returns a response
3. In the sending component, use chrome.runtime.sendMessage() with your message object and handle the response in a callback
4. For content script to background messaging, use chrome.runtime.sendMessage() from content script and chrome.runtime.onMessage in background
5. For popup/options to background, use chrome.runtime.getBackgroundPage() (MV2) or chrome.runtime.sendMessage() (MV3) to reach the background script
6. Return true from the listener callback if you're sending an asynchronous response via sendResponse() callback
7. Handle errors with chrome.runtime.lastError checks in your response callbacks
8. Test messaging by logging to ensure messages arrive and responses return correctly

Code

// manifest.json (MV3 example)
{
  "manifest_version": 3,
  "name": "Messaging Extension",
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  },
  "content_scripts": [{
    "matches": ["<all_urls>"],
    "js": ["content.js"]
  }]
}

// background.js — listener setup
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  console.log("Message from", sender.url, ":", request);
  
  if (request.action === "getPageData") {
    const data = { title: "Retrieved Data", timestamp: Date.now() };
    sendResponse({ success: true, data });
  } 
  else if (request.action === "logEvent") {
    console.log("Event logged:", request.event);
    sendResponse({ success: true, message: "Event recorded" });
  }
  
  // Return true if async response needed
  return true;
});

// content.js — sending messages
function requestPageData() {
  chrome.runtime.sendMessage(
    { action: "getPageData", source: "content" },
    (response) => {
      if (chrome.runtime.lastError) {
        console.error("Message error:", chrome.runtime.lastError);

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change