Browser Extension Development: A Manifest V3 Guide

Most extensions do not need a custom browser or an embedded engine. They need a well-built extension, and since Manifest V3 became the baseline across Chromium-based browsers, that means designing around a background model and a permissions model that behave differently from what many teams are used to from Manifest V2.

What actually changed in Manifest V3

Manifest V3 is not a cosmetic version bump. It changes three things that most extensions touch directly: how background logic runs, how network requests can be inspected or blocked, and how remote code is allowed to execute inside the extension.

None of these changes are arbitrary. Each closes a specific class of problem: background pages that held memory indefinitely, request-blocking code that could see and alter every byte of traffic, and remotely hosted code that could change behavior after an extension had already passed review.

Designing around the service worker lifecycle

The most common Manifest V3 migration bug is code that assumes the background context stays alive. A service worker is started for an event, and the browser is free to shut it down once it goes idle, often within seconds. Anything held only in a variable is gone when that happens.

1. 1

   Event wakes the worker

   A browser action click, alarm, message or network event starts the service worker if it is not already running.

2. 2

   Worker reloads its state

   On startup, the worker reads whatever it needs from chrome.storage or IndexedDB rather than assuming in-memory state survived.

3. 3

   Work runs to completion

   Asynchronous work is kept inside the event lifetime where possible, using chrome.alarms instead of setTimeout for anything long-running.

4. 4

   Worker goes idle

   With no pending events, the browser may terminate the worker at any time. Nothing important should depend on it staying resident.

In practice this means: persist anything that matters, avoid long-lived timers in the background context, and use chrome.alarms for scheduled work instead of a setInterval that assumes the worker will still be running later.

Network rules without blocking webRequest

declarativeNetRequest replaces most blocking use of webRequest with a set of rules the browser evaluates natively: match a URL pattern, then block, redirect or modify headers. It is fast and does not expose request bodies to your code, which is also why it cannot express everything a fully custom callback could.

• Straightforward ad and tracker blocking by URL pattern maps onto declarativeNetRequest cleanly.
• Rules that depend on inspecting response bodies or making a decision per request based on external state need a different design, often moved into a content script or a native messaging host.
• Dynamic rules can still be added and removed at runtime, so the rule set does not have to be fully static, but it is still a rules engine rather than arbitrary code in the request path.

Permissions: ask for less, ask at the right time

Manifest V3 makes it easier to request host permissions at runtime instead of declaring broad access in the manifest up front. Store reviewers and users both read the permissions list as a signal of how much an extension can see, and a narrower request list is both a better user experience and a smoother path through review.

A reasonable default approach

Request the narrowest permission that satisfies the current feature, using optional permissions for anything that only some users will need, and explain in the extension’s own UI why a permission prompt is appearing before the browser shows it.

Chrome, Edge, Brave, Firefox and Safari are not one target

Manifest V3 is a Chromium specification, and Edge and Brave inherit it directly since they share Chromium’s extension platform. Firefox implements the WebExtensions API that Manifest V3 is largely based on, but its manifest keys, background page options and store policies are its own. Safari is the furthest outlier.

If a single extension needs to reach all of these, plan for a shared core with a small per-browser packaging and manifest layer, rather than assuming one manifest file will work unmodified everywhere. Our pages on Chrome extension development, Firefox extension development and Safari extension development cover what changes for each target.

Before you submit for review

• Confirm the extension works with the service worker actually terminating between events, not just in a long-running local dev session where it happens to stay alive.
• Re-read the permissions list as a store reviewer would, and remove anything not used by a shipped feature.
• Test the update path: users update in place, and a service worker rewrite that silently drops stored state on upgrade is a common source of support tickets.
• Run the extension through a real QA pass across the browsers you target, not just the one you built it in. Our browser and extension QA and extension security review services exist for exactly this stage.

When an extension stops being enough

Extensions are the right tool for a large share of browser feature work, but the platform has real edges. If a requirement needs browser UI that extension APIs do not expose, network or process behavior that declarativeNetRequest cannot express, or policy enforcement across managed devices beyond what enterprise extension controls allow, that is usually a sign the work belongs in a custom browser build instead. Our guide to Chromium covers how that decision plays out in practice.