API Reference

onMount(callback: () => void): void

Registers a hook that runs once, client-side, after mount. The right place for browser APIs, timers, observers, fetches, and anything that reads window, document, or the URL.

Returnsvoid

<script>
  let status = "connecting";

  onMount(() => {
    status = "ready";   // reactive: flows through the scheduler
  });
</script>

<main><p>{status}</p></main>

onDestroy(callback: () => void): void

Registers a teardown hook. Remove global listeners, clear timers, disconnect observers, and abort in-flight requests here. Do not change state — the component is going away.

Returnsvoid

<script>
  let width = 0;

  function measure() {
    width = window.innerWidth;
  }

  onMount(() => {
    measure();
    window.addEventListener("resize", measure);
  });

  onDestroy(() => {
    window.removeEventListener("resize", measure);   // yours to remove
  });
</script>

<p>{width}px</p>

let name = persist(key: string, defaultValue: any);

Marks a top-level let as persisted: read from localStorage at mount, written on every statement mutation, and synchronized across components and tabs via BroadcastChannel (storage events as fallback). Server renders use the default.

ReturnsThe stored value, or defaultValue — as an ordinary reactive variable.

<script>
  let theme = persist("theme", "light");

  function toggle() {
    theme = theme === "light" ? "dark" : "light";   // writes + broadcasts
  }
</script>

<button on:click={toggle}>Theme: {theme}</button>

export let name = defaultValue;

Declares a reactive, read-only prop. Parents pass it as an attribute; updates arrive through setProps() without remounting. Assigning a prop in the child is a compile error (WIZZ-G015).

Returns—

<script>
  export let label = "Untitled";
  export let count;               // undefined unless passed
</script>

<p>{label}: {count}</p>

<!-- parent -->
<Badge label="Inbox" count={unread} />

<element on:event={handler}>

Attaches a native listener with addEventListener. Client-only; removed automatically on destroy. Not allowed on component tags (WIZZ-G011) or inside {#each} bodies (WIZZ-G006) — delegate from the container instead.

Returns—

<input on:input={handleInput} />
<button on:click={(event) => add(event.detail)}>Add</button>
<ul on:click={handleListClick}>{#each rows as row (row.id)}<li data-id={row.id}>{row.label}</li>{/each}</ul>

{#if condition} … {:else} … {/if}

Chooses a branch at mount time. Changing the condition later does not swap an already-rendered branch, so drive interactive show/hide with a bound class.

Returns—

{#if status === "ready"}
  <p>Ready.</p>
{:else}
  <p>Loading…</p>
{/if}

{#each items as item (key)} <row /> {/each}

Renders one native root element per item, inside a native parent. Bodies may not contain components, on: directives, or nested blocks.

Returns—

<ul class="users">{#each users as user (user.id)}<li class={user.rowClass}>{user.name}</li>{/each}</ul>

<wizz:head> <title/> <meta/> <link/> </wizz:head>

Per-component document metadata. Server-rendered into the head and adopted on hydration; client mounts prepend tagged nodes and destroy() releases them. Multiple titles resolve last-in-tree-wins.

Returns—

<wizz:head>
  <title>{post.title} — Blog</title>
  <meta name="description" content={post.summary}>
  <link rel="canonical" href={post.url}>
</wizz:head>

<wizz:style> /* raw CSS */ </wizz:style>

Component-scoped CSS. Delivered once per document in dev, adopted on hydration, refcounted on client mounts, and extracted to dist/app.css by wizz build. Expressions are never interpolated into CSS.

Returns—

<wizz:style>
  .card { padding: 1rem; }
  .card:hover h2 { color: var(--accent); }
  @keyframes pulse { 50% { opacity: 0.6; } }
</wizz:style>

export default function mountComponent(target: Node, props?: object): { setProps?(next: object): void; destroy(): void }

Creates the component's DOM, appends its root to target, runs the initial update and mount hooks, and returns a handle. setProps exists only when the component declares props.

Returns{ setProps?, destroy } — call destroy() exactly once.

import mountComponent from "/components/Counter.js";

const handle = mountComponent(document.getElementById("slot"), { label: "Clicks" });
handle.setProps?.({ label: "Taps" });
handle.destroy();   // exactly once

hydrateComponent(target: Element, props: object, state: object): Handle

Adopts server-rendered markup in place: verifies tags, data-wizz-id attributes, and text against the template, then attaches listeners. On any mismatch it warns once, clears target, and mounts fresh.

ReturnsThe same handle shape as mountComponent().

import { hydrateComponent } from "/pages/Home.hydrate.js";

const script = document.querySelector('script[type="application/wizz-state"]');
const state = JSON.parse(script.textContent);
script.remove();

const handle = hydrateComponent(document.getElementById("app"), {}, state);

hydrateRoot(rootNode: Element, props: object, state: object): Handle

Adopts the given node itself as the component root. Parents use it for nested hydration; a structural mismatch remounts inside the child's root without detaching the parent.

ReturnsThe component handle.

// Used by parents during nested hydration; available on every hydratable module.
import { hydrateRoot } from "/components/Card.hydrate.js";

const handle = hydrateRoot(cardElement, { title: "Intro" }, cardState);

renderComponent(props?: object, options?: object): { html: string; head?: string; state: object }

Renders escaped HTML without a DOM. Event handlers and hooks are skipped; author scripts run, so browser globals at the top level throw.

Returns{ html, head?, state }

import { renderComponent } from "./dist/pages/Home.server.js";

const { html, head, state } = renderComponent({});
// html:  escaped markup, no DOM involved
// head:  serialized head markup (only when <wizz:head> is declared)
// state: reactive state snapshot, children under state.__wizz.components

serializeInitialState(state: object): string

Serializes state into an inline application/wizz-state script with every '<' escaped. Deliver it as a sibling of the mount point, never inside it.

ReturnsAn HTML string.

import { renderComponent, serializeInitialState } from "./dist/pages/Home.server.js";

const { html, state } = renderComponent({});
const body = '<div id="app">' + html + "</div>" + serializeInitialState(state);
// '<script type="application/wizz-state">{"count":0}</script>' — every "<" escaped

compile(source: string, options?: { filePath?, hydratable?, diagnostics? }): { source, payload, sourceMap, version, diagnostics? }

Compiles a component to a mountable ES module. Errors are SyntaxErrors carrying a stable code, line, column, and (with filePath) a caret code frame.

Returnssource (module text), payload (analyzed AST), sourceMap (v3 or null), version (frozen triple).

const { compile } = require("./src/compiler");

const { source, payload, sourceMap, version } = compile(componentSource, {
  filePath: "src/pages/Home.wizz"
});

try {
  compile("<main></section>");
} catch (error) {
  error.code;      // "WIZZ-P018" — mismatched closing tag
  error.line;      // structured location
}

const result = compile("<main><p>hi", { filePath: "src/App.wizz", diagnostics: "collect" });
result.diagnostics[0].code;   // "WIZZ-P022"

compileServer(source: string, options?: object): { source, payload, sourceMap: null, version }

Shares the parse → analyze → assign pipeline and emits a DOM-free server module. Component tags render through each child's own server module, gated by the eligibility options.

ReturnsThe same shape as compile(), with sourceMap always null.

const { compileServer } = require("./src/compiler");

const { source, sourceMap } = compileServer(componentSource, {
  filePath: "src/components/Counter.wizz"
});
// source exports renderComponent() and serializeInitialState(); sourceMap is always null

VERSIONS: Readonly<{ compiler: string; syntax: string; output: string }>

The frozen compatibility triple, also stamped on the first line of every generated module and printed by wizz --version.

Returns—

const { VERSIONS } = require("./src/compiler");

VERSIONS;
// { compiler: "1.17.0", syntax: "1.4.1", output: "1.8.2" }  (frozen)

createRouter({ routes, hydratableRoutes?, target, window, document }): { render(), navigate(pathname), destroy() }

The client router used by runtime/main.js. Exact pathname matching, first-render hydration, lazy imports, race-safe renders, and a popstate listener.

Returns{ render(): Promise, navigate(pathname): Promise, destroy(): void }

import { createRouter } from "/runtime/router.js";

const router = createRouter({ routes, hydratableRoutes, target, window, document });
await router.render();             // match location.pathname, hydrate or mount
await router.navigate("/docs");    // pushState + render
router.destroy();                  // remove popstate listener + current page

export default async function handler(request: Readonly<Request>): unknown

Server-side route handler. Plain value → 200 JSON, string → text, undefined → 204, { status, headers, body } → full control, throw → fixed 500.

ReturnsSee the return-value table in Server APIs & SSR.

// src/server/api/health.js → /api/health
export default async function handler(request) {
  return { ok: true, method: request.method };   // 200 JSON
}