@lokascript/vite-plugin

Zero-config Vite plugin that automatically generates minimal LokaScript bundles based on detected hyperscript usage.

Features

• Zero-config: Just add the plugin and it works
• Automatic detection: Scans HTML, Vue, Svelte, JSX/TSX for _="..." attributes
• Minimal bundles: Only includes commands and blocks you actually use
• HMR support: Re-generates bundle when you add new hyperscript
• Framework agnostic: Works with any Vite-based project

Installation

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

Quick Start

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

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

// main.js
import 'lokascript'; // Auto-generated minimal bundle

<!-- Just write hyperscript - plugin detects what you use -->
<button _="on click toggle .active">Toggle</button>

How It Works

1. Scans your HTML/Vue/Svelte/JSX files for _="..." attributes
2. Detects which commands, blocks, and expressions you use
3. Generates a minimal bundle with only the features you need
4. Regenerates on HMR when you add new hyperscript

Compile Mode (Minimal Bundle Size)

When bundle size is the priority, use compile mode to pre-compile hyperscript to JavaScript at build time:

lokascript({
  mode: 'compile', // ~500 bytes gzip vs ~8KB for interpret mode
});

Trade-offs:

| Feature | Interpret (default) | Compile | | ------------------- | ------------------- | --------------- | | Bundle size | ~8 KB gzip | ~500 bytes gzip | | Dynamic execute() | ✓ | ✗ | | Block commands | ✓ | ✗ | | Build complexity | Lower | Higher |

When to use compile mode:

• Landing pages with simple interactions (toggles, shows, hides)
• Performance-critical apps where every KB matters
• Static sites where hyperscript is just for UI polish

When NOT to use compile mode:

• Apps using if, repeat, fetch, or for each blocks
• Dynamic hyperscript generation at runtime via execute()
• Apps that need the full hyperscript power

Supported commands in compile mode: toggle, add, remove, show, hide, focus, blur, set, get, put, increment, decrement, log, send, trigger, wait

Positional expressions: next, previous, parent, first, last, closest

Animations: Use CSS transitions - toggling classes triggers them automatically. No special transition command needed.

Multilingual & Semantic Parsing

Enable semantic parsing for natural language hyperscript and multilingual support across 13 languages.

Multilingual Options

| Option | Type | Default | Description | | ---------------- | -------------------------------------------------- | ------- | --------------------------------------- | | semantic | boolean \| 'en' \| 'auto' | false | Enable semantic parser | | languages | string[] | [] | Explicit language codes to support | | region | 'western' \| 'east-asian' \| 'priority' \| 'all' | auto | Force a regional bundle | | grammar | boolean | false | Enable grammar transformation (SOV/VSO) | | extraLanguages | string[] | [] | Languages to always include |

Supported Languages (13)

• Western: en, es, pt, fr, de
• East Asian: ja, zh, ko
• Other: ar, tr, id, sw, qu

Usage Examples

// Auto-detect languages from source files
lokascript({ semantic: 'auto' });

// English synonyms only (smallest semantic bundle)
lokascript({ semantic: 'en' });

// Explicit languages (selects optimal regional bundle)
lokascript({ languages: ['en', 'es', 'ja'] });

// Force a specific regional bundle
lokascript({ region: 'western' });

// Full multilingual with grammar transformation
lokascript({ semantic: true, grammar: true });

Language Auto-Detection

When semantic: 'auto' is set, the plugin scans your hyperscript for non-English keywords:

<!-- Detected as Japanese -->
<button _="on click トグル .active">Toggle</button>

<!-- Detected as Spanish -->
<button _="on click alternar .active">Alternar</button>

The plugin automatically selects the smallest bundle that covers all detected languages.

Semantic Bundle Sizes

| Bundle | Gzip Size | Languages | | ---------------------- | --------- | --------------------- | | semantic: 'en' | ~20 KB | English only | | semantic: 'es' | ~16 KB | Spanish only | | region: 'es-en' | ~25 KB | English + Spanish | | region: 'western' | ~30 KB | en, es, pt, fr, de | | region: 'east-asian' | ~24 KB | ja, zh, ko | | region: 'priority' | ~48 KB | 11 priority languages | | region: 'all' | ~61 KB | All 13 languages |

Tiered Bundle Architecture

Level 0: Base HybridParser (default)     4-9 KB gzip
         ↓ semantic: true
Level 1: + Semantic English              +20 KB
         ↓ languages detected/specified
Level 2: + Regional Semantic Bundle      +16-61 KB
         ↓ grammar: true
Level 3: + Grammar Transformation        +68 KB

Options

lokascript({
  // Bundle mode: 'interpret' (default) or 'compile'
  mode: 'interpret',

  // Extra commands to always include (for dynamic hyperscript)
  extraCommands: ['fetch', 'put'],
  extraBlocks: ['for'],

  // Always include positional expressions
  positional: true,

  // Enable htmx attribute compatibility
  htmx: true,

  // Debug logging
  debug: true,

  // File patterns
  include: /\.(html|vue|svelte|jsx|tsx)$/,
  exclude: /node_modules/,

  // Custom bundle name (shown in generated code comments)
  bundleName: 'MyApp',

  // Global variable name (default: 'lokascript')
  globalName: 'lokascript',

  // Multilingual options (see "Multilingual & Semantic Parsing" section)
  semantic: false, // boolean | 'en' | 'auto'
  languages: [], // ['en', 'es', 'ja']
  region: undefined, // 'western' | 'east-asian' | 'priority' | 'all'
  grammar: false, // Enable grammar transformation
  extraLanguages: [], // Languages to always include
});

Detected Features

Commands (21)

toggle, add, remove, removeClass, show, hide, set, get, put, append, take, increment, decrement, log, send, trigger, wait, transition, go, call, focus, blur, return

Blocks (5)

if, repeat, for, while, fetch

Positional Expressions (6)

first, last, next, previous, closest, parent

Virtual Module

The plugin creates a virtual module that you can import:

// All of these work:
import 'lokascript';
import 'virtual:lokascript';
import '@lokascript/core'; // Redirects to virtual module

HMR Support

When you add new hyperscript to your HTML files, the plugin:

1. Re-scans the changed file
2. Updates the aggregated usage
3. Triggers a page reload if new commands are detected

Bundle Size Comparison

| Usage | Generated Size (gzip) | vs Full Bundle | | ------------------- | --------------------- | -------------- | | 3 commands | ~5 KB | 90% smaller | | 6 commands | ~6.5 KB | 85% smaller | | 9 commands + blocks | ~8 KB | 80% smaller | | All features | ~40 KB | same |

Edge Cases

For dynamically generated hyperscript that can't be detected:

// This can't be detected by static analysis
element.setAttribute('_', `on click ${dynamicCommand} .active`);

Use extraCommands to include those:

lokascript({
  extraCommands: ['toggle', 'add', 'remove'],
});

Supported File Types

• .html, .htm
• .vue (single file components)
• .svelte
• .jsx, .tsx
• .astro
• .php, .erb, .ejs, .hbs

Monorepo Development

When developing in the lokascript monorepo:

// vite.config.js
import { lokascript } from '../../packages/vite-plugin/src/index.ts';
import path from 'path';

export default {
  plugins: [lokascript({ debug: true })],
  resolve: {
    alias: {
      '@lokascript/core/parser/hybrid': path.resolve(
        __dirname,
        '../../packages/core/src/parser/hybrid'
      ),
    },
  },
};

Examples

Basic Example

See the vite-plugin-test example for a basic demo:

cd examples/vite-plugin-test
npm install
npm run dev

Multilingual Example

See the vite-plugin-multilingual example for multilingual features:

cd examples/vite-plugin-multilingual
npm install
npm run dev

This example demonstrates language auto-detection with Japanese, Spanish, and Korean keywords.

API Reference

Plugin Options

| Option | Type | Default | Description | | ---------------- | --------------------------- | --------------------- | ------------------------------------- | | debug | boolean | false | Enable debug logging | | include | RegExp \| string[] | See below | File patterns to scan | | exclude | RegExp \| string[] | /node_modules/ | File patterns to exclude | | extraCommands | string[] | [] | Commands to always include | | extraBlocks | string[] | [] | Blocks to always include | | positional | boolean | false | Always include positional expressions | | htmx | boolean | false | Enable htmx integration | | bundleName | string | 'ViteAutoGenerated' | Bundle name in comments | | globalName | string | 'lokascript' | Window global name | | semantic | boolean \| 'en' \| 'auto' | false | Enable semantic parser | | languages | string[] | [] | Explicit language codes | | region | string | auto | Force regional bundle | | grammar | boolean | false | Enable grammar transformation | | extraLanguages | string[] | [] | Languages to always include |

Default Include Pattern

/\.(html?|vue|svelte|jsx?|tsx?|astro|php|erb|ejs|hbs|handlebars)$/

License

MIT