@ape-egg/vite-plugin-vibe

⚠️ Early alpha — subject to change. This plugin is a development-only HMR layer for Vibe. Vibe itself is still evolving, so achieving full 1-to-1 feature parity is a moving target — and not the priority right now.

Because the plugin only runs in development (it powers vite dev HMR and is never shipped to production), it is acceptable for it to have rough edges while Vibe stabilises. It updates alongside Vibe, will keep catching up to new runtime features, and will reach a stable release once the underlying framework settles.

Vite plugin for Vibe projects. Gives you hot refresh of components and pages without losing state — window.$ is untouched across edits.

Install

bun add -d @ape-egg/vite-plugin-vibe
# or
npm install -D @ape-egg/vite-plugin-vibe

Usage

// vite.config.js
import { defineConfig } from 'vite';
import vibe from '@ape-egg/vite-plugin-vibe';

export default defineConfig({
  plugins: [vibe()],
});

That's it. bun dev / vite now serves your Vibe project with:

• Component HMR — saving a file in components/ patches exactly what changed in every mounted instance: a text node, an attribute, a binding expression, an iteration or conditional template, a <style> rule. Scroll position, DOM identity, focus and component state survive; a changed <script type="module"> re-mounts the component
• Page HMR — saving an HTML page patches the page body the same way; a changed page <script> reloads, since a boot script defines initial state and cannot be re-run in place
• JS module HMR — saving a plain .js module re-seeds the state it fed: every key of window.$ (and of component states) that holds a value the module exported is assigned the fresh module's value, and Vibe re-renders what reads it. vibe({ ...demo }) follows demo.js with no import.meta.hot.accept in your code. Pages that never imported the module are left alone; a module that seeds no state on a page reloads that page only
• Normal reload fallback — pages without Vibe on them reload normally
• Component preview — an opt-in gallery at /__vibe (see below)

Component preview

Opt-in: enable it with a boolean flag, then open /__vibe while the dev server is running. Every component in your project shows up automatically — no registration, no maintained manifest. Adding a file under components/ makes it appear.

vibe({ preview: true })            // enable with defaults

• Router page (/__vibe) lists all components grouped by folder, with a name filter and a count.
• Per-component page (/__vibe/<path>) renders the component standalone in an isolated stage (its own window.$, so nothing leaks between components), with:
  • a DataInspector showing the component's declared state + the inputs it reads (@[name], <!-- each name as x -->). Each key has a type toggle (string / number / array / object); editing a value updates the live preview.
  • an editable source view (powered by @ape-egg/codie) — edits re-mount the preview instantly and are never written to disk.

State for each component lives in a single committed __vibe.component-previewer.json at your project root, keyed by component path. The plugin keeps it in sync with your components automatically (adds new keys, prunes removed ones, preserves any types you set). When the preview is disabled this file is never written or updated.

The preview is plain static-deployable output: bakePreview() (from @ape-egg/vite-plugin-vibe/preview) emits the whole gallery — pages, component list, analysis, fixtures, and sources — as static files with no backend, so it can be hosted or shared. In a baked deploy, type-toggles and source edits still work but persist only in the browser session.

Options

vibe({
  components: 'components', // directory to serve raw + watch for HMR (default: 'components')

  // Preview is OFF by default. Enable with `preview: true`, or pass an object
  // with `enabled: true` plus configuration. Anything else (omitted, false, or
  // an object without `enabled`) leaves it disabled — and never writes the
  // __vibe.component-previewer.json fixture file.
  preview: {
    enabled: true,                    // the enable flag (or use `preview: true`)
    route: '/__vibe',                 // route prefix for the gallery
    css: ['/index.css'],              // stylesheets the isolated stage includes (default: none)
    stageAttrs: ['stylecheat'],       // boolean attrs set on the stage <body> for attribute-gated CSS
    vibeUrl: '/nodemodules/@ape-egg/vibe/index.js',   // where kit pages load the runtime
    codieUrl: '/nodemodules/@ape-egg/codie/codie.js', // where kit pages load the editor
  },
})

By default the stage renders a component on the Vibe base only. Use preview.css (and preview.stageAttrs for frameworks like Stylecheat that key off <body> attributes) to give a component the styling it needs.

Requirements

• Vite >= 5.0 (hotUpdate on Vite 6+, handleHotUpdate on Vite 5)
• @ape-egg/vibe >= 4.3.0 — the HMR brain lives in @ape-egg/vibe/hot-module-refresh and drives the runtime through $.reconcile, $._refreshComponent and $._remountComponent; the plugin itself is only the Vite transport
• @ape-egg/codie — optional; powers the preview's editable source cell. The kit pages load it from preview.codieUrl (default /nodemodules/@ape-egg/codie/codie.js). If it isn't installed/served, the per-component page still renders (inspector + live stage) and just shows the source cell as disabled.
• acorn — bundled dependency; the preview uses it to statically read each component's declared-state literal and binding surface (no bespoke parser).

How it works

Vibe fetches components at runtime via <component src="">. Vite's default HTML pipeline would inject its HMR client and rewrite <script type="module"> inside every HTML file it serves — which breaks Vibe's component processing.

This plugin:

1. Serves component HTML raw through a middleware, bypassing Vite's HTML transform for files under your components directory.
2. Answers every .html change through Vite's HMR API. The injected /@vibe-hmr module is a self-accepting boundary; the hotUpdate hook sends a custom event first (vibe:component-update for files under components/, vibe:page-update for everything else, with scriptsChanged when a page <script> differs from the last served copy) and returns that module, so Vite emits an ordinary js-update and never a full reload.
3. The brain does the work in the runtime. @ape-egg/vibe/hot-module-refresh fetches the new source and hands it to the runtime: a component whose scripts are unchanged goes through $._refreshComponent (render with the live wrapper's own props, slot and component ids, then a template-aware $.reconcile that updates bindings and iteration/conditional templates alongside the DOM); a component whose script changed is re-mounted through the runtime's staged remount; a page edit reconciles the page body against the freshly fetched document.
4. Owns .js changes too. For a script module in Vite's client module graph the hook sends vibe:module-update (module url, the entry scripts at the roots of its importer chain, Vite's timestamp) and returns an empty module list, so Vite never reaches its no-boundary full reload. The client (client.js) ignores modules its page never loaded, otherwise imports the held instance and a timestamp-busted fresh one and re-seeds state: keys of window.$ and of component states whose raw value is a value the old module exported (matched by key through named exports, the default export and nested plain objects; identity for objects and functions, equality for primitives) take the fresh module's value at the same path. Nothing re-seeded means the module is boot-only code on that page, which reloads.

No server state beyond a per-page script hash, no WebSocket patching, no user configuration of which files are pages vs components — the plugin serves components/ raw and lets Vite watch everything.

Limitations

• A changed page-level <script> reloads the page — initial state comes from that script and there is no way to re-run it in place. Component scripts re-mount the component instead
• A JS module edit follows the module's exported values into state. State the boot script derives from them (vibe({ rows: build(demo) })) is not re-derived; if nothing on the page followed, the page reloads
• Preview: components that read global $ inside their <script> (e.g. $.characters[...]) render best-effort — the inspector surfaces declared state + the inputs referenced in the template, not arbitrary $ reads, so such a component may render its empty/else branch. Failures are isolated to that component's stage cell.

License

ISC