Vite plugin for automatic tree-shaken hyperscript bundles
npm install @lokascript/vite-pluginZero-config Vite plugin that automatically generates minimal LokaScript bundles based on detected hyperscript usage.
- 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
``bash`
npm install @lokascript/vite-plugin @lokascript/core
`javascript
// vite.config.js
import { lokascript } from '@lokascript/vite-plugin';
export default {
plugins: [lokascript()],
};
`
`javascript`
// main.js
import 'lokascript'; // Auto-generated minimal bundle
`html`
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
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 blocksexecute()
- Dynamic hyperscript generation at runtime via
- 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.
Enable semantic parsing for natural language hyperscript and multilingual support across 13 languages.
| 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 |
- Western: en, es, pt, fr, de
- East Asian: ja, zh, ko
- Other: ar, tr, id, sw, qu
`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 });
`
When semantic: 'auto' is set, the plugin scans your hyperscript for non-English keywords:
`html
`
The plugin automatically selects the smallest bundle that covers all detected languages.
| 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 |
``
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
`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
});
`
toggle, add, remove, removeClass, show, hide, set, get, put, append, take,
increment, decrement, log, send, trigger, wait, transition, go, call, focus, blur, return
if, repeat, for, while, fetch
first, last, next, previous, closest, parent
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
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
| 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 |
For dynamically generated hyperscript that can't be detected:
`javascripton click ${dynamicCommand} .active
// This can't be detected by static analysis
element.setAttribute('_', );`
Use extraCommands to include those:
`javascript`
lokascript({
extraCommands: ['toggle', 'add', 'remove'],
});
- .html, .htm.vue
- (single file components).svelte
- .jsx
- , .tsx.astro
- .php
- , .erb, .ejs, .hbs
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'
),
},
},
};
`
See the vite-plugin-test example for a basic demo:
`bash`
cd examples/vite-plugin-test
npm install
npm run dev
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.
| 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 |
`regex``
/\.(html?|vue|svelte|jsx?|tsx?|astro|php|erb|ejs|hbs|handlebars)$/
MIT