@browser-echo/nuxt

@browser-echo/nuxt

Nuxt 3/4 module for streaming browser console logs to your dev terminal.

This Nuxt module registers a Nitro server route and a client plugin (dev-only) with zero manual wiring beyond adding the module to your configuration.

Features

• Zero-config Nuxt 3/4 module
• Automatic Nitro server route registration
• Client plugin auto-injection
• Configurable via nuxt.config.ts
• Works with Nuxt's dev proxy setup
• No production impact

Installation

pnpm add -D @browser-echo/nuxt

Setup

Add the module to your Nuxt configuration:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@browser-echo/nuxt'],
  
  // Optional configuration
  browserEcho: {
    route: '/__client-logs',
    include: ['warn', 'error'],
    tag: '[web]',
    batch: { size: 20, interval: 300 },
    preserveConsole: true,
    stackMode: 'condensed', // 'full' | 'condensed' | 'none'
  }
});

That's it! Run nuxi dev and open your app—your server terminal will show browser logs.

Configuration Options

interface BrowserEchoNuxtOptions {
  enabled?: boolean;                 // default: true (dev only)
  route?: `/${string}`;              // default: '/__client-logs'
  include?: BrowserLogLevel[];       // default: ['log','info','warn','error','debug']
  preserveConsole?: boolean;         // default: true
  tag?: string;                      // default: '[browser]'
  batch?: { size?: number; interval?: number }; // default: 20 / 300ms
  stackMode?: 'full' | 'condensed' | 'none';    // default: 'condensed'
}

Stack Mode Options

• full: Send complete filtered stack trace
• condensed (default): Send only the top application frame
• none: Do not send any stack frames

Usage Example

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@browser-echo/nuxt'],
  
  browserEcho: {
    // Only forward warnings and errors
    include: ['warn', 'error'],
    
    // Custom tag for terminal output
    tag: '[frontend]',
    
    // Reduce noise with condensed stacks
    stackMode: 'condensed',
    
    // Batch settings for performance
    batch: { 
      size: 10,    // Send after 10 logs
      interval: 500 // Or after 500ms
    }
  }
});

How it works

• The module registers a Nitro server route at /__client-logs (configurable)
• A client plugin is automatically added that initializes browser log forwarding
• Browser console logs are batched and sent to the server route
• Logs are printed to your terminal with formatting and colors
• Everything is automatically disabled in production

Development vs Production

• Development: Module is active, logs are forwarded to terminal
• Production: Module is completely disabled, no client code is injected

Nitro Route Registration

The module registers the route directly with Nitro to avoid issues with Nuxt's dev proxy setup. This ensures reliable log forwarding even in complex development environments.

Dependencies

This package depends on @browser-echo/core for the client-side functionality.

Important Notes

• After changing browserEcho options, restart the Nuxt dev server to regenerate the client plugin
• If you run a custom reverse proxy, ensure the log route remains same-origin and not behind auth in dev
• The module only operates in development mode and has zero production impact

Troubleshooting

• No logs appear: Confirm the module is in modules[] and you're in dev mode
• Route conflicts: Change the route option if /__client-logs conflicts with your app
• Too many logs: Use include: ['warn', 'error'] and stackMode: 'condensed'
• Proxy issues: The module registers a Nitro route directly to avoid proxy complications

Author

Kevin Kern

License

MIT

Links

• Main Repository
• Documentation
• Core Package