Asmodeus 🔥

Zero-dependency Firefox addon development tool with hot reload

Develop Firefox addons without npm supply chain risks. No dependencies. Just Node.js built-ins.

Why Asmodeus?

• 🛡️ ZERO npm dependencies - no supply chain attack surface
• 🔥 Hot reload - changes detected and addon reloaded instantly
• 🚀 Simple - one command to start developing
• 📦 Tiny - ~600 lines of auditable code
• 🔧 Powerful - uses Firefox Remote Debugging Protocol directly

vs web-ext: 0 dependencies vs 27+ packages, 600 lines vs 50,000+ lines

Installation

npm install -D asmodeus
# or globally
npm install -g asmodeus

Quick Start

In your Firefox addon directory:

asmodeus

That's it! Asmodeus will:

1. 🦊 Launch Firefox with remote debugging
2. 📦 Temporarily install your addon
3. 👀 Watch for file changes
4. 🔄 Auto-reload on save

Requirements

• Node.js 16+
• Firefox installed
• A manifest.json with an addon ID:

{
  "browser_specific_settings": {
    "gecko": {
      "id": "[email protected]"
    }
  }
}

Configuration

Use environment variables:

# Custom Firefox binary
FIREFOX_BINARY=/usr/bin/firefox-developer-edition asmodeus

# Custom Firefox profile
FIREFOX_PROFILE=~/.mozilla/firefox/dev-profile asmodeus

# Custom RDP port
RDP_PORT=6006 asmodeus

# Run headless
HEADLESS=true asmodeus

What Gets Watched

All files in your addon directory except:

• .git/
• node_modules/
• web-ext-artifacts/
• .vscode/
• dist/, build/

Manual Reload

node node_modules/asmodeus/lib/reload-addon.js [email protected]

How It Works

Asmodeus uses Firefox's built-in Remote Debugging Protocol (RDP):

1. Starts Firefox with --start-debugger-server
2. Connects via TCP to port 6005
3. Uses RDP messages to install and reload addons
4. Watches filesystem with Node's built-in fs.watch()

RDP Protocol

Simple message format: BYTE_LENGTH:JSON_DATA

// Example: getRoot request
'21:{"to":"root","type":"getRoot"}'

// Example: installTemporaryAddon
'{"to":"server1.conn0.addonsActor1","type":"installTemporaryAddon","addonPath":"/path/to/addon"}'

Security Benefits

Traditional approach (web-ext):

• 27+ npm packages (not counting nested dependencies)
• Transitive dependencies
• Automatic updates can break things
• Supply chain attack surface

Asmodeus:

• 0 npm packages
• Uses only Node.js built-ins: net, fs, child_process
• Easy to audit (~600 lines total)
• Complete control over all code

Files

• bin/asmodeus.js - Main executable (~300 lines)
• lib/rdp-client.js - RDP protocol implementation (~280 lines)
• lib/reload-addon.js - Manual reload utility (~30 lines)

Total: ~610 lines of simple, auditable code

API Usage

You can also use Asmodeus programmatically:

import { ExtensionReloader } from 'asmodeus/rdp-client';

const reloader = new ExtensionReloader(6005, 'localhost');

await reloader.connect();
await reloader.reloadAddon('[email protected]');
reloader.disconnect();

Troubleshooting

Firefox doesn't launch

FIREFOX_BINARY=/path/to/firefox asmodeus

Connection refused

• Firefox might take a few seconds to start RDP server
• Check that port 6005 isn't already in use
• Make sure Firefox is running with debugging enabled

Addon not found

• Verify manifest.json has browser_specific_settings.gecko.id
• The ID must match what you pass to reload commands

Contributing

Contributions welcome! This project aims to stay dependency-free.

License

MIT

Name

Asmodeus (אַשְמְדּאָי) - In demonology, one of the seven princes of Hell. In this context: the daemon that watches over your addon development, reloading it when needed. Perfect for a hot-reload development tool! 😈