Chrome Extension Tools

What is Chrome Manifest V3?

Manifest V3 is the current Chrome extension manifest format. Here is what changed from V2, which fields moved or disappeared, and how to check a manifest against the current rules.

The short version

manifest.json is the file that describes an extension: its name, its version, what it is allowed to do, and where its code lives. Manifest V3 is the current format. It keeps that job the same but tightens several things, mostly around what an extension can do to pages and to the browser itself.

An extension declares the format on the first line that matters:

"manifest_version": 3

Why it exists

The main driver was user trust. Manifest V2 gave extensions broad, permanent access — a blocking web request API, a persistent background page, host access decided at install time and rarely revisited. V3 narrows that: most network modification moves to declarative rules, background work moves to a service worker that can be suspended, and host permissions can be requested at the point of use rather than all up front.

What changed from V2

background became a service worker

A V2 background page — a hidden HTML page kept alive — is replaced by a service worker:

"background": { "service_worker": "background.js" }

The trade-off is that a service worker is terminated when idle, so long-lived state does not survive. Code that used to sit in memory must be restored, and persistent: true no longer exists. In practice this is the change that catches people: an MV2 extension moved naively will lose its state between events.

browser_action and page_action became action

Two separate toolbar keys collapsed into one:

"action": { "default_title": "…", "default_popup": "popup.html" }

Leaving browser_action in an MV3 manifest is one of the most common migration mistakes, and it does not throw an obvious error — the toolbar button simply does not appear.

Network blocking moved to declarativeNetRequest

The old webRequestBlocking model, where code saw and could rewrite each request, is replaced by declarativeNetRequest: a rules engine that blocks or redirects without your code ever seeing page content. It is faster and far narrower, which is the point.

Permissions split, and can be optional

Host patterns moved out of permissions into their ownhost_permissions list, and optional_permissions gainedoptional_host_permissions. An extension can now ask for access to a site when the user actually triggers the feature, rather than at install time. This is why reading the three lists separately — which thePermission Checker does — is worth the effort.

web_accessible_resources changed shape

V2 listed strings:

"web_accessible_resources": ["images/*.png"]

V3 uses objects with a resources list, usually constrained by matches:

"web_accessible_resources": [{ "resources": ["images/*"], "matches": ["https://example.com/*"] }]

The content security policy is an object

V2 took a string. V3 expects an object keyed by surface:

"content_security_policy": { "extension_pages": "script-src 'self'; object-src 'self'" }

What has not changed

  • name and version are still required, and version format rules are the same.
  • content_scripts still uses matches, js and css.
  • icons, commands and externally_connectable work as before.
  • The archive layout is unchanged: manifest.json at the root of a ZIP, wrapped in a CRX for distribution.

Version strings are stricter than people expect

version must be a string of one to four dot-separated integers, each 0–65535, with no leading zeros. So "1.0.0" and "2.10" are fine, while"v1.0.0", "1.0.0-beta" and "01.2" are rejected. It is also a common mistake to write it as a JSON number, which is a different type entirely.

Checking a manifest

The Manifest V3 Validator checks the structural and type rules described above and reports each finding with the field, the problem and a fix. It is an independent checker written against Chrome's published documentation — not Google's internal validator, and not a substitute for loading the extension.

To read a manifest rather than judge it, use theManifest Viewer. To get an orientation on a whole extension, use the Extension Inspector.

Where the authoritative answers are

Chrome's own documentation is the source of truth for all of the above, and it moves. The manifest reference, the MV3 migration guide, and the service worker and permissions pages are linked from each finding the validator reports, so you can check a rule rather than take it on trust.

Tools for this