WXT Console Forward Module

A WXT module that forwards console logs from web extension scripts (background, content, popup, and inpage) to the development server console. This makes debugging web extensions much easier by aggregating all logs in one place.

Features

- ✅ Development Mode Only - Only works in development mode for security
- ✅ All Contexts Supported - Background, content scripts, popup, and injected inpage scripts
- ✅ Port Configuration Support - Respects custom port settings from wxt.config.ts dev server configuration
- ✅ Dynamic Port Detection - Automatically detects and uses the configured WXT dev server port
- ✅ Error Forwarding - Captures unhandled errors and promise rejections
- ✅ Context Identification - Clearly identifies which script context logs come from
- ✅ Object & Array Logging - Properly serializes complex objects
- ✅ Stack Traces - Forwards complete error stack traces
- ✅ Automatic Injection - No manual setup required in your scripts
- ✅ Configurable - Customize logging levels, endpoints, and exclusions

Installation

``bash
npm install wxt-module-console-forward
`

Usage

Add the module to your wxt.config.ts:

`typescript
import { defineConfig } from 'wxt';

export default defineConfig({
modules: ['wxt-module-console-forward'],

// Optional: Custom dev server port (module will automatically use this)
dev: {
server: {
port: 5175, // Module will respect this port configuration
},
},

// Optional console forwarding configuration
consoleForward: {
enabled: true, // Only works in dev mode anyway
endpoint: '/api/debug/client-logs',
levels: ['log', 'warn', 'error', 'info', 'debug'],
excludeEntrypoints: [], // Array of entrypoint names to exclude
silentOnError: false, // Show warnings when server is down
forwardErrors: true, // Forward unhandled errors and promise rejections
},
});
`

That's it! Now when you run wxt, all console logs from your extension scripts will appear in your terminal.

Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| enabled | boolean | true (dev mode only) | Whether to enable console forwarding |
| endpoint | string | '/api/debug/client-logs' | API endpoint for receiving logs |
| levels | string[] | ['log', 'warn', 'error', 'info', 'debug'] | Console levels to forward |
| excludeEntrypoints | string[] | [] | Entrypoint names to exclude from logging |
| silentOnError | boolean | true | Don't show warnings when server is down |
| forwardErrors | boolean | true | Forward unhandled errors and promise rejections |

Example Output

When you run your extension, you'll see logs like this in your terminal:

`
[background:service-worker] [log] Service worker started (chrome-extension://...)
[content:main-world] [log] Content script started on: https://example.com
[popup:main-world] [info] Extension popup opened
[inpage:main-world] [log] Inpage script started - running in main world context
[background:service-worker] [error] Test background error with stack trace
at Object.main (background.ts:23:11)
at background.ts:45:5
`

How It Works

The module:

1. Creates Virtual Modules - Uses Vite's virtual module system to inject console forwarding code
2. Automatic Injection - Automatically injects the forwarding code into all your entrypoints
3. Context Detection - Identifies whether code is running in background, content, popup, or inpage context
4. Log Buffering - Batches logs before sending to reduce network overhead
5. Dev Server Middleware - Adds middleware to your dev server to receive and display logs

Example Extension

Check out the example-extension/ directory for a complete demo that showcases:

- Background Script - Service worker logging, errors, and periodic logs
- Content Script - DOM interaction logging, event handlers, and page analysis
- Popup Interface - Interactive buttons to test different logging scenarios
- Inpage Script - Main world context logging with page interaction

$3

`bash
cd example-extension
bun install
bun run dev
`

Then load the extension in Chrome and:
1. Open the popup to test interactive logging
2. Visit any webpage to see content script logs
3. Check your terminal to see all logs aggregated together

Context Types

The module automatically detects and labels different execution contexts:

- background:service-worker - Background service worker
- content:main-world - Content script in isolated world
- popup:main-world - Extension popup
- inpage:main-world - Injected script in page's main world
- unknown:unknown-context - Fallback for undetected contexts

Development

`bash


Install dependencies

bun install

Run the example extension

bun run dev

Build the module

bun run build
`

Testing

`bash


Run tests (headless)

bun run test

Run tests with visible browser

HEADED=1 bun run test
``

Requirements

- WXT >=0.19.0
- Vite ^5.0.0, ^6.0.0, or ^7.0.0
- Development mode only (automatically disabled in production)

License

MIT