A practical preflight checklist for Manifest V3 extension releases

MV3Replay — Sun, 30 Aug 2026 06:52:43 +0000

An extension can work perfectly in development and still fail after packaging. The risky change is often not in the feature code itself. It can be a permission that moved, a host pattern that expanded, a content script that now runs somewhere new, or a browser surface that was never included in the release checklist.

Here is the small preflight review I now use before testing an MV3 release.

1. Compare the packaged manifests

Compare the last version you actually shipped with the new packaged version, not only the source manifest.

Check separately:

required permissions;
optional permissions;
required host access;
optional host access.

A permission moving from optional to required deserves attention even if the set of permission names looks familiar.

2. List every browser surface

Turn the manifest into a list of things a person can interact with or that Chrome can start:

action popup;
options page;
side panel;
background service worker;
content scripts;
commands;
externally connectable pages;
declarative network rules;
web-accessible resources.

If a surface changed, add at least one release check for it. This sounds obvious, but it is easy to review the main popup while forgetting an options page or a host-specific content script.

3. Check where code can now run

For every content script, compare:

match patterns;
excluded matches;
frames;
execution world;
run timing.

The JavaScript file can be unchanged while one of these settings changes the extension's behavior on real sites.

4. Test the packaged build

Run the checklist against the same build directory that will be uploaded. A development build can hide packaging, path, minification, or generated-manifest differences.

At minimum, reload the packaged extension and exercise one path through each changed surface.

5. Record why each check exists

Instead of keeping a generic list such as â€œtest the popup,â€ connect each check to a release change:

host access expanded â†’ test the new host and confirm the old hosts still work;
service worker declaration changed â†’ test a cold start and a restart;
popup added â†’ test opening, closing, and the first message to the background;
web-accessible resource changed â†’ test both the intended page and an unintended page.

This makes the checklist smaller and easier to review than testing everything from memory on every release.

The small tool I am testing

I am building MV3 Replay. Its first piece is intentionally limited: a local command-line preflight check that reads an unpacked MV3 extension, lists its important surfaces, and compares two packaged versions.

It does not upload code, control the browser, collect analytics, or replace end-to-end testing. The purpose is to generate the checklist above more consistently.

I have not proven demand for it yet. If you maintain a Chrome or Edge extension and already compare builds or run a manual release checklist, I would value a blunt answer: would you try this local check on one release?

Disclosure: I am building MV3 Replay. This article explains the workflow behind the tool and is not a customer testimonial.