andy/greasyboii
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
51e098213872c728631567629b873bedfe5d4fb6
greasyboii/BUILD.md
T
Andy Dixon e7d2200ef0 Initial Commit
2025-10-16 11:58:46 +01:00

8.1 KiB
Raw Blame History

Build Instructions

This document contains detailed instructions for building and distributing the Greasemonkey browser extension.

Prerequisites

  • Web browser (Chrome or Firefox)
  • Text editor (for development)
  • Node.js and npm (optional, for Firefox automated builds)

Quick Start

Testing Locally

Chrome

1. Open Chrome
2. Navigate to chrome://extensions/
3. Enable "Developer mode" (top-right toggle)
4. Click "Load unpacked"
5. Select the greasemonkey/chrome directory

Firefox

1. Open Firefox
2. Navigate to about:debugging#/runtime/this-firefox
3. Click "Load Temporary Add-on"
4. Select greasemonkey/firefox/manifest.json

Development Workflow

1. Making Changes

Edit files in the appropriate directory (chrome/ or firefox/).

Key files:

  • manifest.json - Extension configuration
  • popup.html - UI structure
  • popup.css - UI styling
  • popup.js - UI functionality
  • content.js - Code that runs on web pages
  • background.js - Background service/script

2. Testing Changes

After making changes:

Chrome:

  1. Go to chrome://extensions/
  2. Click the reload icon on the Greasemonkey extension card
  3. Test your changes

Firefox:

  1. Go to about:debugging#/runtime/this-firefox
  2. Click "Reload" on the Greasemonkey extension
  3. Test your changes

3. Debugging

Chrome:

  • Background script logs: chrome://extensions/ → "service worker" link
  • Content script logs: Browser console on any page (F12)
  • Popup logs: Right-click popup → "Inspect"

Firefox:

  • Background script logs: about:debugging → "Inspect" on extension
  • Content script logs: Browser console on any page (F12)
  • Popup logs: Right-click popup → "Inspect Element"

Building for Distribution

Chrome/Edge Build

Method 1: Manual Packaging (Recommended for Testing)

  1. Open Chrome
  2. Go to chrome://extensions/
  3. Ensure "Developer mode" is enabled
  4. Click "Pack extension"
  5. For "Extension root directory", select the chrome folder
  6. Leave "Private key file" empty for first build
  7. Click "Pack Extension"
  8. Chrome generates two files:
    • chrome.crx - The packaged extension
    • chrome.pem - Private key (keep this secure for updates!)

Method 2: Chrome Web Store Distribution

  1. Create a developer account at Chrome Web Store
  2. Pay one-time $5 registration fee
  3. Create a ZIP file of the chrome directory: 
    cd chrome
zip -r ../greasemonkey-chrome.zip *
  4. Upload to Chrome Web Store dashboard
  5. Fill in store listing details
  6. Submit for review

Note: Keep your .pem private key file secure. You'll need it for future updates.

Firefox Build

Method 1: Temporary Installation (Development)

Already covered in Quick Start - good for testing only. Temporary add-ons are removed when Firefox restarts.

Method 2: Self-Distribution (Unverified)

  1. Create a ZIP file: 
    cd firefox
zip -r ../greasemonkey-firefox.zip *
  2. Rename to .xpi: 
    mv greasemonkey-firefox.zip greasemonkey-firefox.xpi
  3. Users can install by dragging .xpi file to Firefox
  4. Firefox will show "unverified" warning

Method 3: Official Distribution (Recommended)

  1. Install web-ext tool:

    npm install -g web-ext

  2. Build the extension:

    cd firefox
web-ext build

    This creates a ZIP file in web-ext-artifacts/ directory

  3. Sign with Mozilla:

    • Create account at addons.mozilla.org
    • Get API keys from Developer Hub
    • Sign the extension: 
      web-ext sign \
  --api-key=YOUR_API_KEY \
  --api-secret=YOUR_API_SECRET
    • Or upload manually to addons.mozilla.org

  4. Distribution options:

    • Listed: Public on addons.mozilla.org (requires review)
    • Unlisted: Self-distribute signed XPI (automatic signing)

Directory Structure

greasemonkey/
├── chrome/                 # Chrome extension
│   ├── manifest.json
│   ├── background.js
│   ├── content.js
│   ├── popup.html
│   ├── popup.css
│   ├── popup.js
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
├── firefox/               # Firefox extension
│   ├── manifest.json
│   ├── background.js
│   ├── content.js
│   ├── popup.html
│   ├── popup.css
│   ├── popup.js
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
├── README.md
└── BUILD.md              # This file

Version Updates

When releasing a new version:

  1. Update version number in both manifest.json files:

    "version": "1.1.0"

  2. Update README.md version history

  3. Test thoroughly in both browsers

  4. Build new packages:

    • Chrome: Re-pack with same .pem key
    • Firefox: Build and sign new version

  5. Upload to respective stores/distribution channels

Quality Checklist

Before building for distribution:

  • Test all features in Chrome
  • Test all features in Firefox
  • Verify icons display correctly
  • Check manifest.json versions match
  • Test storage sync functionality
  • Verify permissions are appropriate
  • Test on various websites
  • Check browser console for errors
  • Test add/edit/delete rule functionality
  • Verify enable/disable toggles work
  • Test all match types (URL, Element, Both)
  • Review code for security issues
  • Update version numbers
  • Update documentation

File Size Optimization

To reduce extension size:

  1. Minify JavaScript (optional):

    npm install -g terser
terser popup.js -c -m -o popup.min.js

  2. Optimize PNG icons:

    # If you have optipng installed
optipng icon*.png

  3. Remove development files:

    • Source maps
    • Test files
    • Documentation (keep only in repo)

Automated Build Script

You can create a build script for automation:

#!/bin/bash
# build.sh

VERSION="1.0.0"

echo "Building Greasemonkey v${VERSION}..."

# Chrome build
echo "Building Chrome extension..."
cd chrome
zip -r "../dist/greasemonkey-chrome-${VERSION}.zip" * -x "*.DS_Store"
cd ..

# Firefox build
echo "Building Firefox extension..."
cd firefox
zip -r "../dist/greasemonkey-firefox-${VERSION}.zip" * -x "*.DS_Store"
cd ..

echo "Build complete! Files in dist/ directory"

Make it executable:

chmod +x build.sh
mkdir -p dist
./build.sh

Common Issues

Chrome Extension Doesn't Load

  • Check manifest.json syntax (use JSON validator)
  • Ensure all referenced files exist
  • Check browser console for errors

Firefox Temporary Add-on Removed

  • This is expected behavior
  • Use web-ext for persistent testing: 
    cd firefox
web-ext run

Icons Not Showing

  • Verify icon files exist
  • Check file paths in manifest.json
  • Ensure icon sizes are correct (16x16, 48x48, 128x128)

Storage Not Persisting

  • Chrome: Check sync is enabled in browser
  • Firefox: Temporary add-ons don't persist storage
  • Use proper signed/installed extension for testing

Distribution Platforms

Official Stores

Self-Distribution

  • GitHub Releases
  • Personal website
  • Direct XPI/CRX files

Security Notes

  • Never commit your Chrome .pem private key
  • Keep Firefox API keys secure
  • Don't bundle sensitive data in extension
  • Review all code before distribution
  • Test on malicious sites carefully

Resources

Support

For build issues or questions, contact Andy Dixon.

Reference in New Issue View Git Blame Copy Permalink