Migrating a Chrome extension from MV2 to MV3: what broke, how I fixed it, and what I'd do differently

Google's Manifest V3 deadline is here. If you have a Chrome extension still running on MV2, you're on borrowed time.

I migrated PR Focus (and two other extensions) from MV2 to MV3. Nothing broke catastrophically — but several things surprised me.

Here's what I learned, so you don't have to figure it out the hard way.

---

The big changes

1. Background pages → Service workers

This is the biggest shift. In MV2, background scripts run continuously. In MV3, they're service workers that sleep when idle.

What broke:

• Persistent connections (like WebSockets) needed reconnection logic.
• Timers and intervals didn't survive sleep cycles.
• Global state wasn't preserved between events.

How I fixed it:

• Replaced setInterval with chrome.alarms (which wakes the service worker).
• Stored state in chrome.storage.local instead of in-memory variables.
• Added reconnection logic for WebSocket connections.

Code example:

javascript
// MV2 — background script (runs forever)
setInterval(() => {
  checkForNewPRs();
}, 60000);

// MV3 — service worker (can sleep)
chrome.alarms.create('checkPRs', { periodInMinutes: 1 });
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'checkPRs') {
    checkForNewPRs();
  }
});

2. Remote code execution is dead
MV3 completely bans remote code execution. No more eval(), new Function(), or loading scripts from external URLs.

What broke:

Dynamic script injection (if you were using it).

Remote code fetching (like loading a script from a CDN).

How I fixed it:

Bundled everything locally.

Replaced dynamic evaluation with explicit imports.

Used chrome.scripting.executeScript() with local files instead of stringified code.

3. Host permissions are now optional
MV2 required all permissions up front. MV3 lets you request permissions at runtime.

What changed:

Users can install without granting all permissions.

You can request sensitive permissions (like tabs or activeTab) only when needed.

How I used it:

PR Focus only requests activeTab when the user opens the popup.

No scary permission prompts at install time.

4. WebRequest blocking is gone
MV3 removed blocking capabilities from webRequest API. You can't intercept and modify requests anymore.

What broke:

Ad blockers and request-modifying extensions.

How I worked around it:

PR Focus doesn't need this API, so no change required. But if you're using it, you'll need declarativeNetRequest instead — which is less powerful and more restrictive.

What I'd do differently
1. Test with the service worker lifecycle earlier
The service worker sleep behavior is hard to debug. I spent days chasing issues that only appeared after 5 minutes of inactivity. Lesson learned: test the idle behavior early.

2. Use chrome.storage.local for everything
MV2 let me rely on in-memory state. MV3 doesn't. I should have moved all state to storage.local from day one. Now I have a mix of both, and it's messy.

3. Plan for the permission model
MV3's runtime permission model is a feature, not a bug. I should have designed PR Focus with optional permissions from the start. Instead, I had to refactor.

The migration checklist
Here's what I'd recommend for any MV2→MV3 migration:

Replace background.scripts with background.service_worker in manifest.json.

Convert background scripts to service workers (no window, no document).

Move all state to chrome.storage.local.

Replace setInterval/setTimeout with chrome.alarms.

Remove all eval() and new Function() calls.

Test service worker idle behavior.

Move permissions to optional where possible.

Use chrome.scripting instead of chrome.tabs.executeScript.

Update host_permissions to match the new model.

Final thoughts
MV3 isn't as bad as the early complaints suggested. The service worker model is better for performance and battery life. The permission model is better for privacy.

But the migration takes time. Don't wait until the last minute. Start now.

If you're migrating a Chrome extension and get stuck, I'm happy to help. [Drop me an issue on GitHub.](https://github.com/projekta2/pr-focus-landing/issues)