Userscripts

Userscripts are JavaScript files that are executed every time the user loads a Scratch page. They can modify the document’s HTML, add new buttons, customize Scratch editor behavior, and so much more.

Similarly to userscripts that you might download for userscript managers like Tampermonkey or Greasemonkey, Scratch Addons userscripts consist of pieces of JavaScript that are executed in the same execution context as the JavaScript code from Scratch itself. In browser extension vocabulary, this execution context is often called the “main world”.

Even though Scratch Addons userscripts are part of a browser extension, they cannot access any chrome.* or browser.* APIs. Instead, Scratch Addons offers an addon.* API.

Declaring userscripts in the addon manifest

Userscripts are declared inside a “userscripts” array.

Each item of the array must have the following properties:

• "url": the relative URL to a JavaScript file.
• "matches": the list of Scratch pages where the userscript will run. See matches for more information.

Example manifest:

{
  "name": "Copy link to comment button",
  "description": "Adds a \"Copy Link\" button to all comments on the website, next to the \"Report\" button.",
  "userscripts": [
    {
      "url": "userscript.js",
      "matches": ["projects", "https://scratch.mit.edu/", "profiles", "studios"]
    }
  ],
  "tags": ["community"],
  "enabledByDefault": false
}

Creating your first userscript

Unlike extension content scripts and Tampermonkey userscripts, you must wrap all of your code inside a module default export:

// Example userscript
export default async function ({ addon, console }) {
  console.log("Hello, " + await addon.auth.fetchUsername());
  console.log("How are you today?");
}

Remember that JavaScript allows functions to be declared inside other functions, for example:

export default async function ({ addon, console }) {
  async function sayHelloToUser() {
    console.log("Hello, " + await addon.auth.fetchUsername());
  }

  await sayHelloToUser();
  console.log("How are you today?");
}

Modifying the document HTML

Use browser DOM APIs to customize the HTML of the page.

Here’s an example:

const myButton = document.createElement("button");
myButton.textContent = "Click me!";
myButton.classList.add("button");
myButton.setAttribute("title", "You're hovering a button");

const myContainer = document.querySelector(".container");
myContainer.append(myButton);

Localizing userscripts

Addon userscripts sometimes need to reference English words or sentences. Make sure not to hardcode them, so that they can be part of the translation process.

// Don't do this:
document.querySelector(".sa-find-bar").placeholder = "Find blocks";

To create a translatable string, follow these steps:

1. Create a file named addon-id.json inside the /addon-l10n/en folder.
2. Provide an ID for every string:

{
  "addon-id/find": "Find blocks"
}

3. Make sure to import the msg() function in your userscript. The first line of your userscript should look like this:

export default async function ({ addon, console, msg  }) {
                                              // ^^^

4. Use the msg() function in your code, instead of a hardcoded string:

document.querySelector(".sa-find-bar").placeholder = msg("find");

Technical details

Each userscript file is a JavaScript module that exports a function. Scratch Addons only imports the module if needed, and executes it after the page has fully loaded.

Userscripts are JavaScript modules, so they always run on “strict mode”. This also means that userscripts may use top-level imports to import other JavaScript files.

The order in which userscripts run may vary on each page load. After page load, the user might dynamically enable some addons in a custom order, so order of execution is never guaranteed. Some APIs like addon.tab.appendToSharedSpace attempt to fix any potential race conditions and unexpected behavior when dynamically enabling addons.

runAtComplete

Userscripts may opt-in into being executed before the page has fully loaded by specifying "runAtComplete": false in the addon manifest, once for each userscript.

As of now, only document.head is guaranteed to exist when running a userscript early. In the future, document.body will also be guaranteed to exist, so no userscripts will ever run before the HTML document loaded enough to reach </head> <body>.

章節頁面

• Best Practices

  Follow these best practices when writing or reviewing userscript code.

• Debugging Tips

  Tips to easily debug userscripts, and edge cases to consider.