Overview

bini-overlay is a Vite plugin bundle that replaces Vite's default vite-error-overlay with a polished development experience:

• A floating badge that animates during HMR updates, shows the current route type, and opens a preferences menu.
• A red issue pill that replaces the badge when something breaks.
• A full-screen error panel with a syntax-highlighted code frame, source-mapped call stack, and one-click "open in editor".

Everything is registered with apply: 'serve'. Nothing is injected into production builds.

Features

Status badge

Error panel

Installation

$ npm install bini-overlay --save-dev

Quick Start

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { biniOverlay } from 'bini-overlay'

export default defineConfig({
  plugins: [react(), biniOverlay()],
})

Options

interface BiniOverlayOptions {
  /**
   * App directory scanned for routes. Used to resolve the current page's
   * route type and to power the Route Info inspector.
   * Must match the `appDir` you pass to `biniroute()` if customised.
   * @default 'src/app'
   */
  appDir?: string

  /**
   * Hide the loading badge and its menu while keeping the error overlay.
   * @default false
   */
  disableBadge?: boolean

  /**
   * Editor binary used by "open in editor". When omitted, the first of
   * `code`, `cursor`, `zed`, `subl`, `webstorm` found on PATH is used.
   */
  editor?: string
}

Example:

biniOverlay({
  appDir: 'src/app',
  editor: 'cursor',
})

The Vite base config is picked up automatically for route matching, so no separate base-path option is needed. Code-frame highlighting always uses Shiki's dark-plus theme and is not configurable.

The Badge

By default the badge sits in the bottom-left corner.

Menu

Click the badge to open the menu.

Route Info

Shows the matched route path as a tree, including the layout files and page file that render it. Dynamic (:param) and catch-all (*) segments are tagged with a chip. Unmatched URLs show a "renders your 404 page" message. Requires bini-router >= 2.0.0.

Preferences

Preferences are stored in localStorage under bini-overlay:prefs. The session-hide flag lives in sessionStorage and is cleared when the tab closes.

The Error Panel

When an error occurs, the panel opens automatically.

Code frame example

    10: function Greeting() {
>>> 11:   const name = user.name
    12:   return <h1>Hello, {name}!</h1>
    13: }

Error lifecycle

1. Error occurs   -> badge becomes a red pill and the panel opens
2. Multiple errors -> navigate with prev/next; duplicates are merged
3. You fix it      -> HMR update arrives, resolved errors are cleared
4. All clear       -> panel closes and the badge returns to idle

HMR events

Unrecoverable errors

If the app has crashed so completely that nothing is rendered, or an error carries a component stack, the close button is hidden. The panel stays up until a successful HMR update recovers the page, so you never end up staring at a blank screen.

Reporting Errors From Your App

Errors thrown at runtime and unhandled rejections are captured automatically. To route errors from a React error boundary into the overlay, dispatch a __bini_error__ event:

componentDidCatch(error: Error, info: React.ErrorInfo) {
  window.dispatchEvent(
    new CustomEvent('__bini_error__', {
      detail: {
        name: error.name,
        message: error.message,
        stack: error.stack,
        componentStack: info.componentStack,
        type: 'runtime',
      },
    }),
  )
}

The overlay dispatches a __bini_clear_errors__ event on window after every successful HMR update, so a boundary can listen for it to reset itself:

useEffect(() => {
  const reset = () => setHasError(false)
  window.addEventListener('__bini_clear_errors__', reset)
  return () => window.removeEventListener('__bini_clear_errors__', reset)
}, [])

detail fields

Dev Server Endpoints

The plugins register the following middleware on the Vite dev server. They exist only during vite dev.

The route manifest is built lazily from appDir and invalidated automatically when files under it are added, changed, or removed.

Supported editors: code, cursor, zed, subl, webstorm. Pass the editor option to force a specific binary.

Security

The overlay exposes file-reading and process-launching endpoints, so they are locked down:

• Same-origin only. Requests are checked via Sec-Fetch-Site, falling back to an Origin/Host comparison. Cross-origin requests receive 403.
• Project-root confinement. Code-context and open-in-editor paths are resolved and rejected if they escape the current working directory.
• Dev server only. Every plugin uses apply: 'serve'; none run in vite build.

Architecture

biniOverlay() returns seven cooperating plugins:

Requirements

Version

Dependencies

Troubleshooting

• The overlay doesn't appear - confirm biniOverlay() is in plugins and that you're running vite dev, not a production build.
• Code frames have no colours - Shiki failed to load from esm.sh. Check network access; the overlay falls back to plain text.
• Route type / Route Info shows Not Found everywhere - bini-router isn't installed, or appDir doesn't match the value passed to biniroute().
• Stack frames point at transformed code - no source map is available for that file. Enable source maps in your Vite config.
• Clicking a stack frame does nothing - no supported editor was found on PATH. Pass the editor option to force a binary.
• 403 Forbidden from /__bini_* endpoints - the request came from a different origin. Open the app in a browser at the dev server's hostname rather than through a proxy.
• The badge is missing - it may be hidden for the session. Check the preferences, or clear the session-hide flag by closing the tab.
• The overlay stays open after a fix - wait for the HMR update to land. If it doesn't, the error may not belong to a module Vite can invalidate; reload the page.