henkisdabro/tampermonkey

Tampermonkey Userscript Development

Expert guidance for writing Tampermonkey userscripts - browser scripts that modify web pages, automate tasks, and enhance browsing experience.

Quick Start Template

JavaScript (simple scripts with no GM. APIs)*

// ==UserScript==
// @name         My Script Name                    // <- CUSTOMISE: Unique script name
// @namespace    https://example.com/scripts/      // <- CUSTOMISE: Your unique namespace
// @version      1.0.0                             // <- INCREMENT on updates
// @description  Brief description of the script   // <- CUSTOMISE: What it does
// @author       Your Name                         // <- CUSTOMISE: Your name
// @match        https://example.com/*             // <- CUSTOMISE: Target URL pattern
// @grant        none                              // <- ADD permissions as needed
// @run-at       document-idle                     // <- ADJUST timing if needed
// ==/UserScript==

(function() {
    'use strict';
    // Your code here
})();

Modern (async/await - recommended when using GM. APIs)*

// ==UserScript==
// @name         My Script Name
// @namespace    https://example.com/scripts/
// @version      1.0.0
// @description  Brief description of the script
// @author       Your Name
// @match        https://example.com/*
// @grant        GM.getValue
// @grant        GM.setValue
// @run-at       document-idle
// ==/UserScript==

(async () => {
    'use strict';
    // Async entry point — use await with GM.* APIs
    const setting = await GM.getValue('myKey', 'default');
    console.log('Script loaded, setting:', setting);
})();

TypeScript: Add @types/tampermonkey for full type safety. See typescript.md.

---

Essential Header Tags

| Tag | Required | Purpose | Example | |-----|----------|---------|---------| | @name | Yes | Script name (supports i18n with :locale) | @name My Script | | @namespace | Recommended | Unique identifier namespace | @namespace https://yoursite.com/ | | @version | Yes* | Version for updates (required for auto-update) | @version 1.2.3 | | @description | Recommended | What the script does | @description Enhances page layout | | @match | Yes* | URLs to run on (*or @include) | @match https://example.com/* | | @grant | Situational | API permissions (use none for no GM_ APIs) | @grant GM_setValue | | @run-at | Optional | When to inject (default: document-idle) | @run-at document-start | | @run-in | Optional | Limit to normal or incognito tabs, or Firefox containers (v5.3+) | @run-in normal-tabs |

For complete header documentation, see: header-reference.md

---

URL Matching Quick Reference

// Exact domain                  // @match https://example.com/*
// All subdomains                // @match https://*.example.com/*
// HTTP and HTTPS                // @match *://example.com/*
// Exclude paths (with @match)   // @exclude https://example.com/admin/*

For advanced patterns (regex, @include, specific paths), see: url-matching.md

---

@grant Permissions Quick Reference

| You Need To... | Grant This | |----------------|------------| | Store persistent data | @grant GM_setValue + @grant GM_getValue | | Make cross-origin requests | @grant GM_xmlhttpRequest + @connect domain | | Add custom CSS | @grant GM_addStyle | | Access page's window | @grant unsafeWindow | | Show notifications | @grant GM_notification | | Add menu commands | @grant GM_registerMenuCommand | | Detect URL changes (SPA) | @grant window.onurlchange | | Batch read/write settings (v5.3+) | @grant GM.getValues + @grant GM.setValues | | Mute/unmute tab audio | @grant GM_audio |

// Disable sandbox (no GM_* except GM_info)
// @grant none

// Cross-origin requests require @connect
// @grant GM_xmlhttpRequest
// @connect api.example.com
// @connect *.googleapis.com

For complete permissions guide, see: header-reference.md

---

@run-at Injection Timing

| Value | When Script Runs | Use Case | |-------|------------------|----------| | document-start | Before DOM exists | Block resources, modify globals early | | document-body | When body exists | Early DOM manipulation | | document-end | At DOMContentLoaded | Most scripts - DOM ready | | document-idle | After DOMContentLoaded (default) | Safe default | | context-menu | On right-click menu | User-triggered actions |

---

Common Patterns

These patterns are used frequently. Brief summaries are below - load patterns.md for full implementations with code examples.

• Wait for Element - Promise-based MutationObserver that resolves when a CSS selector appears in the DOM, with configurable timeout
• SPA URL Change Detection - Detect navigation in single-page apps using window.onurlchange grant or History API interception
• Cross-Origin Request - Fetch data from external APIs using GM_xmlhttpRequest with @connect domain whitelisting. See also http-requests.md
• Add Custom Styles - Inject CSS with GM_addStyle to restyle pages or hide elements. See also api-dom-ui.md
• Persistent Settings - Store user preferences with GM_setValue/GM_getValue and expose toggle via GM_registerMenuCommand. See also api-storage.md
• DOM Mutation Observation - Watch for dynamically added content with MutationObserver (debounced variant included)
• Element Manipulation - Inject HTML, remove/hide elements, replace text across the page
• Keyboard Shortcuts - Simple handlers and a shortcut manager with modifier key support
• Data Extraction - Extract table data to arrays/objects, collect and filter page links
• Error Handling - Safe wrapper for try/catch and async retry with exponential backoff
• TypeScript Userscripts - Type-safe scripts with @types/tampermonkey. See typescript.md

---

External Resources

// @require - Load external scripts
// @require https://code.jquery.com/jquery-3.6.0.min.js#sha256-/xUj+3OJU...
// @require tampermonkey://vendor/jquery.js         // Built-in library

// @resource - Preload and inject external CSS
// @resource myCSS https://example.com/style.css    // Then: GM_addStyle(GM_getResourceText('myCSS'))
// @grant GM_getResourceText
// @grant GM_addStyle

---

TypeScript Support

Install the type definitions for full IDE autocompletion and type safety:

npm install --save-dev @types/tampermonkey

// ==UserScript==
// @name         My TypeScript Script
// @match        https://example.com/*
// @grant        GM.getValue
// @grant        GM.xmlHttpRequest
// @connect      api.example.com
// ==/UserScript==

(async () => {
    'use strict';
    const value = await GM.getValue<string>('key', 'default');
    const info: Tampermonkey.ScriptInfo = GM_info;
    console.log(info.script.name, value);
})();

Build with a bundler (esbuild, Vite, webpack) to a single .user.js output file. For full project setup including tsconfig and bundler config, see typescript.md.

---

What Tampermonkey Cannot Do

Userscripts have limitations:

• Access local files - Cannot read/write files on your computer
• Run before page scripts - In isolated sandbox mode, page scripts run first
• Access cross-origin iframes - Browser security prevents this
• Persist across machines - GM storage is local to each browser
• Bypass all CSP - Some very strict CSP cannot be bypassed
• Inject without permission - Tampermonkey v5.4.1+ requires users to grant injection permission per-site or globally; scripts cannot bypass this requirement

Most limitations have workarounds - see common-pitfalls.md.

---

When Generating Userscripts

Always include in your response:

1. Explanation - What the script does (1-2 sentences)
2. Complete userscript - Full code with all headers in a code block
3. Installation - "Copy/paste into Tampermonkey dashboard" or "Save as .user.js"
4. Customisation points - What the user can safely modify (selectors, timeouts, etc.)
5. Permissions used - Which @grants and why they're needed
6. Browser support - If Chrome-only, Firefox-only, or universal

---

Pre-Delivery Checklist

Before returning a userscript, verify:

Critical (Must Pass)

• [ ] No hardcoded API keys, tokens, or passwords
• [ ] @match is specific (not *://*/*)
• [ ] All external URLs use HTTPS
• [ ] User input sanitised before DOM insertion

Important (Should Pass)

• [ ] Wrapped in IIFE with 'use strict'
• [ ] All @grant statements are necessary
• [ ] @connect includes all external domains
• [ ] Error handling for async operations
• [ ] Null checks before DOM manipulation

Recommended

• [ ] @version follows semantic versioning (X.Y.Z)
• [ ] Works in both Chrome and Firefox
• [ ] Comments explain non-obvious code

For complete security checklist, see: security-checklist.md

---

Reference Files Guide

Load these on-demand based on user needs:

| File | When to Load | |------|--------------| | Core | | | header-reference.md | Header syntax - all @tags with examples | | url-matching.md | @match, @include, @exclude patterns | | patterns.md | Common implementation patterns with code | | sandbox-modes.md | Security/isolation execution contexts | | API | | | api-sync.md | GM_* synchronous function reference (callback-based) | | api-async.md | GM.* promise-based API reference - prefer these for new scripts | | api-storage.md | GM_setValue, GM_getValue, listeners | | http-requests.md | GM_xmlhttpRequest cross-origin | | web-requests.md | GM_webRequest interception (Firefox) | | api-cookies.md | GM_cookie manipulation | | api-dom-ui.md | addElement, addStyle, unsafeWindow | | api-tabs.md | getTab, saveTab, openInTab | | api-audio.md | Mute/unmute tabs | | Quality | | | common-pitfalls.md | What breaks scripts and workarounds | | debugging.md | How to debug userscripts | | browser-compatibility.md | Chrome vs Firefox differences | | security-checklist.md | Pre-delivery security validation | | version-numbering.md | Version string comparison rules | | typescript.md | TypeScript project setup with @types/tampermonkey, bundler config |