greasyboii/PACKAGING.md

How to Package GreasyBoii Extension

This guide shows you how to package GreasyBoii for distribution.

Quick Start

Chrome/Edge (Easy Method)

1. Open chrome://extensions/
2. Enable "Developer mode" (top-right toggle)
3. Click "Pack extension"
4. For "Extension root directory" → Select the chrome folder
5. Leave "Private key file" empty (first time)
6. Click "Pack Extension"
7. ✅ Done! You get 2 files:
   • chrome.crx - The packaged extension
   • chrome.pem - Private key (KEEP THIS SECURE!)

Firefox (Command Line)

cd firefox
zip -r ../greasyboii-firefox-v1.0.4.zip *

Done! You get greasyboii-firefox-v1.0.4.zip

---

Detailed Instructions

Chrome Extension Packaging

Method 1: Chrome Built-in Packer (Recommended)

Step 1: Open Extensions Page

chrome://extensions/

Step 2: Enable Developer Mode

• Toggle the "Developer mode" switch in the top-right corner

Step 3: Pack Extension

1. Click "Pack extension" button
2. In the dialog:
   • Extension root directory: Browse and select /path/to/greasemonkey/chrome
   • Private key file: Leave empty (first time) or select your .pem file
3. Click "Pack Extension"

Step 4: Files Created You'll get two files in the parent directory:

• chrome.crx - The packed extension (ready to distribute)
• chrome.pem - Your private key (KEEP THIS SECRET!)

Important Notes:

• ⚠️ Keep the .pem file secure - You need it to update your extension
• ⚠️ Never share your .pem file - Anyone with it can impersonate your extension
• ✅ The .crx file is what you distribute to users

Method 2: Command Line (Using Chrome)

# Navigate to Chrome binary location
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --pack-extension=/path/to/greasemonkey/chrome

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --pack-extension=C:\path\to\greasemonkey\chrome

# Linux
google-chrome --pack-extension=/path/to/greasemonkey/chrome

Method 3: Create ZIP for Chrome Web Store

If you want to publish on Chrome Web Store:

cd chrome
zip -r ../greasyboii-chrome-v1.0.4.zip *

Then upload the ZIP to Chrome Web Store Developer Dashboard

---

Firefox Extension Packaging

Method 1: Simple ZIP (Recommended for Testing)

Create ZIP:

cd firefox
zip -r ../greasyboii-firefox-v1.0.4.zip *

Rename to XPI (optional):

mv greasyboii-firefox-v1.0.4.zip greasyboii-firefox-v1.0.4.xpi

Install:

• Drag the .xpi file into Firefox
• Or: about:addons → gear icon → "Install Add-on From File"

Note: Unsigned extensions show a warning. For permanent use, you need to sign it.

Method 2: Using web-ext (Recommended for Distribution)

Install web-ext:

npm install -g web-ext

Build:

cd firefox
web-ext build

This creates a signed ZIP in web-ext-artifacts/ folder.

Sign (requires Mozilla account):

# Get API keys from https://addons.mozilla.org/developers/addon/api/key/
web-ext sign \
  --api-key=YOUR_API_KEY \
  --api-secret=YOUR_API_SECRET

Run for testing:

web-ext run

This opens Firefox with your extension loaded.

---

Distribution Options

Option 1: Direct Distribution (Self-Hosted)

Chrome (.crx file):

1. Pack the extension (see above)
2. Host the .crx file on your website
3. Users download and drag it to chrome://extensions/
4. ⚠️ Chrome will show "unverified" warning

Firefox (.xpi file):

1. Create and sign the extension
2. Host the .xpi file on your website
3. Users click to install
4. ⚠️ Unsigned extensions need special Firefox config

Option 2: Official Store Distribution

Chrome Web Store:

1. Create developer account ($5 one-time fee)
2. Go to Chrome Web Store Developer Dashboard
3. Click "New Item"
4. Upload your ZIP file
5. Fill in listing details
6. Submit for review
7. ✅ Published after approval (usually 1-3 days)

Firefox Add-ons:

1. Create account at addons.mozilla.org
2. Submit new add-on
3. Upload your ZIP/XPI
4. Choose:
   • Listed: Public on addons.mozilla.org (requires review)
   • Unlisted: Self-distribute signed version (automatic)
5. ✅ Get signed version immediately (unlisted) or after review (listed)

---

Automation Scripts

I've created helper scripts for you:

package-chrome.sh

#!/bin/bash
cd chrome
zip -r ../dist/greasyboii-chrome-v1.0.4.zip * -x "*.DS_Store"
echo "✅ Chrome package created: dist/greasyboii-chrome-v1.0.4.zip"

package-firefox.sh

#!/bin/bash
cd firefox
zip -r ../dist/greasyboii-firefox-v1.0.4.zip * -x "*.DS_Store"
echo "✅ Firefox package created: dist/greasyboii-firefox-v1.0.4.zip"

package-all.sh

#!/bin/bash
mkdir -p dist

echo "📦 Packaging Chrome extension..."
cd chrome
zip -r ../dist/greasyboii-chrome-v1.0.4.zip * -x "*.DS_Store"
cd ..

echo "📦 Packaging Firefox extension..."
cd firefox
zip -r ../dist/greasyboii-firefox-v1.0.4.zip * -x "*.DS_Store"
cd ..

echo "✅ All packages created in dist/ folder!"
ls -lh dist/

---

File Checklist

Before packaging, ensure these files exist:

Chrome folder must have:

• ✅ manifest.json
• ✅ background.js
• ✅ content.js
• ✅ popup.html
• ✅ popup.css
• ✅ popup.js
• ✅ bootstrap.min.css
• ✅ bootstrap.bundle.min.js
• ✅ icon16.png
• ✅ icon48.png
• ✅ icon128.png

Firefox folder must have:

• ✅ manifest.json
• ✅ background.js
• ✅ content.js
• ✅ popup.html
• ✅ popup.css
• ✅ popup.js
• ✅ bootstrap.min.css
• ✅ bootstrap.bundle.min.js
• ✅ icon16.png
• ✅ icon48.png
• ✅ icon128.png

---

Testing Packaged Extension

Chrome:

1. Go to chrome://extensions/
2. Drag the .crx file into the window
3. Click "Add extension"
4. Test all features

Firefox:

1. Go to about:addons
2. Click gear icon → "Install Add-on From File"
3. Select your .xpi or .zip file
4. Click "Add"
5. Test all features

---

Version Updates

When releasing a new version:

1. Update version in manifests:

   "version": "1.0.5"
   

2. For Chrome:

   • Use the SAME .pem file when packing
   • This ensures it's recognized as an update

3. For Firefox:

   • Increment version number
   • Re-sign with same API keys
   • Upload to addons.mozilla.org

4. Update documentation:

   • README.md
   • CHANGELOG.md
   • Any version references

---

Common Issues

Chrome: "Package is invalid: CRX_REQUIRED_PROOF_MISSING"

• Solution: Users must enable "Developer mode" to install unsigned extensions
• Better solution: Publish on Chrome Web Store

Firefox: "This add-on could not be installed because it appears to be corrupt"

• Solution: Check ZIP file structure - files should be at root, not in a subfolder
• Fix: Re-create ZIP from inside the firefox folder

Chrome: "Extension update failed"

• Solution: Use the same .pem file for updates
• Lost .pem?: You'll need to create a new extension (new ID)

Firefox: "This add-on is not signed"

• Solution: Sign it with Mozilla or enable unsigned extensions
• Enable unsigned: about:config → xpinstall.signatures.required → false (Firefox Developer Edition only)

---

Security Notes

• ⚠️ Never commit .pem files to version control
• ⚠️ Keep your API keys secret
• ⚠️ Don't bundle unnecessary files (documentation, source maps, etc.)
• ✅ Only include required files in the package
• ✅ Test packaged version before distributing

---

Quick Commands Reference

# Create distribution folder
mkdir -p dist

# Package Chrome (ZIP for Web Store)
cd chrome && zip -r ../dist/greasyboii-chrome.zip * && cd ..

# Package Firefox (ZIP)
cd firefox && zip -r ../dist/greasyboii-firefox.zip * && cd ..

# Package Firefox (XPI)
cd firefox && zip -r ../dist/greasyboii-firefox.xpi * && cd ..

# Install web-ext (Firefox tool)
npm install -g web-ext

# Build with web-ext
cd firefox && web-ext build

# Run Firefox with extension
cd firefox && web-ext run

# Sign Firefox extension
cd firefox && web-ext sign --api-key=KEY --api-secret=SECRET

---

Next Steps

1. Test locally first - Make sure everything works
2. Create packages - Use scripts above
3. Test packages - Install and verify
4. Decide distribution method:
   • Self-host for personal use
   • Chrome Web Store for public Chrome users
   • Firefox Add-ons for public Firefox users
5. Update version numbers for future releases

---

Current Version: 1.0.4
Ready to Package: ✅ Yes
All Files Present: ✅ Yes

Happy packaging! 🐒✨