Manifest v3 background scripts/service worker on Firefox

Question

I'm trying to migrate my browser extension (that I expect to work on Chrome and Firefox) from manifest v2 to v3.

However, I am getting conflicting information about the background section. I did lots of research on google and stack overflow, and no one seems to agree on anything. Also, most information seems to be outdated. Of the best sources I found, lots of places mention that it should be migrated to service_worker (example), but it seems that Firefox should still use scripts instead (source).

But no matter what I do, I am getting errors. If I only use service worker:

"background": {
    "type": "module", // tried both with and without this option
    "service_worker": "background.ts"
}

The the build command from parcel is happy (seems to use parcel/transformer-webextension underneath), but web-ext fails catastrophically:

WebExtError: installTemporaryAddon: Error:
Error: Could not install add-on at '...':
Error: background.service_worker is currently disabled

Even if I provide the flag --firefox-preview which was supposed to fix this.

Which kinda makes sense, this well-written tutorial claims that Firefox is keeping using scripts for V3, just deprecating the persisent flag (which you can remove or set to false). That is fine, as I wasn't using that anyway.

"background": {
    "scripts": ["background.ts"],
    "persistent": false // `persistent` must either be false or omited; I tried both
}

In fact that is exactly how the official Firefox docs claim V3 should support.

But parcel complains that ^^^ Missing property service\_worker:

Ok, so let's try both:

"background": {
    "type": "module",
    "service_worker": "background.ts",
    "scripts": ["background.ts"]
},

But parcel is not happy, with Invalid Web Extension manifest:

So no matter what I try, I can't get both parcel and web-ext to be happy at the same time.

It seems that Chrome wants one thing, and Firefox wants another, but no matter what I try, I can't even run my extension on neither browser. So not only it seems I can't have a V3 extension for both browsers - I cannot have a V3 extension at all if I want to use both parcel and web-ext (which is indispensable afaik).

I am particularly concerned because according to official chrome sources, Manifest V3 is a "prerequisite for the Featured badge⁠" starting of now, and V2 will be removed by June.

So if I am already penalized for not using V3 now, and have less than 6 months to figure out how to, while none of the available tooling seems to support this version yet? I must be missing something...

---

Notes: these are the commands I am using to run parcel and web-ext:

        "watch": "parcel watch src/manifest.json --dist-dir distribution --no-cache --no-hmr",
        "start": "web-ext run --firefox-preview"

And these are the versions I am using, both the latest on NPM

        "parcel": "^2.8.2",
        "web-ext": "^7.4.0",

Nobe

Answer 1

Just faced the same problem:

• Chrome is not happy with background.scripts and insists on using background.service_worker
• Firefox doesn't support background.service_worker and wants background.scripts

Manifest v3 is developed by Google, so looks like Firefox team haven't fully implemented it yet. Firefox 109 is the first version to "support" manifest v3 (released on January 17).

I was able to quickly find these tickets 1 and 2 on bugzilla. Doesn't look like it will be fixed any time soon!

What makes matters even worse, Chrome doesn't accept new extensions to its store with manifest v2 any more! This could be the reason why Firefox team decided to enable Manifest v3 extensions even without service workers support.

web-ext is also developed by Mozilla, just having something like this:

"background": {
    "scripts": ["background.js"]
},

should allow you (no cross-browser compatibility!) to publish it to Firefox marketplace and use web-ext tool (it also has very verbose inbuilt lint subcommand ./node_modules/.bin/web-ext lint)

Amabil

So I ended up having two manifests, one for each browser, however I still can't use import in my background.js file in Firefox (it works fine in chrome with type: "module" added to service_worker block. – Volscian

FWIW, added a simple npm package for converting between the v3 flavors: github.com/brettz9/convert-manifest-format – Assegai

This answer is great to know why Firefox supports MV3 but not service workers. vite-plugin-web-extension.aklinker1.io/guide/… supports defining a single manifest.json that supports both MV2 & MV3 based on browser or alternatively, separate files. It uses web-ext and vite. Any property can be prefixed with{{platform}}, e.g. "{{chrome}}.service_worker": "src/background.ts", and "{{firefox}}.scripts": ["src/background.ts"]. – Calgary

For simple extensions and no bundler, templating of manifest.json might be enough. There is example here: github.com/jsnjack/surfly-protocol/commit/… . Makefile is used to build both Chrome and Firefox versions – Amabil

it doesn't look like V3 is supported by Firefox at all. Content scripts are not injected. Using V2 it is. – Barranca

@Barranca actually.. at least during temporarily loading an addon using about:debugging I can confirm, that the content.js is loading and working (Manifest V3). background.service_worker is not loaded though. – Placate

Answer 2

I looked through the parcel-bundler change history and Manifest V3 support was added in April, 2022 before Mozilla provided details of their Manifest V3 implementation, which does not include Chrome's addition of Service Workers to replace Background Pages.

Still today, Mozilla has only provided high level details on their vision for Manifest v3, which leaves Firefox's implementation half complete, and (notable to this post) distinct from Chrome's implementation when a background script is included.

This presents several issues for Parcel because their bundler relies on a consistent manifest standard to produce a single distributable that can be used across browsers. The issue you raised is valid and Parcel only supports Chrome's version of Manifest v3. The bigger problem is that Firefox will require a distinct manifest file from other browsers for the foreseeable future, and parcel-bundler only supports a single manifest file that must be named 'manifest.json'.

There is an open pull request to add support for multiple manifest files using distinct names, but it has not been merged yet (at the time of writing). I'm not sure how suitable this solution will be since the changes do not solve for this specific issue.

I opened a bug in the parcel-bundler repo to document the incompatibility with Firefox Manifest V3, but at the moment it is not possible to build a Manifest V3 extension for Firefox that includes background scripts using Parcel.

Wynn

your guthub issue was closed saying it has been completed in a PR... but the problem still occurs even using a version released after the PR merge :( – Pileous

Answer 3

Currently, Firefox continues to use scripts and Google Chrome continues to use service_worker.
In the latest Firefox/Google Chrome, no error will occur even if both are listed.

So let's try:

"background": {
    "service_worker": "background.ts",
    "scripts": ["background.ts"]
},

• Before Chrome 121, Chrome refuses to load a Manifest V3 extension with background.scripts or background.page present. From Chrome 121, their presence in a Manifest V3 extension is ignored.
• Before Firefox 120, Firefox did not start the background page if service_worker was present (see Firefox bug 1860304). From Firefox 121, the background page starts as expected, regardless of the presence of service_worker.

background - Mozilla | MDN

Refs: Proposal: declaring background scripts in a neutral way · Issue #282 · w3c/webextensions

Hobbes

Yes ! This should now be the approach since Firefox 121. – Realist

One of my extensions got rejected from Chrome Web Store review when I used this approach, and was only accepted after I removed the "scripts" line. This policy doesn't seem to be applied consistently (another extension was permitted), so I might have been able to appeal. – Trstram