@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

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

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 }; // default: disabled
}

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'
  }
})

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