The onBeforeScript event of the browser.userScripts is fired before a user script is executed. It can only be included in the API script, the script registered in "user_scripts", where it is used to detect that the custom API methods should be exported to the user script.



Events have three functions:

Adds a listener to this event.
Stop listening to this event. The listener argument is the listener to remove.
Check whether listener is registered for this event. Returns true if it is listening, false otherwise.

addListener syntax



A function that is called when this event occurs. The function is passed the following arguments:

An object that represents the user script that matched a web page. Its properties and methods are as follows:
A method that exports an object containing properties and methods available globally to the user script sandbox. This method must be called synchronously to guarantee that the user script has not executed.
A method that converts a value to one that the user script code can access. This method is used in API methods exported to the user script to result or resolve non-primitive values. The exported objects can also provide methods that the user script code can access and call.
 An object that provides access to the sandbox for the user script.
The scriptMetadata property set when the user script was registered using userScripts.register.


An example of how the listener might be used:

browser.userScripts.onBeforeScript.addListener(function (script) {

  script // This is an API object that represents the user script
         // that is going to be executed.

  script.metadata // Access the user script metadata (returns the
                  // value of the scriptMetadata property from
                  // the call to userScripts.register.

  // Export some global properties into the user script sandbox
  // (this method has to be called synchronously from the
  // listener, otherwise the user script may have executed).
    aGlobalPropertyAccessibleFromUserScriptCode: “prop value”,

    myCustomAPIMethod(param1, param2) {
      // Custom methods exported from the API script can use
      // the WebExtensions APIs available to content scripts.

      return 123; // primitive values can be returned directly

      // Non primitive values have to be exported explicitly
      // using the export method provided by the script API
      // object
      return script.export({
        objKey1: {
          nestedProp: "nestedvalue",
        // Explicitly exported objects can also provide methods.
        objMethod() { ... }

    async myAsyncMethod(param1, param2, param2) {
    // exported methods can also be declared as async

Browser compatibility

Update compatibility data on GitHub
ChromeEdgeFirefoxOperaSafariFirefox for Android
onBeforeScriptChrome No support NoEdge No support NoFirefox Full support 68
Full support 68
Full support 66
Disabled From version 66: this feature is behind the extensions.webextensions.userScripts.enabled preference (needs to be set to true). To change preferences in Firefox, visit about:config.
Opera No support NoSafari No support NoFirefox Android Full support 68


Full support  
Full support
No support  
No support
User must explicitly enable this feature.
User must explicitly enable this feature.

See also