Manifest V3 Migration Checklist

Replace "background.page" or "background.scripts" in manifest.json with "background.service_worker".

Service workers are ephemeral. Don't rely on global variables persisting between events.

Replace in-memory state with chrome.storage.local or chrome.storage.session for data that must survive service worker restarts.

Long-running timers won't work in a service worker. Use chrome.alarms for periodic tasks.

Service workers have no DOM. Move any document/window usage to content scripts or offscreen documents.

Ensure install/activate listeners are set up. Re-register event listeners on every service worker start.

MV3 unifies browser_action and page_action into a single "action" API.

Use chrome.scripting.executeScript() with the new options format.

The new API uses a similar pattern to executeScript.

Blocking webRequest is no longer available. Use declarativeNetRequest rules for request modification.

Most chrome.* APIs now support Promises. Migrate callback patterns for cleaner async code.

If your background needs DOM APIs (e.g., canvas, audio), create an offscreen document.

Host permissions are no longer listed under "permissions" in MV3. Use the separate "host_permissions" array.

Use optional_host_permissions to request access only when needed, reducing install friction.

The new scripting API requires an explicit "scripting" permission in the manifest.

chrome.alarms requires the "alarms" permission.

Clean up any permissions that are no longer needed after the migration.

MV3 prohibits executing code fetched from external servers. Bundle all JavaScript locally.

Dynamically evaluated code is not allowed. Refactor to use static code patterns.

Move inline scripts to separate .js files referenced with script src.

If a library requires eval (e.g., template engines), run it in a sandboxed page with limited capabilities.

MV3 uses "content_security_policy.extension_pages" instead of the flat "content_security_policy" string.

Set "manifest_version": 3 in manifest.json.

Load the unpacked extension in Chrome, exercise every feature, and check for console errors.

If the migration involved UI changes, capture fresh screenshots at 1280x800.

Mentioning MV3 can build user trust and signal active maintenance.

Let users know about the MV3 migration and any behavior changes in the release notes.

MV3 extensions may get faster review times. Double-check all permissions justifications before submitting.