Chrome Extension Manifest V3: What You Need to Know

Google's push to Manifest V3 has been controversial, but it's here to stay. After migrating my Keyword Scout extension, I learned valuable lessons about the new architecture.

Major Changes

1. Service Workers Replace Background Pages

The biggest change is moving from persistent background pages to service workers that can be terminated when idle.

// manifest.json
{
  "manifest_version": 3,
  "background": {
    "service_worker": "background.js"
  }
}

2. No More Remote Code Execution

All code must be bundled with the extension. This affects:

• External scripts (must be bundled)
• Inline scripts (must move to separate files)
• eval() and similar functions (prohibited)

3. Declarative Net Request API

The webRequest API is being replaced with declarativeNetRequest for better privacy and performance.

Migration Strategy

Step 1: Update Manifest

{
  "manifest_version": 3,
  "name": "My Extension",
  "version": "2.0",
  "permissions": ["storage", "activeTab"],
  "host_permissions": ["https://*.example.com/*"]
}

Step 2: Refactor Background Scripts

Service workers don't have access to DOM or window object. Store data using chrome.storage API:

// Store data
await chrome.storage.local.set({ key: value });

// Retrieve data
const { key } = await chrome.storage.local.get('key');

Step 3: Handle Service Worker Lifecycle

Since service workers can be terminated, use alarms for periodic tasks:

chrome.alarms.create('myAlarm', { periodInMinutes: 5 });

chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'myAlarm') {
    // Do periodic work
  }
});

Common Pitfalls

1. Assuming persistence: Don't rely on global variables; they'll be lost when the service worker terminates
2. Synchronous storage: chrome.storage is now promise-based; use async/await
3. Content script injection: Use scripting API instead of tabs.executeScript

Benefits

Despite the migration pain, V3 brings real improvements:

• Better performance (service workers use less memory)
• Enhanced security (no remote code execution)
• Improved privacy (declarative net request)
• Modern JavaScript (native promises, async/await)

Conclusion

Manifest V3 requires rethinking extension architecture, but the result is more robust and efficient. Start migrating now—V2 extensions will eventually be deprecated.