Vite Plugin

The hyperfixi Vite plugin scans your source files, detects which hyperscript commands you use, and generates a minimal bundle automatically. No manual bundle selection needed.

Setup

npm install @hyperfixi/core @hyperfixi/vite-plugin

// vite.config.js
import { hyperfixi } from '@hyperfixi/vite-plugin';

export default {
  plugins: [hyperfixi()]
};

// main.js
import 'hyperfixi';

That's it. The plugin handles the rest.

How It Works

  1. Scan — The plugin scans your HTML, JSX, Vue, and Svelte files for the attributes the engine reads (_, script, data-script) and <script type="text/hyperscript"> blocks
  2. Detect — It identifies which hyperscript commands are used (e.g., toggle, fetch, if)
  3. Bundle — It generates a bundle on @hyperfixi/engine that registers only those commands' grammar modules
  4. Serve — In dev mode, it hot-reloads when your hyperscript usage changes

Configuration

// vite.config.js
import { hyperfixi } from '@hyperfixi/vite-plugin';

export default {
  plugins: [
    hyperfixi({
      // Glob patterns to scan (default: all HTML-like files in src/)
      include: ['src/**/*.html', 'src/**/*.vue'],

      // Patterns to exclude
      exclude: ['node_modules/**'],

      // Force specific commands to always be included
      extraCommands: ['toggle', 'fetch'],

      // Force specific blocks (if, repeat, …) to always be included
      extraBlocks: ['if'],

      // Enable verbose logging during build
      debug: false,
    })
  ]
};

Options

Option Type Default Description
include string[] ['**/*.html', '**/*.vue', '**/*.jsx', '**/*.svelte'] File patterns to scan for hyperscript usage
exclude string[] ['node_modules/**'] File patterns to ignore
extraCommands string[] [] Commands to always include regardless of detection
extraBlocks string[] [] Blocks (if, repeat, …) to always include
positional boolean false Always include positional expressions (first, last, next, closest, …)
htmx boolean — Deprecated, no effect: every bundle runs the hyperscript in content htmx and fixi swap in (htmx itself is not bundled)
devFallback 'everything' | 'auto' 'auto' 'everything' serves the whole engine in dev for faster rebuilds; 'auto' builds the module list in dev too
debug boolean false Log detected commands and bundle contents

Custom Bundles

For cases where the automatic scanner doesn't detect all commands (e.g., dynamically generated hyperscript), force-include them:

hyperfixi({
  extraCommands: ['transition', 'settle']
})

Without the plugin, you can assemble an engine by hand: each command group is a
grammar module exported from @hyperfixi/core, and a bundle is the list you pass
to register().

import { register, boot, on, toggle, fetchCommand } from '@hyperfixi/core';

register(on, toggle, fetchCommand);
boot();

The plugin does exactly this for you, with the list derived from your source.
For every command at once, use the prebuilt bundle.

Framework Integration

Vue

// vite.config.js
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { hyperfixi } from '@hyperfixi/vite-plugin';

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

Svelte

// vite.config.js
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { hyperfixi } from '@hyperfixi/vite-plugin';

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

React (JSX)

Write the script in data-script: the engine reads it as it reads _, the plugin scans it, and JSX accepts any data-* attribute.

<button data-script="on click toggle .active">Toggle</button>

TypeScript

Reference the plugin's client types once, beside Vite's, in src/vite-env.d.ts:

/// <reference types="vite/client" />
/// <reference types="@hyperfixi/vite-plugin/client" />

They declare import 'hyperfixi' and the globals the bundle installs, window.hyperfixi and window._hyperscript. Without them, TypeScript 6 rejects the side-effect import (TS2882).

CommonJS projects

A project whose package.json says "type": "commonjs" (what npm init -y writes) can load the plugin with require from 7.5.0, on the Node versions Vite 8 supports (20.19+, 22.12+).

Next Steps

Suggest a change to this page