Bini Overlay

A beautiful animated overlay badge for the Bini.js framework. Shows your Bini.js logo during development — animates on load and HMR updates, and hands off to a rich error overlay when something goes wrong.

Features

• ✨ Animated Logo — SVG path-drawing animation on page load, refresh, and every HMR update
• 🚨 Error Overlay — Powered by @visulima/vite-overlay with source maps, cause chain navigation, and intelligent fix suggestions
• 🔄 HMR Aware — Logo animates during hot reloads, hides on error, recovers automatically when fixed
• 🎯 Non-intrusive — Small circular badge fixed to the bottom-left corner
• 🎨 Bini.js Branding — Official Bini.js gradient logo and colors
• ⚡ Zero Configuration — Install and it just works
• 📱 Responsive — Adapts gracefully to mobile screens
• 🔒 Development Only — Never appears in production builds

Installation

# npm
npm install bini-overlay --save-dev

# pnpm
pnpm add bini-overlay -D

# yarn
yarn add bini-overlay --dev

Usage

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

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

How It Works

The balloon is your Bini.js logo inside a round black badge, fixed to the bottom-left corner. It has three states:

| State | Behaviour | |-------|-----------| | Loading | Logo draws itself with a stroke animation and pulses | | Idle | Logo sits quietly as a filled gradient icon | | Error | Badge hides completely — the @visulima/vite-overlay error screen takes over |

When an error is fixed and HMR fires the next update, the badge automatically reappears with the loading animation and returns to idle once the update is applied.

Configuration

biniOverlay({
  // Options passed directly to @visulima/vite-overlay
  errorOverlayOptions: {
    forwardConsole: true,
    forwardedConsoleMethods: ['error', 'warn'],
    solutionFinders: [],
  }
})

Environment variable

Disable the badge entirely without touching your config:

DISABLE_BINI_OVERLAY=true npm run dev

Requirements

| Dependency | Version | |------------|---------| | Node.js | >= 18.0.0 | | Vite | ^6.0.0 |

License

MIT