@browser-echo/vite

Vite plugin for streaming browser console logs to your dev terminal with colors, stack traces, and optional file logging.

This package provides a Vite plugin that includes dev middleware and a virtual module to forward browser console logs to your terminal during development. Works with React, Vue, TanStack Start, and any Vite-based project.

Table of Contents

• Vue + Vite
• React + Vite
• TanStack Start
• Configuration Options
• Install MCP Server

Features

• Vite plugin with built-in dev middleware
• Virtual module for automatic client initialization
• Optional file logging (unique to Vite provider)
• Colorized terminal output
• Full stack trace support with multiple modes
• Works with index.html or server-side rendered apps
• Optional network capture (opt-in): fetch, XMLHttpRequest, WebSocket
• Optional request/response body snippets (opt-in) with safe truncation

Installation

npm install -D @browser-echo/vite
# or
pnpm add -D @browser-echo/vite

Usage Examples

Vue + Vite

npm install -D @browser-echo/vite
# or
pnpm add -D @browser-echo/vite

// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import browserEcho from '@browser-echo/vite';

export default defineConfig({
  plugins: [
    vue(),
    browserEcho({
      // Optional configuration
      stackMode: 'condensed',
      colors: true,
    }),
  ],
});

That's it! Your Vue app will now stream console logs to your terminal during development.

React + Vite

npm install -D @browser-echo/vite
# or
pnpm add -D @browser-echo/vite

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import browserEcho from '@browser-echo/vite';

export default defineConfig({
  plugins: [
    react(),
    browserEcho({
      // Optional configuration
      stackMode: 'condensed',
      colors: true,
    }),
  ],
});

Your React app will now stream console logs to your terminal during development.

TanStack Start

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import browserEcho from '@browser-echo/vite';

export default defineConfig({
  plugins: [
    react(),
    browserEcho({
      injectHtml: false, // Important: TanStack Start doesn't use index.html
      stackMode: 'condensed',
      fileLog: { enabled: true },
    }),
  ],
});

Important for TanStack Start: Since TanStack Start renders without an index.html, you need to set injectHtml: false and import the virtual module manually in your router:

// src/router.tsx
if (import.meta.env.DEV && typeof window !== 'undefined') {
  void import('virtual:browser-echo');
}

Configuration Options

interface BrowserEchoViteOptions {
  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]'
  colors?: boolean;                  // default: true
  injectHtml?: boolean;              // default: true
  stackMode?: 'none' | 'condensed' | 'full'; // default: 'condensed'
  showSource?: boolean;              // default: true
  batch?: { size?: number; interval?: number }; // default: 20 / 300ms
  truncate?: number;                 // default: 10_000 chars
  fileLog?: { enabled?: boolean; dir?: string; split?: boolean }; // default: disabled
  mcp?: { 
    url?: string;                    // MCP server base URL (auto-discovered if not set)
    routeLogs?: `/${string}`;        // MCP logs route (default: '/__client-logs')
    suppressTerminal?: boolean;      // Suppress terminal output when forwarding (default: auto)
    headers?: Record<string,string>; // Custom headers for MCP requests
  };
  discoverMcp?: boolean;             // Enable MCP auto-discovery (default: true)
  discoveryRefreshMs?: number;       // Discovery refresh interval (default: 30000)
  networkLogs?: {
    enabled?: boolean;
    captureFull?: boolean;
    bodies?: {
      request?: boolean;
      response?: boolean;
      maxBytes?: number;                       // default 2048 bytes
      allowContentTypes?: string[];            // default ['application/json','text/','application/x-www-form-urlencoded']
      prettyJson?: boolean;                    // default true
    };
  }; // default disabled
}

Install MCP Server

The Vite plugin automatically discovers and forwards logs to MCP servers. No configuration needed in most cases!

📖 First, set up the MCP server for your AI assistant, then configure framework options below.

Auto-Discovery (Default)

browserEcho({
  // MCP auto-discovery enabled by default
  // Logs forward to MCP when detected, terminal output suppressed
})

Manual Configuration

browserEcho({
  mcp: {
    url: 'http://127.0.0.1:5179',           // Explicit MCP base URL
    suppressTerminal: false,                 // Keep terminal output even when forwarding
    headers: { 'Authorization': 'Bearer ...' } // Custom headers if needed
  }
})

Network body snippets (opt-in)

browserEcho({
  networkLogs: {
    enabled: true,
    bodies: {
      request: true,
      response: true,
      maxBytes: 2048,
      allowContentTypes: ['application/json','text/','application/x-www-form-urlencoded'],
      prettyJson: true
    }
  }
})

Output example:

[NETWORK] [POST] [/api/users] [200] [18ms]
    req: {"name":"Ada"}
    res: { "id": 1, "name": "Ada" }

Disable MCP

browserEcho({
  discoverMcp: false,  // Disable auto-discovery
  mcp: { url: '' }     // Disable explicit MCP
})

Environment Variables

• BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp — Set MCP server URL
• BROWSER_ECHO_SUPPRESS_TERMINAL=1 — Force suppress terminal output
• BROWSER_ECHO_SUPPRESS_TERMINAL=0 — Force show terminal output
• BROWSER_ECHO_FILE_LOG=true — Enable MCP-side file logging (ingest server)
• BROWSER_ECHO_SPLIT_LOGS=true — Split logs into logs/frontend vs combined

Discovery behavior

Discovery order: BROWSER_ECHO_MCP_URL → port 5179 (dev) → project-local .browser-echo-mcp.json.

File Logging (Vite-only feature)

Enable optional file logging to write browser logs to disk:

browserEcho({
  fileLog: { 
    enabled: true, 
    dir: 'logs/frontend' // default: 'logs/frontend'
  }
})

Split file logs by tag

Write separate files under per-tag subdirectories (e.g. logs/network/dev-*.log):

browserEcho({
  fileLog: {
    enabled: true,
    dir: 'logs',
    split: true
  },
  networkLogs: { enabled: true }
})

This produces, for example:

• logs/browser/dev-YYYY-MM-DDTHH-MM-SS.log
• logs/network/dev-YYYY-MM-DDTHH-MM-SS.log
• logs/worker/dev-YYYY-MM-DDTHH-MM-SS.log

How it works

The plugin:

1. Adds dev middleware to handle POST requests at /__client-logs
2. Provides a virtual module virtual:browser-echo that initializes the client
3. Optionally injects the virtual module import into your index.html
4. Prints formatted logs to your terminal with colors and stack traces

Dependencies

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

Troubleshooting

• No logs appear: Ensure the plugin is added and either index.html exists or you import the virtual module manually
• Too noisy: Limit to include: ['warn','error'] and use stackMode: 'condensed'
• Duplicate logs in browser: Set preserveConsole: false

Author

Kevin Kern

License

MIT

Links

• Main Repository
• Documentation
• Core Package