Building Chrome Extensions in 2025: Manifest V3, What Changed, and How to Get Started

Manifest V3 is now the required standard for Chrome extensions. Extensions still on Manifest V2 stopped being supported in early 2025. MV3 changes the extension architecture in ways that tripped up a lot of developers migrating from V2. Here's the current state.

The biggest architectural change: service workers

Manifest V2 used persistent background pages — long-running scripts that stayed active indefinitely. MV3 replaced these with service workers: event-driven, non-persistent scripts that spin up when needed and get terminated after a period of inactivity. This has a major consequence: you can't rely on in-memory state persisting between events.

Storing state in MV3

Since service workers can be killed anytime, don't store anything important in JavaScript variables. Use `chrome.storage.local` or `chrome.storage.session` for persistent state. `chrome.storage.session` clears when the browser closes. `chrome.storage.local` persists. Both are async and work across service worker restarts.

What you need in manifest.json

The minimum for an MV3 extension: `manifest_version: 3`, `name`, `version`, `description`. Add `background.service_worker` to register a background script. Add `action` with `default_popup` and `default_icon` for a toolbar button. Add `permissions` for things like `storage`, `activeTab`, or `scripting`.

Content scripts vs background scripts

Content scripts run in the context of a web page — they can read and modify the DOM. Background scripts (service workers) run separately with full extension API access but no DOM access. Communication between them uses `chrome.runtime.sendMessage()` and `chrome.runtime.onMessage.addListener()`. This separation is intentional and improves security.

The declarativeNetRequest change

MV2 allowed extensions to intercept and modify network requests arbitrarily (webRequest API with blocking). MV3 restricts this to declarativeNetRequest — a declarative rule-based system. This broke ad blockers initially; the community worked around it, but it's a real constraint. If you need to block or redirect specific requests, use declarative rules instead of programmatic interception.

Testing your extension

Go to chrome://extensions, enable Developer Mode, click 'Load unpacked,' and select your extension directory. Changes to content scripts require reloading the extension. Changes to the service worker may require restarting the entire extension. Use the 'Service Worker' link in the extension card to open DevTools for the background script.