chrome-ext-service-worker

Chrome Extension Service Workers

MV3 replaced persistent background pages with ephemeral, event-driven service workers. They wake to process events and terminate after ~30 seconds of inactivity. All in-memory state is lost on termination. Code must be structured around this fundamental constraint.

The Ephemeral Lifecycle

[Event occurs] → [Worker starts] → [Script executes top-to-bottom]
→ [Registered listeners fire] → [~30s idle] → [Worker terminates]
→ [All global variables lost]

Every handler must assume zero prior state. Rehydrate from storage at the start of every event.

Hard Rules

1. Register Listeners Synchronously at Top Level

The browser scans for listeners on the first turn of the event loop. Listeners inside promises, callbacks, setTimeout, or async functions will NOT be registered in time.

// CORRECT — synchronous, top-level
export default defineBackground(() => {
  chrome.runtime.onMessage.addListener(handleMessage);
  chrome.alarms.onAlarm.addListener(handleAlarm);
  chrome.runtime.onInstalled.addListener(handleInstall);
});

// WRONG — async, buried inside callback
export default defineBackground(async () => {
  await someSetup();
  // TOO LATE — worker may have already handled the event
  chrome.runtime.onMessage.addListener(handleMessage);
});

2. Never Use setTimeout/setInterval

Standard timers are canceled on termination. Replace with chrome.alarms:

// WRONG — unreliable
setTimeout(() => checkForUpdates(), 60000);

// CORRECT — survives worker restarts
chrome.alarms.create('check-updates', { periodInMinutes: 1 });
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'check-updates') checkForUpdates();
});

3. Never Store State in Global Variables

// WRONG — lost on restart
let userPrefs = {};

// CORRECT — persist to storage
async function getPrefs() {
  const { prefs } = await chrome.storage.local.get('prefs');
  return prefs ?? DEFAULT_PREFS;
}