≡ userScripts API

• Manifest file properties

• Permissions

• Functions

• Events

• Types

≡ Add-on developer resources

• Introduction to add-on development

• "Hello world" extension tutorial

• Developer community

• Sample extensions (Github)

• Using Promises

• Additional resources on DTN

≡ Guides

• Working with WebExtension events

• Working with message lists

• Working with vCard contacts

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

Manifest file properties

user_scripts

[user_scripts]

(object, optional)

api_script

[api_script]

(ExtensionURL, optional)

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

userScripts

Allow unverified third-party scripts to access your data.

Note

A manifest entry named user_scripts is required to use messenger.userScripts.*.

Note

The permission userScripts is required to use messenger.userScripts.*.

Functions

register(userScriptOptions)

– [Added in TB 136]

Register a user script programmatically given its UserScriptOptions, and resolves to an object with the unregister() function

Note

An incompatible version of this function is available for Manifest V2. See userScripts (Legacy).

Parameters

userScriptOptions

userScriptOptions

(UserScriptOptions)

Return type (Promise)

_returns

object

An object that represents a user script registered programmatically

unregister

unregister

(function)

Unregister a user script registered programmatically

Required permissions

• userScripts

Events

onBeforeScript

Event called when a new userScript global has been created

Parameters for onBeforeScript.addListener(listener)

listener(userScript)

listener(userScript)

A function that will be called when this event occurs.

Parameters passed to the listener function

userScript

userScript

(object)

defineGlobals

defineGlobals

(function)

Exports all the properties of a given plain object as userScript globals

export

export

(function)

Convert a given value to make it accessible to the userScript code

global

global

(any)

The userScript global

metadata

metadata

(any)

The userScript metadata (as set in userScripts.register)

Required permissions

• userScripts

Types

ExtensionFileOrCode

Specify code, either by pointing to a file or by providing the code directly. Only one of the two is allowed.

object

file

file

(ExtensionURL)

A URL relative to the extension’s manifest.json file, and pointing to a JavaScript file to register.

or

object

code

code

(string)

A string of JavaScript code to register.

ExtensionURL

A path relative to the root of the extension.

string

MatchPattern

string

Supported values:

<all_urls>

<all_urls>

or

MatchPatternRestricted

or

MatchPatternUnestricted

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

PlainJSONValue

A plain JSON value

null

or

number

or

string

or

boolean

or

array of PlainJSONValue

or

object

RunAt

– [Added in TB 45]

The soonest that the JavaScript or CSS will be injected into the tab.

string

Supported values:

document_end

document_end

document_idle

document_idle

document_start

document_start

UserScriptOptions

Details of a user script

object

js

js

(array of ExtensionFileOrCode)

The list of JS files to inject

matches

matches

(array of MatchPattern)

allFrames

[allFrames]

(boolean, optional)

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.

cookieStoreId

[cookieStoreId]

(array of string or string, optional)

limit the set of matched tabs to those that belong to the given cookie store id

excludeGlobs

[excludeGlobs]

(array of string, optional)

excludeMatches

[excludeMatches]

(array of MatchPattern, optional)

includeGlobs

[includeGlobs]

(array of string, optional)

matchAboutBlank

[matchAboutBlank]

(boolean, optional)

If matchAboutBlank is true, then the code is also injected in about:blank and about:srcdoc frames if your extension has access to its parent document. Code cannot be inserted in top-level about:-frames. By default it is false.

runAt

[runAt]

(RunAt, optional)

The soonest that the JavaScript will be injected into the tab. Defaults to “document_idle”.

scriptMetadata

[scriptMetadata]

(PlainJSONValue, optional)

An opaque user script metadata value