vite-terminal-error-logger

A universal Vite plugin that captures browser runtime try-catch errors and seamlessly logs them to the local terminal, featuring full Sourcemap path restoration and full-screen Error Overlay triggers in development.

简体中文

Features

• 🎯 Runtime Error Sync: Catch business/protocol initialization errors in browser and view them right in your Vite terminal.
• 🗺️ Accurate Sourcemap: Automatically maps compiled lines/columns back to your original .ts source files.
• ⚡ Vite Error Overlay: Intercepts errors and forces Vite's official full-screen red error box to show up, halting dangerous user interactions during development.
• 🪓 Zero Prod Footprint: Tied with import.meta.hot, meaning all debugging overhead is completely tree-shaken during vite build.

Installation

npm install vite-terminal-error-logger -D
# or with pnpm
pnpm add vite-terminal-error-logger -D

Usage

1. Configure Plugin in vite.config.ts

import { defineConfig } from "vite";
import { terminalErrorLogger } from "vite-terminal-error-logger";

export default defineConfig({
  plugins: [
    terminalErrorLogger({
      event: "app:check-error", // Custom HMR event name
      prefix: "protocol",       // Terminal log prefix inside [ ]
      title: "Definition Error" // Log title
    })
  ]
});

2. Capture and Send in Frontend (App.vue or Initialization Scripts)

Wrap your initialization checkers or boundary handlers:

import { ref } from "vue";

const isDevError = ref(false);

async function runCheckers() {
  try {
    // Your custom hardware protocol or business validation logic
    await validateUSBDevice(); 
  } catch (e) {
    console.error(e); // Optional fallback

    if (import.meta.hot) {
      const err = e instanceof Error ? e : new Error(String(e));
      
      // 1. Physically unmount business views to prevent further user interactions
      isDevError.value = true;
      
      // 2. Dispatch to Vite plugin via HMR WS
      import.meta.hot.send("app:check-error", {
        message: err.message,
        stack: err.stack ?? ""
      });
    }
  }
}

Options

| Property | Type | Default | Description | | ----------- | --------- | ------------------ | ------------------------------------------------------------------------------------------------ | | event | string | "terminal-error" | Custom HMR WebSocket event name. | | prefix | string | "error" | Log prefix enclosed in [ ] both in terminal and overlay header. | | title | string | "Runtime error" | Header description for the error context. | | sourcemap | boolean | true | Whether to reverse-map browser stacks back to original .ts source code via Vite's moduleGraph. |

License

MIT