DocsPluginsShowcaseReleases
npmStar us on GitHub
overviewcreate-bini-appbini-deploybini-routerbini-envbini-nativebini-serverbini-overlaybini-ssgvite plugins↗hono plugins↗

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

bini-overlay

Official

Development overlay for Bini.js: an animated status badge, route inspector, and full-screen error panel.

Overview

bini-overlay gives your Bini.js project a polished development experience by replacing Vite's default error screen. It adds a floating status badge, a route inspector, and a full-screen error panel with syntax-highlighted code frames.

Requirements

  • Node.js >= 18.0.0
  • Vite >= 8.0.0
  • bini-router >= 2.0.0

Install

>_Terminal
$ npm install bini-overlay --save-dev

Quick Start

Register the plugin in your Bini.js config. biniOverlay() returns an array of plugins, which Vite automatically flattens, so add it to your plugins array as-is.

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

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

Options

To hide the floating badge, set disableBadge to true:

vite.config.ts
import { defineConfig } from 'vite'
import { biniOverlay } from 'bini-overlay'

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

The Badge

The badge is injected into the page so it never collides with your app's CSS. By default, it sits in the bottom-left corner.

StateAppearanceBehaviour
LoadingLogo draws itself with an animationPlays on page load and on each HMR update
IdleFilled gradient logoDefault state when there are no errors
ErrorRed pill showing 1 Issue / N IssuesClick the count to open the error panel

Menu & Preferences

Clicking the badge opens a menu showing the current route type (Static, Dynamic, or Not Found) and a link to the Route Info inspector.

The Preferences popover lets you change the Theme (System, Light, Dark), Position (4 corners), Size (Small, Medium, Large), and record a custom keyboard Shortcut (default Alt+B) to toggle the badge's visibility.

The Error Panel

When an error occurs, a full-screen panel opens automatically. It catches runtime errors, unhandled rejections, build errors, and errors reported by your error boundaries.

Code Frames & Stacks

The panel displays five lines of code around the error, with the failing line clearly marked. Call stacks are mapped back to your original source code.

Application frames are clickable and will open your editor at the exact line. Framework frames are collapsed by default to keep the panel clean.

Reporting Errors

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

ErrorBoundary.tsx
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 also dispatches a __bini_clear_errors__ event on window after every successful HMR update, so your boundary can listen for it to reset itself:

ErrorBoundary.tsx
useEffect(() => {
  const reset = () => setHasError(false)
  window.addEventListener('__bini_clear_errors__', reset)
  return () => window.removeEventListener('__bini_clear_errors__', reset)
}, [])
Was this helpful?
Previousbini-server
Nextbini-ssg

On this page

  • Overview
  • Requirements
  • Install
  • Quick Start
  • Options
  • The Badge
  • The Error Panel
  • Reporting Errors
Edit this page on GitHub

bini-overlay

Official

Development overlay for Bini.js: an animated status badge, route inspector, and full-screen error panel.

Overview

bini-overlay gives your Bini.js project a polished development experience by replacing Vite's default error screen. It adds a floating status badge, a route inspector, and a full-screen error panel with syntax-highlighted code frames.

Requirements

  • Node.js >= 18.0.0
  • Vite >= 8.0.0
  • bini-router >= 2.0.0

Install

>_Terminal
$ npm install bini-overlay --save-dev

Quick Start

Register the plugin in your Bini.js config. biniOverlay() returns an array of plugins, which Vite automatically flattens, so add it to your plugins array as-is.

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

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

Options

To hide the floating badge, set disableBadge to true:

vite.config.ts
import { defineConfig } from 'vite'
import { biniOverlay } from 'bini-overlay'

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

The Badge

The badge is injected into the page so it never collides with your app's CSS. By default, it sits in the bottom-left corner.

StateAppearanceBehaviour
LoadingLogo draws itself with an animationPlays on page load and on each HMR update
IdleFilled gradient logoDefault state when there are no errors
ErrorRed pill showing 1 Issue / N IssuesClick the count to open the error panel

Menu & Preferences

Clicking the badge opens a menu showing the current route type (Static, Dynamic, or Not Found) and a link to the Route Info inspector.

The Preferences popover lets you change the Theme (System, Light, Dark), Position (4 corners), Size (Small, Medium, Large), and record a custom keyboard Shortcut (default Alt+B) to toggle the badge's visibility.

The Error Panel

When an error occurs, a full-screen panel opens automatically. It catches runtime errors, unhandled rejections, build errors, and errors reported by your error boundaries.

Code Frames & Stacks

The panel displays five lines of code around the error, with the failing line clearly marked. Call stacks are mapped back to your original source code.

Application frames are clickable and will open your editor at the exact line. Framework frames are collapsed by default to keep the panel clean.

Reporting Errors

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

ErrorBoundary.tsx
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 also dispatches a __bini_clear_errors__ event on window after every successful HMR update, so your boundary can listen for it to reset itself:

ErrorBoundary.tsx
useEffect(() => {
  const reset = () => setHasError(false)
  window.addEventListener('__bini_clear_errors__', reset)
  return () => window.removeEventListener('__bini_clear_errors__', reset)
}, [])
Was this helpful?
Previousbini-server
Nextbini-ssg

On this page

  • Overview
  • Requirements
  • Install
  • Quick Start
  • Options
  • The Badge
  • The Error Panel
  • Reporting Errors
Edit this page on GitHub