Background scripts and MV3 service workers

​

Template examples

​

action

npx extension@latest create my-extension --template=action

pnpx extension@latest create my-extension --template=action

yarn dlx extension@latest create my-extension --template=action

bunx extension@latest create my-extension --template=action

deno run -A npm:extension@latest create my-extension --template=action

​

ai-chatgpt

npx extension@latest create my-extension --template=ai-chatgpt

pnpx extension@latest create my-extension --template=ai-chatgpt

yarn dlx extension@latest create my-extension --template=ai-chatgpt

bunx extension@latest create my-extension --template=ai-chatgpt

deno run -A npm:extension@latest create my-extension --template=ai-chatgpt

​

Background capabilities

​

Background script support

​

Sample background script declaration

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "1.0.0",
  "background": {
    "service_worker": "./scripts/background.ts"
  }
}

​

Development behavior

• Extension.js tracks service worker/source changes and can trigger hard extension reload.
• Manifest changes affecting background entries can trigger restart-required diagnostics.
• Browser launch plugins apply target-specific hard reload strategies (Chromium/Firefox).
• Extension.js treats structural entrypoint changes more strictly than regular module edits.

​

Firefox: service worker translated to an event page

​

Chromium: scripts translated to a service worker

​

Safari: a background page, not a service worker

// Throws on Safari and takes the whole background context with it.
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });

// Safe on every target.
chrome.sidePanel?.setPanelBehavior({ openPanelOnActionClick: true });

​

MV3 service worker lifecycle

• In-memory state can disappear between events.
• Design long-running work around events, not process permanence.
• Startup should stay small and predictable.
• Your code should restore important state from storage or recompute it safely.

​

Output behavior

• background/service_worker.js
• background/scripts.js

​

Module and classic notes

• background.type: "module" uses module worker semantics.
• Classic service worker mode uses importScripts-based chunk loading behavior.
• Avoid dynamic imports in background code that must load immediately on startup.

​

Runtime-loaded files

• importScripts(...) dependencies of classic service workers. String-literal arguments are resolved recursively (a dependency can call importScripts itself) against the emitted worker location, so worker-relative URLs keep working even though the worker moves to background/service_worker.js. WebAssembly sibling files loaded by wasm-bindgen glue (*_bg.wasm) ship alongside their loader.
• chrome.scripting.executeScript({files: [...]}) and insertCSS({files: [...]}) payloads. Files referenced only from files: arrays (not declared in manifest content_scripts) are copied verbatim at their extension-root paths.

​

Recommended architecture

• Keep the background entry thin and move feature logic into shared modules.
• Use the background context as the central coordinator for messaging, storage access, and browser API calls.
• Restore durable state from storage instead of assuming the background script stays running permanently.
• Use alarms, explicit event listeners, and small feature modules instead of one large startup path.

​

Common mistakes

• Treating the service worker like a permanently running server process.
• Keeping critical state only in memory.
• Doing expensive startup work on every event wakeup.
• Putting too much feature logic in popup or content-script code when it actually needs background-level browser API access.

​

Best practices

• Prefer background.service_worker for MV3-first extensions.
• Keep background entry files small and delegate logic to shared modules.
• Avoid expensive startup work in service workers; initialize lazily where safe.
• Treat manifest background field edits as structural changes in dev flow.
• Route privileged actions through validated message handlers.
• Store durable settings and caches in browser storage, not only in module-level variables.

​

Next steps

• Understand update outcomes in dev update behavior.
• Persist durable runtime state with Storage.
• Coordinate contexts with Messaging.
• Learn more about JavaScript in development.
• Continue with content scripts.
• Troubleshoot service worker behavior in Manifest V3 troubleshooting.