Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Manifest V3 and Why It Exists

Understand Manifest V3: service workers instead of background pages, no remote code, declarativeNetRequest, host permissions, and how to migrate old extensions.

You will meet two numbers when you read extension tutorials: Manifest V2 and Manifest V3. They describe the version of the extension platform, set by "manifest_version" in manifest.json. Chrome no longer accepts new V2 extensions and has turned off existing ones, so everything you write today is Manifest V3 (MV3). Old tutorials, Stack Overflow answers and code you find may still be V2, so you need to recognize the differences.

Why a new version?

Chrome's goals for MV3 were security, privacy and performance:

  • Security. Extensions can no longer execute remotely hosted code, so a store review sees everything the extension can run.
  • Privacy. Broad access to every site became something users approve and can change per site.
  • Performance. A permanent background page keeps memory in use even when nothing happens; a service worker sleeps.

The changes were debated, especially for ad blockers, but the rules below are what you work with.

The big changes

Area Manifest V2 Manifest V3
Background code Persistent or event page (background.page / scripts) Service worker (background.service_worker)
Toolbar button browser_action / page_action One action key
Host access Mixed into permissions Separate host_permissions
Remote code Allowed with limits Not allowed
Blocking requests webRequest with blocking handlers declarativeNetRequest rules
Page scripts tabs.executeScript scripting.executeScript
Web-accessible files A simple list Objects with resources and matches
API style Callbacks Callbacks and Promises
Content Security Policy A single string An object with extension_pages
flowchart LR
    subgraph V2["Manifest V2"]
        BP["Background page<br/>always alive, has DOM"]
    end
    subgraph V3["Manifest V3"]
        SW["Service worker<br/>wakes on events, no DOM"]
    end
    BP -->|migrate| SW

The background page became a service worker: the single biggest rewrite.

Promises instead of callbacks

V2 APIs took callbacks. MV3 APIs return promises when you leave the callback out, so you can use await:

JavaScript
// V2 style (still works for many APIs)
chrome.storage.local.get("count", (result) => {
  console.log(result.count);
});

// V3 style
const { count } = await chrome.storage.local.get("count");
console.log(count);

This course uses async/await throughout. When you hear "callback or promise?", the answer in MV3 is almost always promise.

No remote code

In V2 an extension could load a script from a CDN and run it. In V3 the following are all forbidden:

  • <script src="https://cdn.example.com/lib.js"> in an extension page;
  • eval() and new Function() in extension pages and the service worker;
  • inline event handlers such as onclick="...";
  • importScripts() of a remote URL in the service worker.

You must bundle libraries inside the package. Data is a different matter: fetch("https://api.example.com/data.json") is fine as long as you do not execute the response as code.

What did not change

Most of what you learned about the web still applies: HTML, CSS, DOM, fetch, modules. Content scripts, popups and options pages work the same. Permissions still exist and chrome.storage, chrome.tabs, chrome.alarms behave as before.

A migration checklist as code

The stand-in below scans a (V2-looking) manifest object and lists the changes needed. This is the kind of work a migration involves.

JS What must change in this V2 manifest?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The same manifest, migrated

Here is the V3 result of that migration. Look at how it differs.

JSON
{
  "manifest_version": 3,
  "name": "Old Timer",
  "version": "0.9",
  "permissions": ["tabs", "storage", "declarativeNetRequest"],
  "host_permissions": ["https://*.example.com/*"],
  "background": { "service_worker": "bg.js" },
  "action": { "default_popup": "popup.html" },
  "web_accessible_resources": [
    { "resources": ["img/logo.png"], "matches": ["https://*.example.com/*"] }
  ],
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'"
  }
}

Promise-or-callback helper

Sometimes you must support both styles. This stand-in shows how a promisified API behaves, using a fake chrome.storage that supports both.

JS Callback and promise, same API

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What replaces the persistent background page in Manifest V3?

    MV3 uses an event-driven service worker declared with background.service_worker, which has no DOM and is stopped when idle.
  2. 2. Which of these is NOT allowed in Manifest V3 extension pages?

    Remotely hosted code is forbidden. Libraries must be bundled in the package, although fetching data is fine.
  3. 3. Where do URL access patterns like "https://.example.com/" go in MV3?

    MV3 separates API permissions (permissions) from site access (host_permissions).

Summary

  • Manifest V3 is the only version you can publish today; V2 is retired.
  • The background page became an event-driven service worker.
  • browser_action/page_action became action, and host patterns moved to host_permissions.
  • No remote code: bundle libraries; fetching data is allowed.
  • APIs return promises, so async/await works.

Next: manifest.json Basics