@maderatools/bridge

🚀 Development bridge for Chrome extension service worker logging

Automatically forward all your Chrome extension service worker logs to MADERA Helper DevTools panel!

Why?

Chrome's security prevents DevTools extensions from accessing other extensions' service worker logs. This bridge solves that by running inside your extension and forwarding logs to MADERA Helper.

Before: Open chrome://extensions → Click "service worker" → Look at console → Copy manually After: All logs automatically appear in MADERA Helper panel with 1-click copy! 🎉

Quick Start

Option 1: Auto-Install (Recommended! ⚡)

npx @maderatools/bridge install

That's it! The bridge will:

• 🔍 Scan for all Chrome extension projects
• 📦 Install the bridge in each one
• ✅ Add importScripts() automatically
• 🎉 Done!

Option 2: Manual Install

npm install --save-dev @maderatools/bridge

Then in your service worker:

// background.js
importScripts('node_modules/@maderatools/bridge/index.js');

// All your logs are now forwarded! 🎉
console.log('Service worker started');
console.error('Something went wrong');

Option 3: With Bundler (Webpack/Vite/etc.)

npm install --save-dev @maderatools/bridge

// background.js
import '@maderatools/bridge';

// Done! Logs are forwarded automatically
console.log('This appears in MADERA Helper!');

CLI Commands

Install Bridge

npx @maderatools/bridge install

Scans your workspace and installs bridge in all Chrome extension projects.

Update Bridge

npx @maderatools/bridge update

Updates the bridge to the latest version in all projects that have it.

Remove Bridge (Before Publishing!)

npx @maderatools/bridge remove

Removes bridge from all projects. Run this before publishing to Chrome Web Store!

List Projects

npx @maderatools/bridge list

Shows all detected Chrome extension projects in your workspace.

Usage

1. Install Bridge

Choose any installation method above.

2. Get MADERA Helper Extension ID

1. Open chrome://extensions
2. Enable "Developer mode"
3. Find "MADERA Helper"
4. Copy the extension ID (default: hdiebgpeehbbpipcpamhdacncaclomfi)

3. Use MADERA Helper

1. Reload your extension
2. Open DevTools (F12)
3. Click "MADERA Helper" tab
4. Select your extension from dropdown
5. Check "🔧 Test Mode"
6. All service worker logs appear automatically! 🎉

Features

Captures Everything

• ✅ console.log() → Regular logs
• ✅ console.error() → Errors (red)
• ✅ console.warn() → Warnings (yellow)
• ✅ console.info() → Info
• ✅ console.debug() → Debug
• ✅ console.trace() → With stack traces

Visual Indicators

Logs appear in MADERA Helper with:

• Green left border (service worker indicator)
• Extension name prefix: [Your Extension] Your log
• Timestamps
• Color coding by log level

Runtime Control

// In your service worker console:

// Disable bridge temporarily
MADERABridge.disable();
console.log('This will NOT be forwarded');

// Re-enable
MADERABridge.enable();
console.log('This WILL be forwarded');

// Restore original console
MADERABridge.restore();

// Check status
console.log(MADERABridge.version); // "1.0.0"

Workflow Example

Development

# Install once
npx @maderatools/bridge install

# Work on your extension
# All logs appear in MADERA Helper automatically!

# Update when new version is released
npx @maderatools/bridge update

Before Publishing

# Clean up for production
npx @maderatools/bridge remove

# Build and publish
npm run build
# Upload to Chrome Web Store

Advanced Usage

Environment-Based Loading

// background.js
if (process.env.NODE_ENV === 'development') {
  importScripts('madera-bridge.js');
}

// Or with bundler
if (import.meta.env.DEV) {
  import('@madera/bridge');
}

With Build Tools

Webpack:

// webpack.config.js
const CopyPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyPlugin({
      patterns: [
        {
          from: 'node_modules/@maderatools/bridge/index.js',
          to: 'madera-bridge.js'
        }
      ]
    })
  ]
};

Vite:

// vite.config.js
export default {
  build: {
    rollupOptions: {
      input: {
        background: 'src/background.js',
        bridge: 'node_modules/@maderatools/bridge/index.js'
      }
    }
  }
};

Multiple Workspaces

# Scan specific directory
npx @maderatools/bridge install /path/to/projects

# Or run from workspace root
cd ~/projects/extensions
npx @maderatools/bridge install

Troubleshooting

"No Chrome extension projects found"

Make sure you're running the command from a directory containing extension projects with manifest.json files.

"Bridge already installed"

The bridge is already present! Use npx @maderatools/bridge update to update it.

"Logs not appearing in MADERA Helper"

Check:

1. ✅ MADERA Helper extension is installed
2. ✅ Your extension is selected in MADERA Helper dropdown
3. ✅ "🔧 Test Mode" is checked
4. ✅ You've triggered your service worker (click extension icon, etc.)
5. ✅ MADERA Helper ID matches in the bridge file

"Error: Cannot find module"

If using importScripts(), make sure the path is correct:

// If bridge is in root
importScripts('madera-bridge.js');

// If bridge is in subfolder
importScripts('scripts/madera-bridge.js');

Security & Performance

Is it safe?

✅ YES! The bridge:

• Only forwards logs to MADERA Helper (nowhere else)
• Doesn't modify extension behavior
• Runs entirely locally
• Open source - inspect the code!

Performance impact?

⚡ Minimal! Adds ~1ms per log statement (imperceptible).

Should I remove it before publishing?

🚫 YES! Always remove before publishing:

npx @maderatools/bridge remove

The bridge is development only - don't ship it to production!

Contributing

Found a bug? Have an idea? Open an issue!

License

MIT

Related

• MADERA Helper - The DevTools extension
• MADERA Bridge Manual Installation Guide

Happy debugging! 🚀