What Is the Purpose of Metadata Blocks in Userscripts?

Userscript metadata blocks act as the control center for browser extensions like Tampermonkey, Violentmonkey, or Greasemonkey, defining key settings, scope, and permissions before any JavaScript executes. By standardizing execution parameters—such as which domain names the script runs on, what external resources it loads, and what API access it receives—the metadata block ensures safety, performance, and proper functionality. Understanding this block is essential for writing custom browser scripts, managing security permissions, and maintaining clean code organization.

Core Functions of the Userscript Metadata Block

A userscript metadata block is a structured comment block placed at the very top of a script, framed by // ==UserScript== and // ==/UserScript==. Browser extension engines parse this header to determine how, where, and when to execute the script.

1. Scope and Execution Target

The primary purpose of the metadata block is defining targeted web pages. Without these parameters, a script would either run on every single website—causing severe performance lag—or fail to run at all.

• @match: Defines explicit URL patterns where the script should run (e.g., https://*.example.com/*). This is the modern standard for defining target domains.
• @include: An older method used to match URLs using standard strings or wildcard characters.
• @exclude: Prevents execution on specific URLs, even if they fit the @match criteria.

2. Permissions and Security Controls

Userscripts run inside isolated browser environments. To interact with privileged functions, scripts must explicitly request authorization through the metadata block.

• @grant: Specifies permissions for elevated APIs (such as GM_xmlhttpRequest for cross-origin requests or GM_setValue for local data storage). Setting @grant none keeps the script in a standard sandbox, improving performance and security.
• @run-at: Dictates the exact moment during page loading that the script injects (e.g., document-start, document-end, or document-idle).

3. Resource Dependency Management

Rather than bundling large libraries into a single file, the metadata block allows developers to pull in external tools and styles securely.

• @require: Loads external JavaScript dependencies (like jQuery or custom libraries) before the main script runs.
• @resource: Pre-loads external assets, such as CSS stylesheets, images, or JSON data, which can then be retrieved using GM-specific functions.

Basic Example of a Userscript Header

Below is a standard layout showing how these directives work together in practice:

// ==UserScript==
// @name         Custom Page Styling Helper
// @namespace    http://example.com/
// @version      1.0.0
// @description  Enhances page readability by tweaking CSS styles.
// @author       Developer
// @match        https://*.example.com/*
// @icon         https://www.google.com/s2/favicons?sz=64&domain=example.com
// @grant        GM_addStyle
// @run-at       document-end
// ==/UserScript==

Summary of Key Directives