userScripts API
Hint
The userScripts API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.
Note
Available for use with Manifest V3 only.
Note
An incompatible version of this API is available for Manifest V2. See userScripts (Legacy).
Permissions
The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.
Hint
Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.
userScripts
Allow unverified third-party scripts to access your data.
Functions
configureWorld(properties)
– [Added in TB 136]
Configures the environment for scripts running in a USER_SCRIPT world.
Parameters
properties
The desired configuration for a USER_SCRIPT world.
Required permissions
getScripts([filter])
– [Added in TB 136]
Returns all dynamically-registered user scripts for this extension.
Parameters
filter
If specified, this method returns only the user scripts that match it.
Required permissions
getWorldConfigurations()
– [Added in TB 136]
Returns all registered USER_SCRIPT world configurations.
Required permissions
register(scripts)
– [Added in TB 136]
Registers one or more user scripts for this extension.
Note
An incompatible version of this function is available for Manifest V2. See userScripts (Legacy).
Required permissions
resetWorldConfiguration([worldId])
– [Added in TB 136]
Resets the configuration for a given world. That world will fall back to the default world’s configuration.
Parameters
worldId
The ID of the USER_SCRIPT world to reset. If omitted or empty, resets the default world’s configuration.
Required permissions
unregister([filter])
– [Added in TB 136]
Unregisters all dynamically-registered user scripts for this extension.
Parameters
filter
If specified, this method unregisters only the user scripts that match it.
Required permissions
update(scripts)
– [Added in TB 136]
Updates one or more user scripts for this extension.
Required permissions
Types
ExecutionWorld
– [Added in TB 136]
The JavaScript world for a script to execute within. USER_SCRIPT is the default execution environment of user scripts, MAIN is the web page’s execution environment.
MatchPattern
string
or
or
MatchPatternRestricted
Same as MatchPattern above, but excludes <all_urls>
string
or
string
MatchPatternUnestricted
Mostly unrestricted match patterns for privileged add-ons. This should technically be rejected for unprivileged add-ons, but, reasons. The MatchPattern class will still refuse privileged schemes for those extensions.
string
RegisteredUserScript
– [Added in TB 136]
An object that represents a user script registered programmatically
object
id
The ID of the user script specified in the API call. This property must not start with a ‘_’ as it’s reserved as a prefix for generated script IDs.
js
The list of ScriptSource objects defining sources of scripts to be injected into matching pages.
allFrames
If allFrames is true, implies that the JavaScript should be injected into all frames of current page. By default, it’s false and is only injected into the top frame.
excludeGlobs
excludeMatches
includeGlobs
At least one of matches or includeGlobs should be non-empty. The script runs in documents whose URL match either pattern.
matches
At least one of matches or includeGlobs should be non-empty. The script runs in documents whose URL match either pattern.
runAt
The soonest that the JavaScript will be injected into the tab. Defaults to “document_idle”.
world
The JavaScript script for a script to execute within. Defaults to “USER_SCRIPT”.
worldId
If specified, specifies a specific user script world ID to execute in. Only valid if world is omitted or is USER_SCRIPT. If worldId is omitted, the script will execute in the default user script world (“”). Values with leading underscores (_) are reserved. The maximum length is 256.
RunAt
– [Added in TB 45]
The soonest that the JavaScript or CSS will be injected into the tab.
ScriptSource
– [Added in TB 136]
Object with file xor code property. Equivalent to the ExtensionFileOrCode, except the file remains a relative URL.
object
file
The path of the JavaScript file to inject relative to the extension’s root directory.
or
object
code
UserScriptFilter
– [Added in TB 136]
Optional filter to use with getScripts() and unregister().
WorldProperties
– [Added in TB 136]
The configuration of a USER_SCRIPT world.
object
csp
The world’s Content Security Policy. Defaults to the CSP of regular content scripts, which prohibits dynamic code execution such as eval.
messaging
Whether the runtime.sendMessage and runtime.connect methods are exposed. Defaults to not exposing these messaging APIs.
worldId
The identifier of the world. Values with leading underscores (_) are reserved. The maximum length is 256. Defaults to the default USER_SCRIPT world (“”).