API Reference

@hyperfixi/core's root is @hyperfixi/engine, re-exported (ESM only); the tooling lives on subpaths. The hyperscript language itself is upstream _hyperscript's — see the language reference.

Core API

import { register, everything, boot } from '@hyperfixi/core';

// Add the grammar: every module, or only what a page uses
register(...everything);

// Install as window._hyperscript and process every _="..." attribute
// when the document is ready
boot();

A bundle on the engine is the list of grammar modules passed to register(). A command or feature that is not registered does not exist: a script that uses it fails to parse.

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

register(on, add, remove, toggle);
boot();

The script-tag bundle (hyperfixi.js, 33.3 KB gzipped) is register(...everything) plus boot(), prebuilt.

Functions

evaluate(src, overrides?)

import { evaluate } from '@hyperfixi/core';

evaluate('add .clicked to me', { me: button });
evaluate('log "Hello World"');
const sum = evaluate('1 + 2'); // an expression returns its value

parse(src)

import { parse, ParseError } from '@hyperfixi/core';

try {
  parse('toggle .active on');
} catch (e) {
  if (e instanceof ParseError) console.error(e.message); // names where parsing stopped
}

window._hyperscript

In the browser, window._hyperscript and window.hyperfixi are the same object, shaped like upstream's:

_hyperscript.evaluate('put "hi" into #out');
_hyperscript.parse('on click toggle .active on').errors[0]?.message; // no throw
_hyperscript.processNode(document.querySelector('#new-content'));
_hyperscript.config; // runtime configuration
_hyperscript.use(plugin);

A script that fails to parse fires a hyperscript:parse-error event and logs an error naming the token where parsing stopped. document receives hyperscript:ready once the page has been processed.

The engine does not watch the DOM: after inserting HTML that carries _="..." attributes, call processNode on it.

Writing a Command

A grammar module is a function that adds rules to the grammar. It can live in your own package: import expr and the types from @hyperfixi/core.

import { register, everything, expr } from '@hyperfixi/core';

function shout(g) {
  g.commands.shout = (p, _keyword, start) => {
    const value = expr(p);
    return {
      type: 'shoutCommand',
      start,
      end: p.endPos(),
      run: ctx => alert(String(value.ev(ctx)).toUpperCase()),
    };
  };
}

register(...everything, shout);

Subpaths

Coming from 3.x

4.0 retired core's own engine and its API: hyperscript.compileSync / compileAsync / eval / validate, createContext, createRuntime, debugControl, and the /commands, /expressions, /parser/*, /registry and /behaviors subpaths. In their place:

The migration guide maps every removed export.

Hyperscript Language Reference

hyperfixi implements upstream _hyperscript's grammar. For the language, see the upstream docs:

• Commands — toggle, add, remove, fetch, if, repeat, and more
• Expressions — Selectors, positional, properties, type conversion
• Reference — Complete language reference

Quick Example

<button
  _="on click
  add .loading to me
  fetch /api/data as JSON
  put result.message into #output
  remove .loading from me"
>
  Load Data
</button>

Multilingual API

For hyperscript in other languages, and translation between them, see the LokaScript docs.

Next Steps

• Bundle Selection — The bundle and the Vite plugin
• Cookbook — Practical examples