Bug 1943050 - new `userScripts` API content #38073

rebloor · 2025-02-10T02:00:41Z

Description

Addresses the documentation needs of Bug 1943050 Enable userScripts API by default by adding the documentation for the user script, API and related APIs.

Related issues and pull requests

Moving old API to legacy: #37975 (comment)
Addition of related browser compatibility data:

Legacy version compatibility data Data for legacy version of webextension.api.userScripts browser-compat-data#25857
New version compatibility data Bug 1943050 new webExtension.api.userScripts browser-compat-data#25913
Extension workshop updates: Bug-1943050 userScripts API permissions content mozilla/extension-workshop#2013

github-actions · 2025-02-10T15:38:38Z

Preview URLs (21 pages)

Flaws (11)

Note! 18 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime
Title: runtime
Flaw count: 1

macros:
- Can't resolve /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/onserScriptConnect

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/MessageSender
Title: runtime.MessageSender
Flaw count: 1

macros:
- Can't resolve /en-US/docs/Mozilla/Add-ons/WebExtensions/API/port/sender

URL: /en-US/docs/Mozilla/Firefox/Releases/136
Title: Firefox 136 for developers
Flaw count: 9

broken_links:
- /en-US/docs/Web/API/document/referrer is ill cased
- /en-US/docs/Glossary/asynchronous is ill cased
- /en-US/docs/Web/API/document/cookie is ill cased
- /en-US/docs/Web/URI/Schemes/data is a redirect
macros:
- Macro produces link /en-US/docs/Web/API/document/referrer which is a redirect
- Macro produces link /en-US/docs/Glossary/asynchronous which is a redirect
- Macro produces link /en-US/docs/Web/API/document/cookie which is a redirect
- Macro produces link /en-US/docs/Mozilla/Add-ons/WebExtensions/API/contextMenus/update which is a redirect
- Macro produces link /en-US/docs/Mozilla/Add-ons/WebExtensions/API/contextMenus/remove which is a redirect

External URLs (2)

URL: /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts
Title: userScripts

https://developer.chrome.com/docs/extensions/reference/api/userScripts (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Mozilla/Firefox/Releases/136
Title: Firefox 136 for developers

https://bugzil.la/1943050 (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-02-22 16:52:59)

Rob--W

Could you rebase your PR on the (presumably final) state of the legacy documentation move? Then I can more easily compare the difference with this link: https://github.com/rebloor/content/compare/Bug-1943050-userScripts-API-move-legacy-content..Bug-1943050-userScripts-API-new-content

Rob--W · 2025-02-18T14:10:59Z

files/en-us/mozilla/add-ons/webextensions/api/runtime/onuserscriptconnect/index.md

+
+{{Compat}}
+
+> [!NOTE]


Let's delete all of this copyright etc stuff (in every article related to userScripts).

The userScripts API is designed together with me in the WECG; we don't need to call out Chromium's source and license header here.

Rob--W · 2025-02-18T14:15:46Z

files/en-us/mozilla/add-ons/webextensions/api/runtime/onuserscriptconnect/index.md

+    - `port`
+      - : {{WebExtAPIRef('runtime.Port')}}. An object connecting the current script to the other context.
+
+## Examples


Let's delete this full example. It is inaccurate and incomplete, and I'd like to get the primary doc completed without being blocked on the example.

Missing userScripts.configureWorld() call.

Uses browserAction (which is MV2-only) instead of action API (which is MV3 only).

Example shows bad practice of storing the port in a global variable with the expectation of the variable sticking around; this is not guaranteed in event pages/service workers (because these may suspend).

files/en-us/mozilla/add-ons/webextensions/api/runtime/onuserscriptconnect/index.md

files/en-us/mozilla/add-ons/webextensions/api/runtime/onuserscriptmessage/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md

Rob--W · 2025-02-18T14:58:01Z

files/en-us/mozilla/add-ons/webextensions/api/userscripts/registereduserscript/index.md

+
+- `allFrames` {{optional_inline}}
+  - : `boolean`. If `allFrames` is `true`, the script is injected into all of a page's frames. By default, it's `false` and the script is only injected into the top frame.
+- `id` {{optional_inline}} for {{WebExtAPIRef("userScripts.update()")}} calls, required for {{WebExtAPIRef("userScripts.register()")}}


ID is always required.

files/en-us/mozilla/add-ons/webextensions/api/userscripts/registereduserscript/index.md

github-actions · 2025-02-18T16:24:22Z

This pull request has merge conflicts that must be resolved before it can be merged.

Co-authored-by: Rob Wu <rob@robwu.nl>

Removed inappropriate onUserScriptConnect example

files/en-us/mozilla/add-ons/webextensions/api/runtime/onuserscriptconnect/index.md

files/en-us/mozilla/add-ons/webextensions/api/runtime/onuserscriptmessage/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/resetworldconfiguration/index.md

Rob--W · 2025-02-20T11:09:44Z

files/en-us/mozilla/add-ons/webextensions/api/userscripts/resetworldconfiguration/index.md

+
+Resets the configuration of a `USER_SCRIPT` world set by {{WebExtAPIRef("userScripts.configureWorld")}} to the defaults specified in {{WebExtAPIRef("userScripts.WorldProperties")}}. When the default world is reset, all worlds without an explicit configuration are also reset.
+
+Any scripts injected into a reset world are moved to the default `USER_SCRIPT` world.


Suggested change

Any scripts injected into a reset world are moved to the default `USER_SCRIPT` world.

This is factually incorrect. The closest reasonable interpretation of this is that the default world's configuration is used upon reset, which is already stated above.

Rob--W · 2025-02-20T11:10:58Z

files/en-us/mozilla/add-ons/webextensions/api/userscripts/resetworldconfiguration/index.md

+
+```js-nolint
+const resettingWorldConfiguration = await browser.userScripts.resetWorldConfiguration(
+  worldId       // string


Suggested change

worldId // string

worldId // optional string

Rob--W · 2025-02-20T11:48:41Z

files/en-us/mozilla/add-ons/webextensions/api/userscripts/worldproperties/index.md

+
+{{AddonSidebar}}
+
+The configuration of a `USER_SCRIPT` execution environment.


Please list all methods that uses this type: configureWorld, getWorldConfigurations.

Rob--W · 2025-02-20T11:54:07Z

files/en-us/mozilla/add-ons/webextensions/api/userscripts/worldproperties/index.md

+- `worldId` {{optional_inline}}
+  - : `string`. The identifier for the world. Values with leading underscores (`_`) are reserved. The maximum length is 256. Defaults to the default `USER_SCRIPT` world ("").
+- `csp` {{optional_inline}}
+  - : string`. The world's Content Security Policy (CSP). Defaults to the standard content scripts CSP, which prohibits dynamic code execution, such as` eval()`.


Suggested change

- : string`. The world's Content Security Policy (CSP). Defaults to the standard content scripts CSP, which prohibits dynamic code execution, such as` eval()`.

- : string`. The world's Content Security Policy (CSP). Defaults to the [default CSP for content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#csp_for_content_scripts), which prohibits dynamic code execution, such as` eval()`.

Added link that explains the default CSP.

files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md

Rob--W · 2025-02-20T12:08:05Z

files/en-us/mozilla/add-ons/webextensions/manifest.json/permissions/index.md

@@ -132,6 +132,7 @@ These permissions are available in Manifest V2 and above unless otherwise noted:
 - `theme`
 - `topSites`
 - `unlimitedStorage`
+- `userScripts` (This permission is [optional-only](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions#optional-only_permissions) in Firefox. In Chrome, the extension user must also activate [developer mode](https://developer.chrome.com/docs/extensions/reference/api/userScripts#developer_mode_for_extension_users).)


Suggested change

- `userScripts` (This permission is [optional-only](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions#optional-only_permissions) in Firefox. In Chrome, the extension user must also activate [developer mode](https://developer.chrome.com/docs/extensions/reference/api/userScripts#developer_mode_for_extension_users).)

- 'userScripts' (see [userScripts permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts#permissions))

Just link to the full documentation for brevity. Those who care are better served by the full documentation.

Rob--W · 2025-02-20T12:10:00Z

files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md

-> No optional-only permissions were generally available at the time of writing, December 2024.
+The optional-only API permissions are:
+
+- 'userScripts' (Firefox only)


Don't forget to also list userScripts in the list of optional permissions above.

Optional-only is a subset of optional_permissions.

Co-authored-by: Rob Wu <rob@robwu.nl>

files/en-us/mozilla/add-ons/webextensions/api/userscripts/configureworld/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/resetworldconfiguration/index.md

Rob--W

I am approving because the PR can be merged once my suggestions have all been applied. If in doubt, please ping me and I will offer an expedited review.

files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/register/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/registereduserscript/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/resetworldconfiguration/index.md

files/en-us/mozilla/add-ons/webextensions/api/userscripts/userscriptfilter/index.md

Rob--W · 2025-02-22T16:19:01Z

files/en-us/mozilla/add-ons/webextensions/api/userscripts/index.md


-To use the API, call `{{WebExtAPIRef("userScripts.register","register()")}}` passing in an object defining the scripts to register. The method returns a Promise that is resolved with a `{{WebExtAPIRef("userScripts.RegisteredUserScript","RegisteredUserScript")}}` object.
+- In Firefox, `userScripts` is an [optional-only permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions#optional-only_permissions) declared in the `optional_permissions` manifest key. Your extension must check that the permission has been granted by checking the availability of the `userScripts` API namespace or using {{WebExtAPIRef("permissions.contains()")}} and, if not, request it using {{WebExtAPIRef("permissions.request()")}}.
+- in Chrome, `userScripts` is an install time requested permission declared in the [`permissions` manifest key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions). However, to enable use of the API, users must [turn on the developer environment in Chrome](https://developer.chrome.com/docs/extensions/reference/api/userScripts#developer_mode_for_extension_users).


Note: Chrome is working on a per-extension toggle independently of the Developer Mode checkbox. That implementation is tracked at https://issues.chromium.org/issues/390138269

Co-authored-by: Rob Wu <rob@robwu.nl>

files/en-us/mozilla/add-ons/webextensions/api/userscripts/registereduserscript/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

rebloor added 5 commits February 6, 2025 11:16

Move legacy userScripts API documentation

8485776

Deleted content

02602fb

Missing slug updates

6882c17

remove dup

a55a6d9

Updated userScripts main article and type and method stubs

13926ce

rebloor added the Content:WebExt WebExtensions docs label Feb 10, 2025

rebloor requested review from dotproto and Rob--W February 10, 2025 02:00

rebloor self-assigned this Feb 10, 2025

github-actions bot added the size/l [PR only] 501-1000 LoC changed label Feb 10, 2025

Correct ScriptSource stub

2c4ed84

rebloor added 4 commits February 11, 2025 10:19

Type details

e076b22

userScript method details

fbae885

Adds permissions details

1cc58fa

runtime API additions

de94fad

github-actions bot added size/xl [PR only] >1000 LoC changed and removed size/l [PR only] 501-1000 LoC changed labels Feb 12, 2025

Release note

9820157

github-actions bot added the Content:Firefox Content in the Mozilla/Firefox subtree label Feb 13, 2025

rebloor mentioned this pull request Feb 13, 2025

Bug 1943050 new webExtension.api.userScripts mdn/browser-compat-data#25913

Open

rebloor marked this pull request as ready for review February 17, 2025 16:05

rebloor requested review from a team as code owners February 17, 2025 16:05

rebloor requested review from pepelsbey and removed request for a team February 17, 2025 16:05

sideshowbarker removed the request for review from a team February 18, 2025 00:36

Rob--W requested changes Feb 18, 2025

View reviewed changes

github-actions bot added the merge conflicts 🚧 [PR only] label Feb 18, 2025

Merge branch 'main' into Bug-1943050-userScripts-API-new-content

df5cd85

github-actions bot added size/l [PR only] 501-1000 LoC changed and removed merge conflicts 🚧 [PR only] size/xl [PR only] >1000 LoC changed labels Feb 18, 2025

rebloor and others added 5 commits February 19, 2025 05:58

Apply suggestions from review

f5f897a

Co-authored-by: Rob Wu <rob@robwu.nl>

Removed based on chromium notes

b000936

Eval space fix?

5675d22

Runtime event permission requirements

23d1d2e

Removed inappropriate onUserScriptConnect example

Additional information about configurations

e26c543

rebloor requested a review from Rob--W February 19, 2025 01:42

Final feedback updates

ef4ae42

Rob--W requested changes Feb 20, 2025

View reviewed changes

rebloor and others added 4 commits February 21, 2025 04:55

Apply suggestions from review

0350cdb

Co-authored-by: Rob Wu <rob@robwu.nl>

Corrections to suggested changes

800c1f2

Further feedback updates

5750c8b

Apply suggestions from review

10d4a80

Co-authored-by: Rob Wu <rob@robwu.nl>

rebloor commented Feb 20, 2025

View reviewed changes

files/en-us/mozilla/add-ons/webextensions/api/userscripts/configureworld/index.md Show resolved Hide resolved

files/en-us/mozilla/add-ons/webextensions/api/userscripts/resetworldconfiguration/index.md Show resolved Hide resolved

rebloor requested a review from Rob--W February 20, 2025 17:03

Rob--W approved these changes Feb 22, 2025

View reviewed changes

Rob--W reviewed Feb 22, 2025

View reviewed changes

Apply suggestions from review

fed7682

Co-authored-by: Rob Wu <rob@robwu.nl>

github-actions bot reviewed Feb 22, 2025

View reviewed changes

files/en-us/mozilla/add-ons/webextensions/api/userscripts/registereduserscript/index.md Outdated Show resolved Hide resolved

Remove unnecessary space

c8c17db

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bug 1943050 - new `userScripts` API content #38073

Bug 1943050 - new `userScripts` API content #38073

rebloor commented Feb 10, 2025 •

edited

Loading

github-actions bot commented Feb 10, 2025 •

edited

Loading

Rob--W left a comment

Rob--W Feb 18, 2025

Rob--W Feb 18, 2025

Rob--W Feb 18, 2025

rebloor Feb 19, 2025

github-actions bot commented Feb 18, 2025

Rob--W Feb 20, 2025

Rob--W Feb 20, 2025

Rob--W Feb 20, 2025

rebloor Feb 20, 2025

Rob--W Feb 20, 2025

Rob--W Feb 20, 2025

Rob--W Feb 20, 2025

rebloor Feb 20, 2025

Rob--W left a comment

Rob--W Feb 22, 2025


		Resets the configuration of a `USER_SCRIPT` world set by {{WebExtAPIRef("userScripts.configureWorld")}} to the defaults specified in {{WebExtAPIRef("userScripts.WorldProperties")}}. When the default world is reset, all worlds without an explicit configuration are also reset.

		Any scripts injected into a reset world are moved to the default `USER_SCRIPT` world.


		{{AddonSidebar}}

		The configuration of a `USER_SCRIPT` execution environment.

	- : string`. The world's Content Security Policy (CSP). Defaults to the standard content scripts CSP, which prohibits dynamic code execution, such as` eval()`.
	- : string`. The world's Content Security Policy (CSP). Defaults to the [default CSP for content scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_Security_Policy#csp_for_content_scripts), which prohibits dynamic code execution, such as` eval()`.

	- `userScripts` (This permission is [optional-only](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions#optional-only_permissions) in Firefox. In Chrome, the extension user must also activate [developer mode](https://developer.chrome.com/docs/extensions/reference/api/userScripts#developer_mode_for_extension_users).)
	- 'userScripts' (see [userScripts permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts#permissions))


		{{Compat}}

		> [!NOTE]

Bug 1943050 - new userScripts API content #38073

Are you sure you want to change the base?

Bug 1943050 - new userScripts API content #38073

Conversation

rebloor commented Feb 10, 2025 • edited Loading

Description

Related issues and pull requests

github-actions bot commented Feb 10, 2025 • edited Loading

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

github-actions bot commented Feb 18, 2025

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

Bug 1943050 - new `userScripts` API content #38073

Bug 1943050 - new `userScripts` API content #38073

rebloor commented Feb 10, 2025 •

edited

Loading

github-actions bot commented Feb 10, 2025 •

edited

Loading