Add example using MV3 userScripts API #576

Rob--W · 2024-12-18T14:53:25Z

Description

Add example using MV3 userScripts API. And many other aspects of MV3 development, useful for #496.

Motivation

This example is part of the documentation of the userScripts API.

Additional details

User scripts in Manifest V3 w3c/webextensions#279 (History and links to API proposals)
https://bugzilla.mozilla.org/show_bug.cgi?id=1875475 ("[meta] Implement userScripts API in MV3")
https://bugzilla.mozilla.org/show_bug.cgi?id=1917000 ("Implement opt-in to userScripts API")

Related issues and pull requests

Rob--W · 2024-12-18T14:54:53Z

userScripts-mv3/manifest.json

+  "browser_specific_settings": {
+    "gecko": {
+      "id": "[email protected]",
+      "strict_min_version": "134.0a1"


Note: I put strict_min_version 134 because this is the first version of Firefox where the API landed, behind the extensions.userScripts.mv3.enabled preference. I may update it to 135 or 136 once we ship it by default on release.

erosman · 2024-12-18T17:02:04Z

Note: "host_permissions" should include "file:///*", as many users (myself included) run personal userScripts on local files.

Rob--W · 2024-12-18T17:25:56Z

Note: "host_permissions" should include "file:///*", as many users (myself included) run personal userScripts on local files.

This is a demo extension, not a full-fledged user script manager. For it to be a complete user script manager, it would have to define the full GM.* / GM_* APIs, and also have a better UI. That goes beyond demonstrating the extension APIs and is left as an exercise to the reader.

erosman · 2024-12-18T17:35:23Z

I understand.. the intension was to demonstrate that the MV3 userScripts API supports "file:///*" as well.

userScripts-mv3/manifest.json

dotproto

In this review I mostly identified small tweaks. The core functionality looks quite solid. Nice work, @Rob--W!

dotproto · 2025-01-06T18:59:50Z

userScripts-mv3/README.md

@Rob--W, if you want to publish this example before the 135, I think we should add some installation instructions to the README that mention that you need to enable extensions.userScripts.mv3.enabled in about:config.

userScripts-mv3/README.md

dotproto · 2025-01-06T19:28:59Z

userScripts-mv3/README.md

+
+## What it does
+
+This extension is an example of a [user script manager](https://en.wikipedia.org/wiki/Userscript_manager)


Nit: end the sentence with a period.

Suggested change

This extension is an example of a [user script manager](https://en.wikipedia.org/wiki/Userscript_manager)

This extension is an example of a [user script manager](https://en.wikipedia.org/wiki/Userscript_manager).

userScripts-mv3/background.js

dotproto · 2025-01-06T20:26:05Z

userScripts-mv3/background.js

+    let worldIds = scriptsToRemove.map(s => s.id);
+    await browser.userScripts.unregister({ worldIds });


Line 145 currently throws the following error:

Uncaught (in promise) Error: Type error for parameter filter (Unexpected property "worldIds") for userScripts.unregister.

Channel: Nightly
Version: 135.0a1 (2024-12-30) (aarch64)
OS: macOS 15.1 (24B83)

I looked through the current version of toolkit/components/extensions/schemas/user_scripts.json and the current version of UserScriptFilter only has a ids property.

It looks like this may be the result of some refactoring that occured during development. The script appears to work as expected if we change the body of the if clause as follows:

Suggested change

let worldIds = scriptsToRemove.map(s => s.id);

await browser.userScripts.unregister({ worldIds });

await browser.userScripts.unregister({ ids: scriptsToRemove });

Thanks for catching this! I've applied the suggestion and renamed scriptsToRemove to scriptIdsToRemove.

dotproto · 2025-01-06T20:56:14Z

userScripts-mv3/options.mjs

+    }
+  }
+
+  button.onclick = async () => {


I had to double check that re-assigning an onevent handler like this would remove the previous event handler, but it checks out! (mdn, whatwg spec)

examples.json

userScripts-mv3/README.md

rebloor · 2024-12-22T15:27:04Z

userScripts-mv3/README.md

+The extension is an example of a
+[user script manager](https://en.wikipedia.org/wiki/Userscript_manager).
+
+This covers the following aspects to extension development:


Suggested change

This covers the following aspects to extension development:

This example illustrates these aspects of extension development:

I accepted Simeon's suggestion below instead, which adds "demo" to get to This demo covers the following aspects to extension development:

Is this wording OK or is it preferable to use "illustrate"?

userScripts-mv3/README.md

rebloor · 2024-12-22T15:29:24Z

userScripts-mv3/README.md

+
+- Showing onboarding UI after installation.
+
+- Designing background scripts that can restart repeatedly with minimal


@Rob--W as we seem to make the assumption that this is going to be rendered as a markdown document (e.g. use of hyperlink in the introductory paragraph) is there any need to impose line breaks?

To make it easier to read when the file is not rendered.

userScripts-mv3/background.js

userScripts-mv3/README.md

userScripts-mv3/options.mjs

Rob--W

Thanks for the reviews and (comment) suggestions (@dotproto , @rebloor and @erosman). I have just applied them, with the changes visible at https://github.com/Rob--W/webextensions-examples/commits/82331d201638e099c597b04dd2d166f156713c97

I'm going to squash all commits into one to make it ready to merge.

Rob--W · 2025-01-15T22:04:19Z

userScripts-mv3/README.md

+The extension is an example of a
+[user script manager](https://en.wikipedia.org/wiki/Userscript_manager).
+
+This covers the following aspects to extension development:


I accepted Simeon's suggestion below instead, which adds "demo" to get to This demo covers the following aspects to extension development:

Is this wording OK or is it preferable to use "illustrate"?

Rob--W · 2025-01-15T22:05:06Z

userScripts-mv3/README.md

+
+- Showing onboarding UI after installation.
+
+- Designing background scripts that can restart repeatedly with minimal


To make it easier to read when the file is not rendered.

Rob--W · 2025-01-15T22:18:20Z

userScripts-mv3/background.js

+    // Pretend that userScripts was not available, so that if the permission is
+    // restored, that permissions.onAdded will re-initialize.


Rephrased to:

// Pretend that userScripts is not available, to enable permissions.onAdded // to re-initialize when the permission is restored.

Rob--W · 2025-01-15T22:28:44Z

userScripts-mv3/background.js

+    let worldIds = scriptsToRemove.map(s => s.id);
+    await browser.userScripts.unregister({ worldIds });


Thanks for catching this! I've applied the suggestion and renamed scriptsToRemove to scriptIdsToRemove.

Rob--W requested a review from dotproto December 18, 2024 14:53

Rob--W commented Dec 18, 2024

View reviewed changes

dotproto reviewed Jan 6, 2025

View reviewed changes

userScripts-mv3/manifest.json Show resolved Hide resolved

dotproto requested changes Jan 6, 2025

View reviewed changes

rebloor reviewed Jan 8, 2025

View reviewed changes

userScripts-mv3/README.md Outdated Show resolved Hide resolved

userScripts-mv3/options.mjs Outdated Show resolved Hide resolved

Rob--W commented Jan 15, 2025

View reviewed changes

Add example using MV3 userScripts API

5aefc8a

Rob--W force-pushed the userScripts-mv3-sample branch from 82331d2 to 5aefc8a Compare January 15, 2025 22:40

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add example using MV3 userScripts API #576

Add example using MV3 userScripts API #576

Rob--W commented Dec 18, 2024

Rob--W Dec 18, 2024

erosman commented Dec 18, 2024

Rob--W commented Dec 18, 2024

erosman commented Dec 18, 2024 •

edited

Loading

dotproto left a comment

dotproto Jan 6, 2025

dotproto Jan 6, 2025

dotproto Jan 6, 2025

Rob--W Jan 15, 2025

dotproto Jan 6, 2025

rebloor Dec 22, 2024

Rob--W Jan 15, 2025

rebloor Dec 22, 2024

Rob--W Jan 15, 2025

Rob--W left a comment

Rob--W Jan 15, 2025

Rob--W Jan 15, 2025

Rob--W Jan 15, 2025

Rob--W Jan 15, 2025


		## What it does

		This extension is an example of a [user script manager](https://en.wikipedia.org/wiki/Userscript_manager)

		let worldIds = scriptsToRemove.map(s => s.id);
		await browser.userScripts.unregister({ worldIds });

	let worldIds = scriptsToRemove.map(s => s.id);
	await browser.userScripts.unregister({ worldIds });
	await browser.userScripts.unregister({ ids: scriptsToRemove });

	This covers the following aspects to extension development:
	This example illustrates these aspects of extension development:


		- Showing onboarding UI after installation.

		- Designing background scripts that can restart repeatedly with minimal

		// Pretend that userScripts was not available, so that if the permission is
		// restored, that permissions.onAdded will re-initialize.

Add example using MV3 userScripts API #576

Are you sure you want to change the base?

Add example using MV3 userScripts API #576

Conversation

Rob--W commented Dec 18, 2024

Description

Motivation

Additional details

Related issues and pull requests

Choose a reason for hiding this comment

erosman commented Dec 18, 2024

Rob--W commented Dec 18, 2024

erosman commented Dec 18, 2024 • edited Loading

dotproto left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Rob--W left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erosman commented Dec 18, 2024 •

edited

Loading