@ape-egg/vite-plugin-vibe
v0.0.2
Published
Vite plugin for Vibe — component HMR and raw HTML serving
Downloads
111
Maintainers
Readme
@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 devHMR 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-vibeUsage
// 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/morphs the rendered component in place - Page HMR — saving an HTML page updates the
<slot>content; the rest of the page stays mounted - Normal reload fallback — pages without Vibe (
<slot>not present) reload normally
Options
vibe({
components: 'components', // directory to serve raw + watch for HMR (default: 'components')
})Requirements
- Vite
>= 5.0 @ape-egg/vibe>= 1.9.1— the plugin relies on Vibe preserving<slot>in the processed DOM and on internal hooks (_vibeRawSource,_vibeIterPropIds) used for surgical HMR
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:
- Serves component HTML raw through a middleware, bypassing Vite's HTML transform for files under your components directory.
- Watches component files and sends custom
vibe:component-updateevents on change. The client injects a small runtime that replaces the rendered component's DOM in place — fetching the new template, executing any scripts if changed, and preserving the original slot content captured before initial hydration. - Intercepts Vite's full-reload for HTML pages via
handleHotUpdate. If Vibe is on the page (detected by presence of<slot>), the client fetches the new page HTML, extracts the content inside<component src>, and swaps the<slot>element's content. Vibe's MutationObserver re-hydrates bindings/conditionals/iterations naturally.
No server-state, no WebSocket churn, no user configuration of which files are pages vs components — the plugin watches components/ and lets Vite handle everything else.
Limitations
- Components with slot content containing
<script type="module">that has changed require a full page reload (scripts can't be cleanly re-executed in place) - If a page file changes HTML outside the
<component src="...">wrapper (e.g., new<body>children), the plugin falls back tolocation.reload()automatically
License
ISC
