Firefox Extension Manifest V3 Migration: What Actually Changed

{ "permissions": ["https://api.example.com/*", "storage", "tabs"] }

// MV3 { "permissions": ["storage", "tabs"], "host_permissions": ["https://api.example.com/*"] }

### Service Worker Lifecycle & State Persistence
The biggest behavioral change is background scripts becoming service workers. Service workers:
1.  **Don't have access to the DOM**
2.  **Get terminated when idle** (no persistent state in memory)
3.  **Must use `self` instead of `window`**

// MV2 background script — this works window.myGlobalState = {}; setInterval(() => console.log('still alive'), 1000);

// MV3 service worker — this breaks // window is not defined in service worker scope // State is lost when the service worker stops

// Instead, persist state to storage self.addEventListener('message', async (event) => { const { type, data } = event.data; if (type === 'SAVE_STATE') { await browser.storage.session.set({ state: data }); } });

### Keeping a service worker alive
For new tab extensions, this is less of an issue since the new tab page itself is a foreground page with a normal DOM context. But if you need the background script:  

// Use alarms to keep the service worker alive browser.alarms.create('keepAlive', { periodInMinutes: 0.4 }); browser.alarms.onAlarm.addListener((alarm) => { if (alarm.name === 'keepAlive') { // Service worker is alive } });

### Content Security Policy Changes
MV3 tightened CSP:  

// MV2 — this was allowed { "content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'" }

// MV3 — unsafe-eval is NOT allowed in extension pages { "content_security_policy": { "extension_pages": "script-src 'self'; object-src 'self'" } }

This breaks libraries that use `eval()` — notably some templating engines and older versions of Angular.

### What Stayed the Same
For simple extensions like new tab pages, most things don't change:
- `chrome_url_overrides` (or `browser_url_overrides`) still works
- `browser.storage` API unchanged
- `browser.tabs` API unchanged
- Content scripts work the same way
- The extension popup works the same way

### Real-World Migration Example
Here's the before/after for Weather & Clock Dashboard:  

// Before (MV2) { "manifest_version": 2, "browser_action": {}, "permissions": ["storage"] }

// After (MV3) { "manifest_version": 3, "action": {}, "permissions": ["storage"] }

For this extension (pure new tab page, no background script, no remote code), the migration was literally two line changes.

## Pitfall Guide
1. **Assuming `window` or DOM Access in Service Workers**: Service workers execute in a dedicated worker context, not a window context. Accessing `window`, `document`, or DOM APIs will throw `ReferenceError`. Always use `self` and route UI interactions through message passing to content scripts or popups.
2. **Ignoring Service Worker Suspension**: Firefox terminates idle service workers to save resources. Any in-memory variables, caches, or timers are wiped. Rely exclusively on `browser.storage.session` or `browser.storage.local` for state that must survive suspension.
3. **Using `eval()` or `unsafe-eval` in Dependencies**: MV3 CSP strictly prohibits dynamic code execution. Libraries that compile templates at runtime or use `eval()` will fail silently or throw CSP violations. Pre-compile templates, use static bundling, or switch to CSP-compliant alternatives.
4. **Misplacing Host Permissions**: Firefox separates host patterns from standard permissions. Placing URLs in the `permissions` array instead of `host_permissions` results in silent authorization failures. Network requests to those hosts will be blocked without explicit error messages.
5. **Overusing Alarms to Keep SW Alive**: While `browser.alarms` with `periodInMinutes: 0.4` prevents suspension, it forces periodic wake-ups that increase battery/CPU usage. Use this pattern only for extensions requiring continuous background polling, and implement graceful degradation when possible.
6. **Deprecated `browser_action`/`page_action` Keys**: Firefox MV3 unifies toolbar and page-specific buttons under the `action` key. Legacy keys trigger manifest validation warnings or parsing errors. Update all references to use the unified `action` API and handle context via `browser.action` vs `browser.pageAction` equivalents if needed.

## Deliverables
**📘 MV3 Migration Blueprint**
- Architecture decision flowchart for background execution vs service worker lifecycle
- State persistence strategy matrix (session vs local vs in-memory)
- CSP compliance audit checklist for third-party dependencies

**✅ Pre-Launch Validation Checklist**
- [ ] `manifest_version` updated to `3`
- [ ] `browser_action`/`page_action` replaced with `action`
- [ ] Host URLs moved to `host_permissions` array
- [ ] Background scripts converted to `service_worker` format
- [ ] All `window` references replaced with `self` or message-passing patterns
- [ ] State persistence implemented via `browser.storage.session`
- [ ] CSP `unsafe-eval` removed and dependencies audited
- [ ] Alarm-based keepalive implemented only where strictly necessary
- [ ] Tested on Firefox 109+ with `about:debugging` service worker inspector

**⚙️ Configuration Templates**
- `manifest.json` MV3 baseline template with proper permission separation
- Service worker lifecycle boilerplate (message listener, storage fallback, alarm scheduler)
- CSP-compliant extension page configuration snippet
- Cross-browser compatibility wrapper for `browser` vs `chrome` API namespaces