A user logs in through your extension's popup, closes it, reads an article for a minute, then clicks your toolbar icon again. They are logged out. Nothing in your code changed. Chrome shut down your background script after 30 seconds of idle time, and the auth token you kept in a global variable went with it. That one bug produces more "my extension randomly stopped working" tickets than anything else in Manifest V3.

Manifest V3 is the version of Chrome's extension platform that every Web Store extension now has to target. The manifest diff looks like a version bump and a few renamed keys. What actually changed is where your code lives, how long it stays alive, and what it may do to the requests passing through the browser. Google traded away extension power for lower memory use, a smaller attack surface and packages a reviewer can read in full. Once you see where each part of that trade lands, migration bugs stop looking random and you can predict them.

The background page became a service worker

In Manifest V2, a background page lived as long as the browser did. It was an invisible tab with a DOM and a JavaScript heap, so a variable set at startup was still there six hours later. Manifest V3 replaces it with an extension service worker. Chrome starts it when an event arrives and kills it after about 30 seconds without events. Your code no longer runs continuously. It runs when something wakes it up.

Three failures come out of this, and they show up in that order. Global state disappears: tokens, caches, the counter you incremented on every tab update. Long timers never fire: a ten-minute setTimeout dies with the worker at the 30-second mark. Wake-up events get dropped: if you register chrome.runtime.onMessage inside a .then() or after an await, Chrome has already dispatched the event that woke the worker before your listener existed. The fixes are dull and they work. Keep state in chrome.storage.session or chrome.storage.local, schedule work with chrome.alarms (30-second minimum period), and register every listener synchronously at the top of the file, before the first await.

A service worker has no DOM either. Code that ran DOMParser, played a notification sound or wrote to the clipboard from the background page now needs chrome.offscreen: a hidden document you create with a declared reason such as DOM_PARSER or AUDIO_PLAYBACK, talk to over runtime messaging, and close when done. Chrome allows one at a time. Skip it and the call doesn't throw a useful error. The feature just quietly stops doing anything.

Blocking requests became declaring rules

The most argued-over change is network filtering. In Manifest V2, the blocking form of webRequest handed every request to your JavaScript, which decided whether to cancel, redirect or rewrite it. Manifest V3 removed blocking webRequest for Web Store extensions and replaced it with declarativeNetRequest. You don't run code per request anymore. You give Chrome a list of JSON rules, and Chrome applies them in its own network stack.

For most extensions that's a good deal. Blocking a tracker domain, stripping a header or redirecting a URL pattern each fit in one rule, and matching happens without a round trip into your worker for every image and XHR. It breaks down when a decision needs something a rule can't see: a request body, a remote lookup, or state that lives in your code. The limits are concrete. Each extension gets a guaranteed 30,000 static rules, 30,000 dynamic rules and 1,000 regex rules, and the match syntax is URL patterns, resource types and headers, not arbitrary code. That's why content blockers with 100,000-entry filter lists were hit hardest. Read-only webRequest still works, so you can still observe traffic. Changing traffic now goes through rules.

No more code you didn't ship

Manifest V3 bans remotely hosted code. Everything your extension executes has to be in the package that went through review. A script tag pointing at your CDN is out, and the default content security policy blocks eval and new Function. You can still fetch JSON and config, but not logic. This is the rule that breaks extensions built around a server-side rules engine, and the ones that bundle a vendor analytics or A/B SDK which downloads its real code at runtime. Those SDKs fail at load time, and they often take the rest of the worker down with them.

The smaller API changes are mostly cleanup. browserAction and pageAction merged into a single action key. tabs.executeScript moved to chrome.scripting.executeScript, which takes a function or file instead of a code string. Host permissions moved into their own host_permissions field, which Chrome now shows users as a separate install warning. Most APIs return promises instead of taking callbacks. None of these are hard, but each fails in its own way when missed, which is why we wrote a step-by-step Manifest V2 to V3 migration guide instead of a find-and-replace list.

What this means for your extension today

A Manifest V2 extension no longer runs in current stable Chrome, and the Web Store won't accept one. So the question isn't whether to migrate. It's how much of the extension depended on the old model. An extension that reads the page and shows a popup ports in a few days. One that kept long-lived state in the background, rewrote requests in code or loaded logic from a server needs a redesign, and the cost of a Manifest V3 migration mostly follows that split.

You can size it in an hour by reading your background script with three questions. What state does it hold in memory? Which requests does it modify rather than just watch? What code does it load that isn't in the package? Each yes maps to a known pattern: storage-backed state, declarative rules, bundled logic. We've written those up in our Manifest V3 extension patterns. Then test like a user: open chrome://serviceworker-internals, stop the worker by hand, and use the extension cold. Most V3 bugs that never show up on a developer's always-busy machine show up on that first cold start.

Manifest V3 isn't a worse platform. It's a stricter one, and the constraints are documented. Extensions designed around them ship smaller packages, clear review faster and survive Chrome releases. Extensions that fight them keep failing in ways nobody can reproduce on demand. If yours is in the second group, that's the work our Chrome extension development practice does every week.

Questions, answered.

What is Manifest V3 in simple terms?

It is the current version of Chrome's extension platform, set by "manifest_version": 3 in manifest.json. It replaces always-on background pages with service workers that start on demand and stop after about 30 seconds idle, moves request blocking to declarativeNetRequest rules, and bans running code that wasn't shipped in the reviewed package.

Do Manifest V2 extensions still work in Chrome?

No. Chrome has removed Manifest V2 support from stable releases, and the Web Store no longer accepts V2 extensions. An extension that still targets V2 has to be migrated to reach Chrome users.

Why does my Manifest V3 extension lose its state?

Chrome shuts the service worker down after roughly 30 seconds without events, which wipes every in-memory variable. Keep anything that must survive in chrome.storage.session or chrome.storage.local, and use chrome.alarms instead of long setTimeout calls. Register event listeners synchronously at the top level too, or the worker misses the event that woke it.

Can Manifest V3 extensions still block or modify network requests?

Yes, through declarativeNetRequest rules that Chrome applies itself, capped at a guaranteed 30,000 static and 30,000 dynamic rules per extension. Read-only webRequest is still available for observing traffic. Logic that needs arbitrary code, a request body or a remote lookup per request has to be redesigned to fit rules.

Can a Manifest V3 extension load code from a server?

It can fetch data and configuration, but not executable logic. Remotely hosted scripts are banned, and the default content security policy blocks eval and new Function. Everything that runs must ship inside the reviewed package, including third-party SDKs.