userScripts

Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration.

Note:This is documentation for the new API version, available in Firefox for Manifest V3. SeeuserScripts (legacy) for information on the API available for use in Firefox with Manifest V2.

This API offers capabilities similar toscripting but with features suited to handling third-party scripts.

Permissions

To use this API, you need theuserScripts permission andhost_permissions for sites where you want to run scripts. However, the approach to enabling the use of this API varies between browsers:

In Firefox,userScripts is anoptional-only permission declared in theoptional_permissions manifest key. Your extension must check that the permission has been granted by checking the availability of theuserScripts API namespace or usingpermissions.contains() and, if not, request it usingpermissions.request().
in Chrome,userScripts is an install time requested permission declared in thepermissions manifest key. However, to enable use of the API, users mustturn on the developer environment in Chrome.

Execution worlds

When a user script is registered or updated (usinguserScripts.register() oruserScripts.update()), your extension can set it to run in an isolatedUSER_SCRIPT world or theMAIN world.

AUSER_SCRIPT world provides an isolated execution environment that isn't accessible to a host page or other extensions. This isolation is similar to acontent script environment, exceptUSER_SCRIPT worlds cannot access extension APIs.

User scripts can share aUSER_SCRIPT world or isolate themselves in aUSER_SCRIPT world by setting theworldId property ofRegisteredUserScript. The API enables an extension to configure a content security policy (CSP) for aUSER_SCRIPT world usinguserScripts.configureWorld().

In theMAIN world, host pages and other extensions can see and access running user scripts. TheworldId property is not supported forMAIN worlds.

These execution world values are defined inExecutionWorld.

Messaging

Like content scripts and other extension scripts, user scripts communicate with other parts of an extension with messages usingruntime.sendMessage() andruntime.connect(). However, extensions receive messages using the dedicatedruntime.onUserScriptMessage andruntime.onUserScriptConnect. Dedicated handlers are used as they make it easier to identify messages from user scripts, which are a less-trusted context.

To enable messaging APIs, calluserScripts.configureWorld() with themessaging argument set totrue before registering a user script.

browser.userScripts.configureWorld({  messaging: true,});

Extension updates

When an extension updates, user scripts are cleared. To restore scripts, add code to the extension'sruntime.onInstalled event handler that responds to the"update" reason.

Types

userScripts.ExecutionWorld: The execution environment for a script injected withuserScripts.register()oruserScripts.update().
userScripts.RegisteredUserScript: Anobject returned bygetScripts() representing registered user scripts and used as input toregister() andupdate().
userScripts.ScriptSource: The code or a file source for a user script.
userScripts.UserScriptFilter: A list of user scripts to be processed byuserScripts.getScripts() oruserScripts.unregister().
userScripts.WorldProperties: The configuration of aUSER_SCRIPT execution environment.

Methods

userScripts.configureWorld(): Configures aUSER_SCRIPT execution environment for the extension.
userScripts.getScripts(): Returns user scripts registered by the extension.
userScripts.getWorldConfigurations(): Returns all the extension's registered world configurations.
userScripts.register(): Registers user scripts for the extension.
userScripts.resetWorldConfiguration(): Resets the configuration for aUSER_SCRIPT world registered by the extension.
userScripts.unregister(): Unregisters user scripts registered by the extension.
userScripts.update(): Updates user scripts registered by the extension.
userScripts.execute(): Injects a user script into a target context.