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.

dotproto · 2025-01-06T19:06:26Z

userScripts-mv3/README.md

+A user script manager, demonstrating the userScripts API, the permissions API,
+`optional_permissions`, and Manifest Version 3 (MV3).
+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:


Reword to fix a grammar issue and for clarity. Currently the intro sentence is incomplete.

Suggested change

A user script manager, demonstrating the userScripts API, the permissions API,

`optional_permissions`, and Manifest Version 3 (MV3).

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:

The extension is an example of a

[user script manager](https://en.wikipedia.org/wiki/Userscript_manager). It

demonstrates the userScripts API, the permissions API, `optional_permissions`,

and Manifest Version 3 (MV3).

This demo covers the following aspects to extension development:

dotproto · 2025-01-06T19:08:14Z

userScripts-mv3/README.md

+- Minimizing the overhead of background script startup, which is especially
+  relevant because event pages .


Reword to make this comment more applicable to other browsers. It also addresses the fact that other browsers may also support service workers in the future.

Suggested change

- Minimizing the overhead of background script startup, which is especially

relevant because event pages .

- Minimizing the overhead of background script startup. This is relevant because

Manifest Version 3 extensions uses an event-based background context.

NOTE: If you accept this suggestion, you should also update this line with a similar change.

Correcting grammar in suggestion

Suggested change

- Minimizing the overhead of background script startup, which is especially

relevant because event pages .

- Minimizing the overhead of background script startup. This is relevant because

Manifest Version 3 extensions use an event-based background context.

dotproto · 2025-01-06T19:12:48Z

userScripts-mv3/README.md

+- Monitoring an optional (userScripts) permission, and dynamically registering
+  events and scripts based on its availability.


Reword for clarity. The parenthetical should appear after the entire phrase that it applies to.

I tend to prefer to include the quotation marks when referring to a permission. That said, I don't know if we have an established pattern one way or the other.

Suggested change

- Monitoring an optional (userScripts) permission, and dynamically registering

events and scripts based on its availability.

- Monitoring grants for an optional permission (`"userScripts"`), and

dynamically registering events and scripts based on its availability.

dotproto · 2025-01-06T19:27:20Z

userScripts-mv3/README.md

+- Monitoring an optional (userScripts) permission, and dynamically registering
+  events and scripts based on its availability.
+
+- Using the `userScripts` API to register, update and unregister code.


Optional: clarify that the extension is specifically operating on user scripts rather than arbitrary code.

Suggested change

- Using the `userScripts` API to register, update and unregister code.

- Using the `userScripts` API to register, update and unregister user script

code.

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).

dotproto · 2025-01-06T19:33:25Z

userScripts-mv3/background.js

+    userScriptsAvailableAtStartup = false;
+
+    // Clear cached state, so that ensureUserScriptsRegistered() will refresh
+    // the registered user scripts if the permissions is granted again.


Suggested change

// the registered user scripts if the permissions is granted again.

// the registered user scripts if the permission is granted again.

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 });

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)

rebloor · 2024-12-22T15:23:18Z

examples.json

    "javascript_apis": [
      "userScripts.register",
      "runtime.onMessage",
      "runtime.sendMessage"
    ],
    "name": "user-script-register"
  },
+  {
+    "description": "A user script manager, demonstrating the userScripts API, permissions API, optional_permissions and Manifest Version 3 (MV3).",


Suggested change

"description": "A user script manager, demonstrating the userScripts API, permissions API, optional_permissions and Manifest Version 3 (MV3).",

"description": "A user script manager demonstrating the userScripts API, permissions API, optional_permissions, and Manifest Version 3 (MV3).",

rebloor · 2024-12-22T15:26:10Z

userScripts-mv3/README.md

+A user script manager, demonstrating the userScripts API, the permissions API,
+`optional_permissions`, and Manifest Version 3 (MV3).
+The extension is an example of a
+[user script manager](https://en.wikipedia.org/wiki/Userscript_manager).


Suggested change

A user script manager, demonstrating the userScripts API, the permissions API,

`optional_permissions`, and Manifest Version 3 (MV3).

The extension is an example of a

[user script manager](https://en.wikipedia.org/wiki/Userscript_manager).

This is an example [user script manager](https://en.wikipedia.org/wiki/Userscript_manager) that demonstrates the userScripts API, the permissions API,`optional_permissions`, and Manifest Version 3 (MV3).

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:

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

userScripts-mv3/README.md

+
+This covers the following aspects to extension development:
+
+- Showing onboarding UI after installation.


Suggested change

- Showing onboarding UI after installation.

- Showing an onboarding UI after installation.

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?

rebloor · 2024-12-22T16:27:40Z

userScripts-mv3/background.js

+
+  // Now we have computed the changed scripts, apply the changes in this order:
+  // 1. Unregister obsolete scripts.
+  // 2. Reset / configure worlds.


Suggested change

// 2. Reset / configure worlds.

// 2. Reset or configure worlds.

rebloor · 2024-12-22T16:27:55Z

userScripts-mv3/background.js

+  // Now we have computed the changed scripts, apply the changes in this order:
+  // 1. Unregister obsolete scripts.
+  // 2. Reset / configure worlds.
+  // 3. Update / register new scripts.


Suggested change

// 3. Update / register new scripts.

// 3. Update or register new scripts.

rebloor · 2024-12-22T16:28:27Z

userScripts-mv3/background.js

+  // 3. Update / register new scripts.
+  // This order is significant: scripts rely on world configurations, and while
+  // running this asynchronous script updating logic, the browser may try to
+  // execute any of the registered scripts when a website loaded in a tab or


Suggested change

// execute any of the registered scripts when a website loaded in a tab or

// execute any of the registered scripts when a website loads in a tab or

rebloor · 2024-12-22T16:28:58Z

userScripts-mv3/background.js

+    await browser.userScripts.unregister({ worldIds });
+  }
+
+  // 2. Reset / configure worlds.


Suggested change

// 2. Reset / configure worlds.

// 2. Reset or configure worlds.

rebloor · 2024-12-22T16:29:32Z

userScripts-mv3/background.js

+
+  // 2. Reset / configure worlds.
+  if (scripts.some(s => s.worldId)) {
+    // When a userscripts need privileged functionality, we run them in a


Suggested change

// When a userscripts need privileged functionality, we run them in a

// When a userscripts need privileged functionality, run them in a

Shouldn’t that be "When a userscript needs" or "When userscripts need"?

rebloor · 2025-01-08T02:05:26Z

userScripts-mv3/README.md

+- Minimizing the overhead of background script startup, which is especially
+  relevant because event pages .


Correcting grammar in suggestion

Suggested change

- Minimizing the overhead of background script startup, which is especially

relevant because event pages .

- Minimizing the overhead of background script startup. This is relevant because

Manifest Version 3 extensions use an event-based background context.

rebloor · 2025-01-08T02:08:34Z

userScripts-mv3/options.mjs

+}
+
+/**
+ * Shows the form where the user can edit or create a new user script.


Suggested change

* Shows the form where the user can edit or create a new user script.

* Shows the form where the user can edit or create a user script.

Add example using MV3 userScripts API

dc0d4cc

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

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

rebloor Jan 8, 2025

dotproto Jan 6, 2025

dotproto Jan 6, 2025

dotproto Jan 6, 2025

dotproto Jan 6, 2025

dotproto Jan 6, 2025

dotproto Jan 6, 2025

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

rebloor Dec 22, 2024

erosman Jan 8, 2025

rebloor Jan 8, 2025

rebloor Jan 8, 2025

		- Minimizing the overhead of background script startup, which is especially
		relevant because event pages .

		- Monitoring an optional (userScripts) permission, and dynamically registering
		events and scripts based on its availability.

	- Using the `userScripts` API to register, update and unregister code.
	- Using the `userScripts` API to register, update and unregister user script
	code.


		## What it does

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

	// the registered user scripts if the permissions is granted again.
	// the registered user scripts if the permission is granted again.

		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 });

	"description": "A user script manager, demonstrating the userScripts API, permissions API, optional_permissions and Manifest Version 3 (MV3).",
	"description": "A user script manager demonstrating the userScripts API, permissions API, optional_permissions, and Manifest Version 3 (MV3).",

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


		This covers the following aspects to extension development:

		- Showing onboarding UI after installation.

	- Showing onboarding UI after installation.
	- Showing an onboarding UI after installation.


		- Showing onboarding UI after installation.

		- Designing background scripts that can restart repeatedly with minimal

	// 2. Reset / configure worlds.
	// 2. Reset or configure worlds.

	// 3. Update / register new scripts.
	// 3. Update or register new scripts.

	// execute any of the registered scripts when a website loaded in a tab or
	// execute any of the registered scripts when a website loads in a tab or

	// When a userscripts need privileged functionality, we run them in a
	// When a userscripts need privileged functionality, run them in a

	* Shows the form where the user can edit or create a new user script.
	* Shows the form where the user can edit or create a user script.

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

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

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