📢 Try installing a desktop browser extension and synchronize bookmarks with your XBrowser.

User Script Introduction

Series Navigation

TL;DR (Quick Start)

  • Regular User Scripts: A piece of JavaScript code that runs directly, suitable for lightweight feature enhancements.
  • Tampermonkey Scripts: With // ==UserScript== metadata header, supports more script management capabilities and GM APIs.
  • Recommended Reading Order: Introduction -> Regular Scripts -> Tampermonkey Scripts -> API Reference -> API Examples.

Quick Navigation

What are User Scripts?

User scripts are user-defined JavaScript code that can run automatically during page loading, or be injected into the current page after certain specific conditions are met. User scripts can enhance the functionality of original web pages or remove some web page restrictions, thereby providing a better user experience for the original web page.

User scripts are characterized by being small, flexible, and easy to use. They can extend browser functionality very conveniently. It’s no exaggeration to say that if you can think of it, it can be done. Many regular browser features can be implemented in the form of user scripts, such as reading mode, page translation, night mode, etc.

Classification of User Scripts

Based on the characteristics of user scripts, we can roughly divide user scripts into two categories: regular user scripts and Tampermonkey scripts.

Regular User Scripts

Regular user scripts are native JavaScript code, loosely organized, without specific development specifications. As long as they conform to standard JavaScript syntax, they are characterized by being small, flexible, and easy to get started with.

The simplest regular user script can be written like this:

alert("Hello World!");

Tampermonkey Scripts

Tampermonkey originated from a Firefox extension called Greasemonkey. Later, Tampermonkey extension appeared with wider support and better compatibility. User scripts compatible with these two extensions are collectively called Tampermonkey scripts.

The simplest Tampermonkey script can be written like this:

// ==UserScript==
// @name         Say hello
// @namespace    com.example.hello
// @version      0.1
// @description  When you open the site example.com it says "HELLO"
// @author       You
// @match        www.example.com
// ==/UserScript==

(function() {
    'use strict';
    alert("Hello World!");
})();

Compared to regular scripts, Tampermonkey scripts usually contain two parts: one part is the header composed of metadata, and the other part is the code body. Metadata is used to define the basic information of the script (version, name, dependencies, resources, permissions, execution timing, etc.). In addition, the script manager also provides some advanced GM APIs to help developers achieve more efficient and convenient development. For more information about metadata and APIs, please refer to Tampermonkey Script API Reference.

Common Issues (Troubleshooting)

  • Script not working: First confirm whether the script is enabled, and whether the script’s scope (regular script’s auto-execution domain/Tampermonkey script’s @match/@include/@exclude) covers the current website.
  • Script executed but no visible effect: Many scripts write output to the console or page elements, not necessarily showing alerts. You can first use the most intuitive method like alert("Hello World!") to verify the execution path.
  • Only want to work on certain websites: Prioritize using scope restrictions (domain settings for regular scripts or matching rules in Tampermonkey script metadata) to avoid injecting into all websites, which may cause performance or compatibility issues.

Related Reading