@ 浏览器- echo/ vite

用于将浏览器控制台日志流到您的 Dev 终端的 Vite 插件, 上面有颜色、 堆栈痕迹和可选的文件记录 .

这个软件包提供了一个Vite插件,包括dev中件和一个虚拟模块,在开发过程中将浏览器控制台日志转发到您的终端. 与React,Vue,TanStack Start合作,以及任何基于Vite的项目.

目录

• Vue + 维特
• 反应 + Vite
• TanStack 启动
• 配置选项
• 安装 MCP 服务器

特征

• 带有内置 dev 中间软件的 Vite 插件
• 自动客户端初始化虚拟模块
• 可选文件记录( 与 Vite 提供者独有)
• 彩色终端输出
• 多个模式的完整堆栈跟踪支持
• 与 index.html 或服务器端提供的应用程序
• 可选网络抓取( opt- in): 抓取, XMLHttp Request, WebSocket
• 可选请求/应答机身片段(可选入),安全截取

安装

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

用法实例

Vue + 维特

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,
    }),
  ],
});

就这样! 您的 Vue app 将在开发期间将控制台日志流到您的终端 .

反应 + 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,
    }),
  ],
});

您的回放应用程序将在开发期间将控制台日志流到您的终端 .

TanStack 启动

// 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 },
    }),
  ],
});

对 TanStack 启动很重要: 自从TanStack以来 开始制作,没有 index.html,需要设置 injectHtml: false 并手动在路由器中导入虚拟模块 :

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

配置选项

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
}

安装 MCP 服务器

Vite插件自动发现并转发日志到MCP服务器. 多数情况下不需要配置!

📖 首先,设置 MCP 服务器 ,然后配置下面的框架选项.

自动发现( 默认)

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

手动配置

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

网络正文片断( opt- in)

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

输出示例 :

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

禁用 MCP

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

环境变量

• BROWSER_ECHO_MCP_URL=http://127.0.0.1:5179/mcp 设置 MCP 服务器 URL
• BROWSER_ECHO_SUPPRESS_TERMINAL=1 - 强制压制终端输出
• BROWSER_ECHO_SUPPRESS_TERMINAL=0 — 部队显示终端输出
• BROWSER_ECHO_FILE_LOG=true ——启用 MCP- side 文件记录( 最小服务器)
• BROWSER_ECHO_SPLIT_LOGS=true ——将日志分解为日志/前端对齐

发现行为

发现顺序 : BROWSER_ECHO_MCP_URL 港口 5179(dev) 当地项目 .browser-echo-mcp.json。 。 。 .

文件日志( 只有图像特性)

启用可选文件记录将浏览器日志写入磁盘 :

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

按标签分割文件日志

将单独的文件写入每个标签子目录(例如. logs/network/dev-*.log:

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

例如,这产生了:

• 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

如何运作

插件 :

1. 添加 dev 中间软件处理 POST 请求 /__client-logs
2. 提供虚拟模块 virtual:browser-echo 初始化客户端
3. 可选地将虚拟模块导入到您的 index.html
4. 用颜色和堆放痕迹打印格式化日志到终端

依赖关系

此软件包取决于 @ 浏览器- echo/ 核心 用于客户端功能.

解决问题

• 没有日志: 确保添加插件并同时添加其中之一 index.html 已存在或您手动导入虚拟模块
• 太大声了: 限制 include: ['warn','error'] 和使用情况 stackMode: 'condensed'
• 浏览器中的复制日志设置 preserveConsole: false

作者

凯文克恩

许可证

麻省理工学院

链接

• 主仓库
• 文档
• 核心软件包