Thank you for your interest in contributing! This guide will help you add new userscripts to this repository.
-
Create Your Script
- Start with the template in
_templates/userscript-template.user.js - Write your script following JavaScript best practices
- Test thoroughly on target websites
- Start with the template in
-
Script Requirements
- Must include complete metadata header
- Must include autoupdate URLs (
@updateURLand@downloadURL) pointing to the latest GitHub release - Must use
.user.jsextension - Must be well-commented
- Should handle errors gracefully
-
Versioning
Versions are managed automatically by semantic-release.
- Do not manually change
@versionin source scripts for release purposes - Version is determined from git tags (the last published release), not file contents
- All scripts share a single repo-level version
- Use Conventional Commits to drive version bumps:
fix:→ patch bump (e.g. 3.0.0 → 3.0.1)feat:→ minor bump (e.g. 3.0.1 → 3.1.0)feat!:orBREAKING CHANGE:→ major bumpchore:,docs:,refactor:,style:,test:,ci:→ no release
- Do not manually change
-
Metadata Requirements
// ==UserScript== // @name Descriptive Name // @namespace https://github.com/warthurton/userscripts // @version 1.0 // @description Clear description of what the script does // @author warthurton // @match https://example.com/* // @icon https://favicons-blue.vercel.app/?domain=example.com // @updateURL https://github.com/warthurton/userscripts/releases/latest/download/<name>.meta.js // @downloadURL https://github.com/warthurton/userscripts/releases/latest/download/<name>.user.js // @grant none // ==/UserScript==
- Purpose: Ensure script managers (Violentmonkey/FireMonkey/Tampermonkey) can automatically detect and install updates.
- Required fields:
@updateURLand@downloadURLmust always be present. - URL format:
@updateURL→https://github.com/warthurton/userscripts/releases/latest/download/<name>.meta.js@downloadURL→https://github.com/warthurton/userscripts/releases/latest/download/<name>.user.js<name>is the script filename without.user.js(e.g.auto-closeforauto-close.user.js)
- The build script rewrites these URLs in the published release assets, so they just need to be present in source files.
- Do not omit or comment out these lines; they must be included upon script creation.
- Purpose: Display an icon for the userscript in the script manager, making it easier to identify scripts at a glance.
- Recommended service: Use
https://favicons-blue.vercel.app/?domain=<domain>to get favicons. - Format:
@icon https://favicons-blue.vercel.app/?domain=example.com - Examples:
- For GitHub scripts:
@icon https://favicons-blue.vercel.app/?domain=github.com - For ChatGPT scripts:
@icon https://favicons-blue.vercel.app/?domain=chatgpt.com - For YouTube scripts:
@icon https://favicons-blue.vercel.app/?domain=youtube.com
- For GitHub scripts:
- Extract the domain from the
@matchURL pattern to determine the appropriate domain for the favicon. - The
@iconfield should always be included in new userscripts.
-
File Naming
- Use lowercase with hyphens
- Be descriptive but concise
- Example:
github-notification-enhancer.user.js
-
Documentation
- Add a comment block at the top explaining the script's purpose
- Document any configuration options
- Note any known limitations or issues
- Use strict mode:
'use strict'; - Use meaningful variable names
- Add comments for complex logic
- Keep functions small and focused
- Wrap code in IIFE to avoid global namespace pollution
- Check for element existence before manipulating DOM
- Use event delegation when possible
- Minimize @grant permissions (use
noneif possible)
- Test on multiple pages that match your @match pattern
- Verify script doesn't interfere with site functionality
- Check browser console for errors
- Test in different browsers if possible
Use the template in _templates/userscript-template.user.js as a starting point for new scripts. It includes:
- Proper metadata header with all required fields
- IIFE wrapper to avoid global namespace pollution
- Example structure with configuration and initialization
- Placeholder comments for updateURL and downloadURL
If you have questions about contributing, please open an issue for discussion.