vite-browser

Know why your Vite app broke — not just where.

Runtime diagnostics CLI for Vite applications. Connect to a running dev server, correlate errors with recent HMR activity, trace store-to-render propagation paths, and inspect framework state — all from the terminal, with zero project setup.

Built for developers and AI coding agents alike.

📖 Documentation · 📦 npm

Install

Agent Skill (recommended):

npx skills add MapleCity1314/vite-browser

CLI only:

npm install -g @presto1314w/vite-devtools-browser
npx playwright install chromium

The problem

You save a file. Vite hot-updates. The page breaks.

The error overlay tells you what failed — but not which update caused it, how the change propagated through your component tree, or whether the real problem is a stale store, a broken import, or a network regression.

What vite-browser does

# 1. See the current error with source context
$ vite-browser errors --mapped --inline-source

TypeError: Cannot read properties of undefined (reading 'items')
  → /src/components/CartSummary.tsx:14:12
    14 | total = cart.items.reduce(...)

# 2. Correlate with recent HMR activity
$ vite-browser correlate errors --mapped --window 5000

Confidence: high
HMR update observed within 5000ms of the current error
Matching modules: /src/store/cart.ts

# 3. Trace the propagation path
$ vite-browser diagnose propagation --window 5000

Status: fail | Confidence: high
Store → Render → Error path found:
  store: cart (changedKeys: items)
  render: AppShell > ShoppingCart > CartSummary

Four commands. You know the store update broke the render path. You know where to fix it.

Key features

• Error correlation — Match errors against recent HMR-updated modules within a time window
• Propagation diagnosis — Trace store → render → error paths with confidence levels
• HMR diagnosis — Detect patterns like missing-module, circular-dependency, hmr-websocket-closed
• Framework inspection — Vue trees, Pinia stores, Vue Router; React trees, Zustand stores, hook diagnostics, commit tracing; Svelte trees
• Mapped errors — Source-mapped stack traces with inline source snippets
• Screenshot — Full-page capture for visual verification; multimodal AI agents can "see" the page to confirm fixes or catch layout/style regressions that don't surface in logs
• Zero config — No plugins, no project changes. Works with any running Vite dev server

Agent Skills

vite-browser is designed skill-first. The skill router automatically picks the right debugging workflow based on the symptom:

Symptom	Routed to
Broad / unclear failure	core-debug
Recent edit or HMR breakage	runtime-diagnostics
Wrong data or failed requests	network-regression
Pre-merge verification	release-smoke

AI coding agents (Claude Code, Codex, Cursor) follow the structured workflow instead of guessing.

→ Agent Skills guide · AI IDE Setup

Quick reference

# Browser
vite-browser open <url>          # Launch and navigate
vite-browser close               # Close browser and daemon

# Diagnostics
vite-browser errors --mapped --inline-source
vite-browser correlate errors --mapped --window <ms>
vite-browser correlate renders --window <ms>
vite-browser diagnose hmr --limit <n>
vite-browser diagnose propagation --window <ms>

# Framework
vite-browser detect
vite-browser vue tree | vue pinia | vue router
vite-browser react tree
vite-browser react store list | react store inspect <name>
vite-browser react hook health | react hook inject
vite-browser react commits [--limit <n>] | react commits clear
vite-browser svelte tree

# Vite runtime
vite-browser vite runtime
vite-browser vite hmr trace --limit <n>
vite-browser vite module-graph trace --limit <n>

# Utilities
vite-browser screenshot                # Full-page capture (visual verification)
vite-browser logs | network | eval <script>

→ Full CLI reference

Current scope

v0.3.6 is the current stable release. It provides reliable runtime state surfacing, error-HMR correlation, common HMR failure pattern detection, and store → render → error path narrowing for both Vue + Pinia and React + Zustand workflows.

React support includes component tree inspection, Zustand store discovery and state reading, bundled DevTools hook (zero-config, no browser extension needed), hook diagnostics, and lightweight commit tracing.

correlate renders and diagnose propagation are high-confidence narrowing tools, not strict causal proof. They intentionally produce conservative output when evidence is incomplete.

Development

pnpm install
pnpm build
pnpm test

Requirements: Node.js ≥ 20 · Chromium via Playwright · Running Vite dev server

License

MIT