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 _="..." attributes
  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 detected Hand content htmx swaps in to the engine (htmx 4 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()]
});

Next Steps

Suggest a change to this page