Manifest V3 Explained for Beginners

Every Chrome extension has a file called manifest.json that tells the browser what the extension is and what it can do. The "manifest version" is a field in that file specifying which generation of the Chrome extension platform you're targeting.

Manifest V3 (MV3) is the current generation. Google began enforcing it in 2023, and MV2 extensions are no longer accepted in the Chrome Web Store. If you're building today, you're building on MV3.

What changed from MV2

Service workers instead of background pages

MV2 extensions could run a persistent background page, a hidden web page that stayed loaded the entire time Chrome was open. MV3 replaces this with a service worker. The key difference: service workers are not persistent. They spin up when needed and shut down after a period of inactivity.

This matters because you can't store state in memory across events. If your extension needs to remember something between actions, you have to write it to chrome.storage explicitly.

No remote code execution

MV2 extensions could load JavaScript from a remote URL at runtime. MV3 prohibits this entirely. All code that runs must be bundled inside the extension package that gets reviewed by Google. This was a security change targeting extensions that loaded malicious code after passing review.

In practice: no more eval() on remote strings, no fetching and executing scripts from your server.

declarativeNetRequest replaces webRequest (for blocking)

MV2 had a webRequest API that let extensions inspect and block network requests programmatically. Adblockers relied on it heavily. MV3 replaces the blocking variant with declarativeNetRequest, where you declare a set of static rules describing which requests to block or redirect. The browser engine applies those rules, not your JavaScript.

The non-blocking (observational) webRequest still exists. Only the ability to intercept and block requests in JavaScript was removed.

What this means for building today

Most extensions are unaffected by these changes. If you're building something that injects a button into a webpage, reads the current tab's URL, or saves user preferences, MV3 is straightforward to work with. The service worker model only creates friction if you're doing complex background processing.

The declarativeNetRequest change primarily affects content filtering tools. If that's what you're building, you'll need to learn the rule format, which is more verbose than the old approach but also better documented than it was at launch.

Common gotchas

Forgetting storage is async. You can't read from chrome.storage synchronously. Everything is callback or promise-based, and since your service worker may have restarted, you need to fetch state fresh at the start of each event handler.

Service worker timeouts. If your background logic takes too long or sits idle, Chrome will terminate the service worker. If you're waiting on a long network request, the worker may be killed before it completes. Design around short-lived operations.

Content script injection timing. Declaring "run_at": "document_start" vs "document_end" vs "document_idle" matters more than beginners expect. Injecting too early means the DOM isn't ready; injecting too late means the user sees the page before your changes apply.

host_permissions vs activeTab. Many beginners put "host_permissions": ["<all_urls>"] in their manifest when they only need access to the current tab the user clicks on. Using activeTab permission instead is simpler, doesn't require the user to grant broad host access, and speeds up Chrome Web Store review.

Checking your manifest version

Open your manifest.json and look for this field near the top:

"manifest_version": 3

If it says 2, you're on a legacy version. Migrating mostly means converting your background page to a service worker and auditing for remote code execution.

---

If you'd rather describe what your extension should do and skip the manifest details entirely, Extension Coder generates MV3-compliant extensions from plain English.