@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

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

Quick Start

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

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

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

`html

Toggle
`

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:

`javascript
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.

$3

| 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 |

$3

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

$3

`javascript
// 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 });
`

$3

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

`html

Toggle


Alternar
`

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

$3

| 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 |

$3

`
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

`javascript
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

$3

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

$3

if, repeat, for, while, fetch

$3

first, last, next, previous, closest, parent

Virtual Module

The plugin creates a virtual module that you can import:

`javascript
// 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:

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

Use extraCommands to include those:

`javascript
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:

`javascript
// 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

$3

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

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

$3

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

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

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

API Reference

$3

| 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 |

$3

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

License

MIT