Extension Migration

Extension Migration (MV2 → MV3)

Official migration guide: https://developer.chrome.com/docs/extensions/develop/migrate

> Consider framework adoption: When migrating MV2→MV3, consider adopting WXT or Plasmo for built-in MV3 support, auto-manifest generation, and modern tooling.

Workflow Overview

1. Audit existing MV2 extension (APIs, permissions, background scripts)
2. Update manifest_version to 3
3. Convert background page → service worker
4. Replace deprecated APIs (see Quick Reference below)
5. Update permissions, CSP, webaccessibleresources format
6. Migrate webRequest → declarativeNetRequest (if blocking)
7. Bundle any remote code locally
8. Test all functionality across Chrome versions
9. Submit to Chrome Web Store

Key Breaking Changes

| Area | MV2 | MV3 | |------|-----|-----| | Background | background.scripts/page | background.service_worker | | Browser action | browser_action / page_action | action | | Network blocking | webRequest (blocking) | declarativeNetRequest | | Script injection | tabs.executeScript(string) | scripting.executeScript({func/files}) | | Remote code | CDN scripts allowed | Must bundle locally | | CSP | String value | Object {extension_pages: "..."} | | Web accessible | string[] | object[] with matches field | | Host permissions | In permissions array | Separate host_permissions array | | URL helper | chrome.extension.getURL | chrome.runtime.getURL | | Persistent storage | localStorage | chrome.storage.local |

Migration Priority Checklist

• [ ] manifest_version: 3 set
• [ ] Background converted to service worker
• [ ] localStorage/sessionStorage → chrome.storage.*
• [ ] XMLHttpRequest → fetch
• [ ] setInterval/setTimeout → chrome.alarms
• [ ] browser_action/page_action → action
• [ ] tabs.executeScript → scripting.executeScript
• [ ] chrome.extension.getURL → chrome.runtime.getURL
• [ ] permissions host entries → host_permissions
• [ ] web_accessible_resources updated to object format
• [ ] content_security_policy updated to object format
• [ ] No remote code (CDN scripts, eval, string Function())
• [ ] webRequest blocking → declarativeNetRequest (if used)

Quick Reference: MV2 → MV3 API Map

chrome.extension.getURL()        → chrome.runtime.getURL()
chrome.extension.getBackgroundPage() → chrome.runtime.getBackgroundPage() [deprecated, use messaging]
chrome.tabs.executeScript()      → chrome.scripting.executeScript()
chrome.tabs.insertCSS()          → chrome.scripting.insertCSS()
chrome.browserAction.*           → chrome.action.*
chrome.pageAction.*              → chrome.action.*
webRequest (blocking)            → declarativeNetRequest
localStorage                     → chrome.storage.local
XMLHttpRequest                   → fetch()
setInterval (background)         → chrome.alarms
document/window (background)     → NOT available in service worker

Manifest Diff

// MV2
{
  "manifest_version": 2,
  "background": { "scripts": ["bg.js"], "persistent": false },
  "browser_action": { "default_icon": "icon.png" },
  "permissions": ["webRequest", "webRequestBlocking", "https://example.com/*"],
  "content_security_policy": "script-src 'self'; object-src 'self'",
  "web_accessible_resources": ["images/*.png"]
}

// MV3
{
  "manifest_version": 3,
  "background": { "service_worker": "bg.js" },
  "action": { "default_icon": "icon.png" },
  "permissions": ["declarativeNetRequest"],
  "host_permissions": ["https://example.com/*"],
  "content_security_policy": { "extension_pages": "script-src 'self'; object-src 'self'" },
  "web_accessible_resources": [{ "resources": ["images/*.png"], "matches": [""] }]
}

Reference Files

• [Breaking Changes](references/breaking-changes.md) — all changes with before/after code
• [Service Worker Migration](references/service-worker-migration.md) — background → SW guide
• [Network Request Migration](references/network-request-migration.md) — webRequest → declarativeNetRequest
• [Migration Checklist](references/migration-checklist.md) — step-by-step checklist with testing

Related Skills

• extension-manifest - MV3 manifest generation
• extension-testing - Testing after migration
• extension-security - Security audit post-migration

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: quangpl
• Source: quangpl/browser-extension-skills
• License: MIT

Install and usage instructions live in the source repository linked above.