🇺🇸English
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 |
// 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 |
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 . See also
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
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:
Weekly Installs
66
Repository
henkisdabro/woo…-plugins
GitHub Stars
45
First Seen
Jan 25, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
opencode61
codex60
gemini-cli58
github-copilot57
cursor55
kimi-cli54
