Tampermonkey Userscript Development

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

Quick Start Template

// ==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
    console.log('Script loaded!');
})();

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`

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`

// 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

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

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

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

When Generating Userscripts

Always include in your response:

Explanation - What the script does (1-2 sentences)
Complete userscript - Full code with all headers in a code block
Installation - "Copy/paste into Tampermonkey dashboard" or "Save as .user.js"
Customisation points - What the user can safely modify (selectors, timeouts, etc.)
Permissions used - Which @grants and why they're needed
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

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 usage
api-async.md	GM.* promise-based API usage
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

tampermonkey