Skip to content
Draft

vite-plugin-xu

A build-time Vite plugin that compiles a .xu single-file component into a real ES module.

@xuda/vite-plugin-xu compiles .xu single-file components to ES modules at build time, and hot-reloads them in dev at the level of a full component reload.

A workspace package today, not an npm install

@xuda/vite-plugin-xu and the @xuda/compiler package it depends on both carry "private": true in their package.json. Unlike xuda-cli, create-xuda-cli and @xuda/core, neither is published to npm yet. The one working consumer in this repository, examples/hello, reaches it as a file: dependency: "@xuda/vite-plugin-xu": "file:../../packages/vite-plugin-xu".

Setup

js
// vite.config.js
import { defineConfig } from 'vite';
import xu from '@xuda/vite-plugin-xu';

export default defineConfig({ plugins: [xu()] });
js
// src/main.js
import { createApp } from '@xuda/core';
import App from './App.xu';

createApp(App).mount('#app');

examples/hello is a full working project built this way: a counter, a conditional mount and a keyed list, driven entirely by plain functions and plain mutation over a reactive() store, with no signals, .value or datasource layer visible in the component itself.

What the plugin is, mechanically

One transform hook. Vite's default load already read the file, so the hook receives the .xu source as text, calls @xuda/compiler, and returns the emitted module. There is no custom resolver and no virtual module: .xu stays a real file with a real path, which keeps stack traces and the HMR graph honest.

enforce: 'pre' matters: without it, vite:esbuild can reach the file first and fail on <template>, which reads as the file being broken rather than the pipeline order being wrong. Vite also appends ?import to non-JS imports (and ?t=… on an HMR re-request), so the plugin strips that before its include test, or the file silently isn't compiled and the browser reports a syntax error in a file the author never wrote.

HMR

The level implemented is full component reload: on edit, the module re-executes, every mounted instance of that component unmounts and remounts from the new module, and component state resets. A reactive({ count: 0 }) in <script> goes back to 0. State preservation is deliberately not attempted, because after an edit to <script> there is no reliable way to know which half of the old reactive object still means the same thing.

In serve mode the plugin appends an import.meta.hot.accept footer. __XUDA_HMR__ is installed by createApp in @xuda/core the first time an app mounts, so the plugin never injects an import into user code. If no mounted app claims the updated component (nobody was showing it, or the page hasn't booted), the update falls back to a full page reload rather than silently doing nothing. A production build gets no HMR footer at all.

Options

See The .xu language for the block-based dialect xuda-cli compiles, and the callout there for how this compiler's dialect differs from it.