How to Remove Orphaned Script after Chrome Extension Update

Problem

Unintentionally reloading a Chrome extension, particularly those in developer mode, can create orphaned content scripts. These scripts remain running in the background but lose communication with the rest of the extension, resulting in errors such as "extension context invalidated" and "unchecked runtime.lastError".

Solution

The orphaned content script can still receive DOM messages. To remove it:

1. Send Message from New Content Script:

• In the new, working content script, send a message to the orphaned script using window.dispatchEvent.
• Use a unique message identifier, such as orphanMessageId.

2. Unregister Listeners in Orphaned Script:

• In the orphaned script, define a listener for the orphanMessageId.
• Within this listener, unregister all previous listeners and nullify global variables.
• This makes the old script eligible for garbage collection.

3. Background Script:

• Re-inject the content script on extension reload/install.

4. Content Script:

• Use named functions for event listeners to preserve their references.
• Set a window.running property to indicate an active instance.
• When receiving the orphanMessageId, unregister listeners and mark the script as orphaned.

5. Popup Script:

• Check if a working content script is present before sending messages.
• Utilize ensureContentScript to ensure script injection.

Example Code:

background.js:

// Re-inject content script
chrome.runtime.onInstalled.addListener(() => {
  chrome.tabs.query({ active: true, currentWindow: true }, tabs => {
    chrome.tabs.executeScript(tabs[0].id, { file: 'content.js' });
  });
});

content.js:

// Orphaned script detection and cleanup
var orphanMessageId = chrome.runtime.id   'orphanCheck';
window.dispatchEvent(new Event(orphanMessageId));
window.addEventListener(orphanMessageId, unregisterOrphan);

// Register named listeners
chrome.runtime.onMessage.addListener(onMessage);
document.addEventListener('mousemove', onMouseMove);

// Orphan flag and cleanup function
window.running = true;

function unregisterOrphan() {
  if (chrome.runtime.id) {
    // Not orphaned
    return;
  }
  window.removeEventListener(orphanMessageId, unregisterOrphan);
  document.removeEventListener('mousemove', onMouseMove);
  try {
    chrome.runtime.onMessage.removeListener(onMessage);
  } catch (e) {}
  return true;
}

popup.js:

async function sendMessage(data) {
  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
  if (await ensureContentScript(tab.id)) {
    return await chrome.tabs.sendMessage(tab.id, data);
  }
}

async function ensureContentScript(tabId) {
  try {
    const [{ result }] = await chrome.scripting.executeScript({
      target: { tabId },
      func: () => window.running === true,
    });
    if (!result) {
      await chrome.scripting.executeScript({
        target: { tabId },
        files: ['content.js'],
      });
    }
    return true;
  } catch (e) {}
}