Publishing UserScripts to Greasy Fork: A Complete Tutorial

This tutorial walks through the process of creating and publishing a userscript to Greasy Fork, using our Claude.ai sidebar toggle script as an example.

What is Greasy Fork?

Greasy Fork is a popular repository for userscripts, which are JavaScript programs that modify web pages. It’s the successor to the traditional Userscripts.org site and integrates well with modern userscript managers like Tampermonkey and Greasemonkey.

Prerequisites

• Basic knowledge of JavaScript
• A userscript manager installed:
• Tampermonkey (Chrome, Firefox, Edge)
• Greasemonkey (Firefox)
• Violentmonkey (Chrome, Firefox)
• A Greasy Fork account

Creating a UserScript

Metadata Block Structure

Every userscript starts with a metadata block. Here’s our example:

// ==UserScript==
// @name         Claude.ai Sidebar Toggle
// @namespace    http://tampermonkey.net/
// @version      1.0
// @description  Add a button to toggle the sidebar on claude.ai
// @author       Your Name
// @match        https://claude.ai/*
// @grant        none
// @license      MIT
// ==/UserScript==

Important metadata fields:
- @name: The name of your script
- @namespace: Usually your website or a unique identifier
- @version: Script version (must be incremented for updates)
- @description: Brief description of what your script does
- @match: Which URLs your script runs on
- @grant: Required permissions
- @license: The license for your code

Code Structure

Best practices for userscript code:

1. Always use strict mode:

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

2. Include CSS within JavaScript:

const style = document.createElement('style');
style.textContent = `
    /* Your CSS here */
`;
document.head.appendChild(style);

3. Handle page loading appropriately:

window.addEventListener('load', () => {
    // Your initialization code
});

Publishing to Greasy Fork

1. Create an Account:
   - Visit https://greasyfork.org
   - Click “Sign in” and create an account
   - Verify your email address

2. Create New Script:
   - Click “New Script” in your user menu
   - Choose between:

   • “Write a new script”
   • “Import from URL”
   • “Import from file”

3. Fill Out Script Information:
   - Name (prepopulated from metadata)
   - Description (prepopulated from metadata)
   - Additional information (optional):

   • Screenshots
   • Additional documentation
   • Support URL
   • Contribution URL

4. Set Script Settings:
   - Choose script type (usually “Public”)
   - Select language
   - Choose sync options (if importing from URL)
   - Set update notifications

5. Submit for Review:
   - Your script will be checked for basic requirements
   - Automated tests will run
   - Manual review may be required for certain features

Best Practices for Greasy Fork

1. Code Quality:
   - Use clear, readable code
   - Comment complex logic
   - Follow JavaScript best practices
   - Test thoroughly before publishing

2. Metadata:
   - Use specific @match patterns
   - Request minimum necessary @grant permissions
   - Include a clear @description
   - Choose an appropriate @license

3. Documentation:
   - Provide clear installation instructions
   - Document any configuration options
   - Include example usage
   - List known issues or limitations

4. Updates:
   - Maintain a changelog
   - Increment version numbers
   - Test updates thoroughly
   - Respond to user feedback

Script Maintenance

1. Monitoring:
   - Check script feedback
   - Monitor for site changes
   - Track bug reports
   - Review feature requests

2. Updates:

// ==UserScript==
// @name         Claude.ai Sidebar Toggle
// @version      1.1
// Changes:
// - Fixed sidebar selector
// - Added error handling
// ==/UserScript==

3. Version Control:
   - Use a Git repository (optional)
   - Document changes
   - Keep old versions available

Common Issues and Solutions

1. Script Not Running:
   - Check @match patterns
   - Verify required permissions
   - Test in multiple browsers
   - Check for conflicts

2. Update Problems:
   - Clear browser cache
   - Reinstall userscript manager
   - Check version numbers
   - Verify metadata block

3. Site Changes:
   - Use robust selectors
   - Add error handling
   - Monitor site updates
   - Respond quickly to breaks

Security Considerations

1. Code Safety:
   - Avoid eval() and similar functions
   - Sanitize user input
   - Use content security policies
   - Minimize external dependencies

2. User Privacy:
   - Document data collection
   - Get consent for analytics
   - Protect user information
   - Follow GDPR guidelines

Greasy Fork Policies

1. Content Rules:
   - No malicious code
   - No copyright infringement
   - No adult content without marking
   - No obfuscated code

2. Maintenance Requirements:
   - Respond to critical issues
   - Keep contact information updated
   - Document significant changes
   - Handle security reports

Example: Full Script

// ==UserScript==
// @name         Claude.ai Sidebar Toggle
// @namespace    http://tampermonkey.net/
// @version      1.0
// @description  Add a button to toggle the sidebar on claude.ai
// @author       Your Name
// @match        https://claude.ai/*
// @grant        none
// @license      MIT
// ==/UserScript==

(function() {
    'use strict';

    // Add custom styles
    const style = document.createElement('style');
    style.textContent = `
        #sidebar-toggle {
            position: fixed;
            top: 20px;
            left: 20px;
            z-index: 9999;
            padding: 8px 12px;
            background-color: #f0f0f0;
            border: 1px solid #ccc;
            border-radius: 4px;
            cursor: pointer;
            font-size: 14px;
            opacity: 0.8;
            transition: opacity 0.2s;
        }

        #sidebar-toggle:hover {
            opacity: 1;
        }
    `;
    document.head.appendChild(style);

    function createToggleButton() {
        const button = document.createElement('button');
        button.id = 'sidebar-toggle';
        button.innerHTML = '◀';
        button.title = 'Toggle Sidebar';

        button.addEventListener('click', () => {
            const sidebar = document.querySelector('[data-testid="menu-sidebar"]');
            if (sidebar) {
                sidebar.style.display = sidebar.style.display === 'none' ? 'block' : 'none';
                button.innerHTML = sidebar.style.display === 'none' ? '▶' : '◀';
            }
        });

        document.body.appendChild(button);
    }

    // Wait for the page to fully load
    window.addEventListener('load', () => {
        // Small delay to ensure the Claude.ai UI is fully rendered
        setTimeout(createToggleButton, 1000);
    });
})();

Resources

• Greasy Fork Documentation
• Tampermonkey Documentation
• UserScript Meta Keys
• JavaScript Best Practices

Conclusion

Publishing to Greasy Fork is a great way to share your userscripts with the community. Remember to:
- Follow best practices
- Maintain your code
- Respond to user feedback
- Keep scripts updated
- Document everything clearly

Next Steps

1. Join the Greasy Fork community
2. Contribute to other scripts
3. Build a portfolio of useful scripts
4. Share your knowledge
5. Keep learning and improving