@browser-echo/vite

@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:

• Adds dev middleware to handle POST requests at /__client-logs
• Provides a virtual module virtual:browser-echo that initializes the client
• Optionally injects the virtual module import into your index.html
• 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