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 (12)

Note! 17 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/Add-ons/WebExtensions/API/userScripts/UserScriptFilter
Title: userScripts.UserScriptFilter
Flaw count: 1

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

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 (3)

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/Add-ons/WebExtensions/manifest.json/permissions
Title: permissions

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-19 00:51:21)

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

Rob--W · 2025-02-18T14:17:42Z

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

+Fired when a connection is made with a user script from one of the extension's [`USER_SCRIPT` worlds](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/ExecutionWorld).
+
+A user script can only connect and then sent messages from a `USER_SCRIPT` world that is configured by {{WebExtAPIRef('userScripts.configureWorld()')}} with `messaging` set to `true`.
+


Let's add a note that this event requires the "userScripts" permission (in Firefox). In Chrome, the onUserScriptConnect and onUserScriptMessage events are always present, even in extensions that don't declare the userScripts permission, even if there is no way for that event to fire.

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

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

+Use this event to listen for messages sent from one of the extension's [`USER_SCRIPT` worlds](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/ExecutionWorld).
+
+A user script can only send messages using {{WebExtAPIRef('runtime.sendMessage')}} from a `USER_SCRIPT` world that is configured by {{WebExtAPIRef('userScripts.configureWorld()')}} with `messaging` set to `true`.
+


(already mentioned before; adding for completeness)

Let's add a note that this event requires the "userScripts" permission (in Firefox). In Chrome, the onUserScriptConnect and onUserScriptMessage events are always present, even in extensions that don't declare the userScripts permission, even if there is no way for that event to fire.

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.

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

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

+- `world` {{optional_inline}}
+  - : {{WebExtAPIRef("userScripts.ExecutionWorld")}}. The execution environment to use to run the scripts. Defaults to "USER_SCRIPT".
+- `worldId` {{optional_inline}}
+  - : `string`. ID of a user script world execute the script in. Only valid if `world` is `USER_SCRIPT` or omitted. If `worldId` is omitted, the script is execute in the default `USER_SCRIPT` world (""). Values with leading underscores (`_`) are reserved. The maximum length is 256 characters.


Refer to configureWorld for ease of discovery of what world configurations are.

@Rob--W don't follow this feedback. Isn't the main reference for worlds on the API's root page. Or did you mean a reference to 'getWorldConfigurations'?

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>

github-actions · 2025-02-18T16:58:55Z

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


[mdn-linter] _{reported by reviewdog 🐶}

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 standard content scripts CSP, which prohibits dynamic code execution, such as`eval()`.

Removed inappropriate onUserScriptConnect example

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

Apply suggestions from review

f5f897a

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

github-actions bot reviewed Feb 18, 2025

View reviewed changes

rebloor added 4 commits February 19, 2025 07:07

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

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

Rob--W Feb 18, 2025

rebloor Feb 19, 2025

Rob--W Feb 18, 2025

rebloor Feb 19, 2025

Rob--W Feb 18, 2025

rebloor Feb 19, 2025

github-actions bot commented Feb 18, 2025

github-actions bot Feb 18, 2025

		Fired when a connection is made with a user script from one of the extension's [`USER_SCRIPT` worlds](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/ExecutionWorld).

		A user script can only connect and then sent messages from a `USER_SCRIPT` world that is configured by {{WebExtAPIRef('userScripts.configureWorld()')}} with `messaging` set to `true`.

		Use this event to listen for messages sent from one of the extension's [`USER_SCRIPT` worlds](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/ExecutionWorld).

		A user script can only send messages using {{WebExtAPIRef('runtime.sendMessage')}} from a `USER_SCRIPT` world that is configured by {{WebExtAPIRef('userScripts.configureWorld()')}} with `messaging` set to `true`.

	- : 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 standard content scripts CSP, which prohibits dynamic code execution, such as`eval()`.


		{{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

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

github-actions bot commented Feb 18, 2025

github-actions bot Feb 18, 2025

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