# Ilha

> Ilha is a lightweight UI framework under 2,500 lines of code. Simple enough to fit in a single AI context window, powerful enough to build modern interfaces your way.

# Ilha for Svelte Developers
Source: https://ilha.build/blog/ilha-for-svelte-developers

If you know Svelte, Ilha’s fine-grained reactivity should feel familiar. You write function components. You declare `atom()` values. Reads subscribe. Writes rerun the component and morph the DOM.

This is not an argument that Ilha is better than Svelte. It is a map from familiar Svelte ideas to Ilha.

## What is Ilha?

Ilha is a small isomorphic UI library. A component renders HTML on the server and activates in the browser. You do not turn the whole page into a client app by default.

```tsx twoslash
import { atom } from "ilha";

export const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};
```

## `$state` vs `atom()`

Svelte reads and writes a variable. Ilha reads with `count()` and writes with `.set()` / `.update()`. In JSX, `{count}` subscribes.

```tsx twoslash
import { atom } from "ilha";

export const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};
```

## `$derived` vs `Atom.map`

```tsx twoslash
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom } from "ilha";

export const Totals = () => {
  const count = atom(0);
  const doubled = atom(Atom.map(count.atom, (n) => n * 2));
  return <p>{doubled}</p>;
};
```

Async and streamed data use `when` / Stream views, not a derived accessor with `.loading`.

## `$effect` vs `watch()`

```tsx twoslash
import { atom, watch } from "ilha";

const Title = () => {
  const title = atom("Hello");
  watch(title, (value) => {
    document.title = value;
  });
  return <p>{title}</p>;
};
```

For stream-driven ongoing logic, use `when` with `Atom.toStream` — see [Streams](/guide/ui/streams). For write-site DOM effects, handlers are fine.

## Props

Props are ordinary function arguments. There is no `$props()` rune.

## Boundaries

A nested function shares the parent component. `mount` / `renderToString` on a function makes it a root.

## SSR

`await renderToString(Counter)` for HTML. `mount(host, Counter, { hydrate: true })` to attach events.

| Svelte              | Ilha                                                 |
| ------------------- | ---------------------------------------------------- |
| `$state`            | `atom(value)`                                        |
| `$derived`          | `atom(Atom.map(...))` or `atom(Atom.transform(...))` |
| `$effect`           | `watch()` or event handlers                          |
| `bind:value`        | `oninput` + `atom`                                   |
| `.svelte` component | function component                                   |

---

# Astro
Source: https://ilha.build/guide/astro

`@ilha/astro` is an [Astro](https://astro.build) integration for Ilha. You register it once, then import any component into an `.astro` page and hydrate it with a [client directive](https://docs.astro.build/en/reference/directives-reference/#client-directives).

It is a separate package from `ilha`. Add it when you build with Astro.

## Install

```package-install
@ilha/astro
```

`astro` and `ilha` are peer dependencies.

## Quick start

```ts twoslash
// astro.config.mjs
import { defineConfig } from "astro/config";
import ilha from "@ilha/astro";

export default defineConfig({
  integrations: [ilha()],
});
```

Set `jsxImportSource` to `ilha` — see [Render and hydrate](/guide/ui/render):

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "ilha"
  }
}
```

```tsx twoslash
// src/islands/counter.tsx
import { atom } from "ilha";

export const Counter = ({ start = 0 }: { start?: number }) => {
  const count = atom(start);
  return (
    <button type="button" onclick={() => count.update((value) => value + 1)}>
      {count}
    </button>
  );
};
```

```astro
---
import { Counter } from "../islands/counter";
---

<Counter client:load start={10} />
```

## How it works

| Phase | What happens |
| --- | --- |
| Server | The renderer calls `renderToString()`, which wraps output in a `[data-ilha]` host with a state snapshot. |
| Client | The client entry finds that host inside Astro's `<astro-island>` and calls `mount(..., { hydrate: true })`. |

```
server                              client
──────────────────────────────────  ────────────────────────────────────
.renderToStaticMarkup(component)        @ilha/astro/client
  → renderToString(component)             → find [data-ilha] inside <astro-island>
  → data-ilha-state snapshot          → mount(host, component, { hydrate: true })
                                      → astro:unmount → unmount()
```

## Client directives

| Directive        | Behavior                                     |
| ---------------- | -------------------------------------------- |
| `client:load`    | Hydrate as soon as the page loads.           |
| `client:idle`    | Hydrate when the browser is idle.            |
| `client:visible` | Hydrate when the island enters the viewport. |
| `client:media`   | Hydrate when a media query matches.          |
| `client:only`    | Skip SSR. Mount fresh in the browser.        |

```astro
---
import { Counter } from "../islands/counter";
---

<Counter client:only="@ilha/astro" start={0} />
```

When you mix JSX frameworks, pass `include` globs:

```ts
ilha({ include: ["**/ilha/**"] });
```

## Import paths

| Import path          | Use it for                                      |
| -------------------- | ----------------------------------------------- |
| `@ilha/astro`        | Integration (default export / `getRenderer()`). |
| `@ilha/astro/client` | Client hydration entry (registered by Astro).   |
| `@ilha/astro/server` | Server renderer entry (registered by Astro).    |

## Notes

- Ilha components do not support Astro `<slot />` forwarding. Pass data through props.
- `client:only` mounts with `mount(element, component)` against an empty host.
- Peer ranges: `astro` `^7.2.9`, `ilha` `^0.14.0`.

## Related

| Topic                  | Guide                                  |
| ---------------------- | -------------------------------------- |
| Core `ilha` API        | [ilha](/reference/ilha)                |
| SSR and hydrate        | [Render and hydrate](/guide/ui/render) |
| Multi-page SPA routing | [Router](/guide/routing/overview)      |

---

# Core concepts
Source: https://ilha.build/guide/getting-started/core-concepts

ilha is built around a small set of ideas: components, atoms, JSX, and isomorphic render. Once these click, the rest of the library feels straightforward.

## Component

A component is a function that returns a view. It can be sync, async, or a generator.

The same component can render to HTML and mount in the browser. It owns the atoms you declare while it runs.

A nested plain function belongs to the parent component. Its `atom()` calls share that parent.

## Choose the smallest form

| Form                     | Ownership                               |
| ------------------------ | --------------------------------------- |
| `const View = () => JSX` | Parent component owns atoms and cleanup |
| `mount(el, View)`        | `View` is the root fiber                |
| `function*` / `async`    | Same root, with `yield*` / `await`      |

```tsx twoslash
import { atom } from "ilha";

const Badge = (props: Record<string, unknown>) => (
  <span>{String(props.label)}</span>
);

const Label = (props: Record<string, unknown>) => {
  const text = atom(String(props.label));
  return <Badge label={text()} />;
};
```

Read an atom with `text()` when you need the current value in JS. In JSX, `{text}` subscribes the render.

## Isomorphic components

Use the same function two ways:

- `await renderToString(component)` for HTML.
- `mount(element, component)` for the browser.

You do not split a component into server and client copies.

## Atoms

An atom is a value you can read and update. When it changes, the component that read it reruns.

```tsx twoslash
import { atom } from "ilha";

const Counter = () => {
  const count = atom(0);
  count(); // read
  count.set(5); // write
  count.update((n) => n + 1);
  return <p>{count}</p>;
};
```

Derived values use Effect's `Atom.map` or `Atom.transform`:

```tsx twoslash
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom } from "ilha";

const Cart = () => {
  const items = atom([{ n: 1 }, { n: 2 }]);
  const total = atom(
    Atom.map(items.atom, (list) => list.reduce((sum, item) => sum + item.n, 0))
  );
  return <p>{total}</p>;
};
```

Do not put JSX in an atom. Atoms hold data. Map arrays during render with `items().map(...)`, or paint a Stream for live server data. Use [`watch()`](/guide/ui/state#side-effects) for side effects on atom changes.

## JSX

Prefer JSX. Interpolated values escape. Event props are lowercase (`onclick`, `onchange`).

```tsx twoslash
import { atom } from "ilha";

const App = () => {
  const open = atom(false);
  return (
    <button type="button" onclick={() => open.set(true)}>
      Open
    </button>
  );
};
```

Use a plain function for DOM events. You do not need a special action wrapper on the client.

## SSR and hydration

`renderToString(component)` paints into a DOM, waits until idle, then returns HTML. By default it wraps the output in `<div data-ilha data-ilha-state="…">`.

`mount(host, component, { hydrate: true })` restores atom snapshots from that host and attaches events.

## Mental model

1. A component runs and returns a view.
2. Atoms it reads subscribe that run.
3. A write schedules a rerun and morphs the DOM.
4. Streams and generators paint into holes inside the host.

---

# Installation
Source: https://ilha.build/guide/getting-started/installation

Install ilha with your package manager. For a new project, start from a template so routing and mounting are already wired.

## Install

```package-install
npm i ilha effect
```

`effect` is a peer dependency. Ilha atoms and streams sit on Effect.

## Templates

| Template | Command | Sandbox |
| --- | --- | --- |
| [Vite SPA](https://github.com/ilhajs/ilha/tree/main/templates/vite-spa) | `npx giget@latest gh:ilhajs/ilha/templates/vite-spa` | [Open](https://stackblitz.com/github/ilhajs/ilha/tree/main/templates/vite-spa) |
| [Oxide SPA](https://github.com/ilhajs/ilha/tree/main/templates/oxide-spa) | `npx giget@latest gh:ilhajs/ilha/templates/oxide-spa` | [Open](https://stackblitz.com/github/ilhajs/ilha/tree/main/templates/oxide-spa) |

Vite SPA is a client app with file routes. Oxide SPA adds server pages, frames, and `action` from `oxidejs`.

## Requirements

- ESM modules.
- TypeScript for the best editor support.
- A browser for `mount()`.
- JSON-serializable atom snapshots when you hydrate.

## Import

```tsx twoslash
import { atom, mount, renderToString } from "ilha";
```

Named exports you will use most:

```tsx twoslash
import { atom, when, mount, renderToString, h, Fragment } from "ilha";
```

Custom elements come from `ilha/define`:

```tsx twoslash
import { define } from "ilha/define";
```

## Minimal example

```tsx twoslash
import { atom } from "ilha";

const Greeting = () => <p>Hello, ilha!</p>;

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      Count: {count}
    </button>
  );
};
```

## Server-side rendering

```tsx twoslash
import { atom, renderToString } from "ilha";

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      Count: {count}
    </button>
  );
};

const html = await renderToString(Counter);
```

`renderToString` waits until in-flight work is idle, then serializes. Pass `{ timeout: ms }` to cut off early.

## Client-side mounting

```tsx twoslash
import { mount } from "ilha";

const Counter = () => <p>Count</p>;

const root = document.getElementById("app");
if (root) {
  const unmount = mount(root, Counter);
}
```

The returned function stops listeners and in-flight work. Call it when you remove the host.

---

# Introduction
Source: https://ilha.build/guide/getting-started/introduction

import { example } from "./introduction.examples";

ilha is a tiny, isomorphic UI library for building reactive components.

You render on the server and mount in the browser with signal-based updates. There is no virtual DOM and no compiler. Markup stays close to HTML.

## What ilha is

A **component** is a function, async function, or generator that returns a view. The same component produces HTML through `renderToString()` and activates in the browser through `mount()`.

You write a function component. You declare `atom()` values inside it. Reads during render subscribe that component; writes rerun it and morph the host.

## Why it exists

Most UI stacks force you to choose between simplicity and interactivity. ilha keeps both close together: a small API, direct DOM updates, and one component for server and client.

This makes ilha a good fit when you want:

- Server-rendered markup.
- Small interactive regions.
- Explicit state.
- No virtual DOM.

## How it feels to use

A typical component reads like a small HTML-aware module:

<Preview code={example} />

The same function can render to a string on the server and mount into the DOM on the client.

## Choose the smallest component form

| Start with | Use it when |
| --- | --- |
| `const View = () => JSX` | Reusable markup inside a parent component |
| `const View = function*` | You need `yield Stream.map(...)` or `yield* when(...)` |
| `mount(el, View)` | The function is the root you hydrate or mount |

Start plain:

```tsx twoslash
const Status = () => <p>Ready</p>;
```

Add local state with `atom()`:

```tsx twoslash
import { atom } from "ilha";

const Status = () => {
  const message = atom("Ready");
  return <p>{message}</p>;
};
```

A nested function without its own `mount()` / `renderToString()` belongs to the parent component.

## Core ideas

### Isomorphic rendering

You produce HTML on the server and activate the same function in the browser.

### Fine-grained reactivity

Atoms keep updates local. Changing one value does not rerender an entire application tree.

### Function components

You write functions that return JSX. Generators `yield` streams and `yield*` Effects. Async functions can await before they return a view.

### JSX-first authoring

Prefer JSX. It escapes interpolations. Use `h()` when you cannot use JSX.

## When to use ilha

Use ilha when you want server HTML plus a few interactive regions, not a full client app by default.

## Basic mental model

1. Write a component that returns JSX.
2. Declare `atom()` values you read in the view.
3. Call `renderToString(component)` on the server.
4. Call `mount(element, component, { hydrate: true })` in the browser.

---

# Without JSX
Source: https://ilha.build/guide/recipes/h

Prefer JSX. When a file cannot use the JSX runtime, call `h()`:

```ts twoslash
import { atom, h } from "ilha";

const Counter = () => {
  const count = atom(0);
  return h(
    "button",
    {
      type: "button",
      onclick: () => count.update((n) => n + 1),
    },
    "count: ",
    count
  );
};
```

`h(type, props, ...children)` is the same factory JSX uses. There is no `html` tagged template in this API.

## Tagged templates

If you want markup that looks like the old html tagged-template helper, look at [@knighted/jsx](https://github.com/knightedcodemonkey/jsx). It is a tagged-template JSX runtime. It is **not** built into Ilha.

It is compatible with Ilha **only if** the tag emits `h()` vnodes (`$$ilha: 1`), not DOM nodes or `React.createElement`. The package defaults to React; override its `createElement` / `fragment` to `h` and `Fragment` from `ilha` if that option exists in the version you install.

Use lowercase event props (`onclick`, not `onClick`). Ilha only binds all-lowercase `on*` keys. `class` and `className` both work.

Prefer real JSX or `h()` for anything you ship. Treat `@knighted/jsx` as an optional authoring layer, not part of the Ilha contract.

---

# Oxlint plugin
Source: https://ilha.build/guide/recipes/oxlint

TypeScript types your props and atoms. It cannot see call order, generator frames, or React-shaped event names. The Oxlint plugin flags those mistakes in the editor and in CI.

The plugin ships as `@ilha/router/oxlint`. It is a JavaScript Oxlint plugin — no extra compiler.

## Install

Install Oxlint and `@ilha/router` if the app does not already depend on the router.

```package-install
npm i -D oxlint @ilha/router
```

## Enable the plugin

Point Oxlint at the export and turn on the rules you want.

```json
{
  "jsPlugins": ["@ilha/router/oxlint"],
  "rules": {
    "oxlint-plugin-ilha/no-conditional-primitive": "error",
    "oxlint-plugin-ilha/no-primitive-outside-component": "error",
    "oxlint-plugin-ilha/no-instruction-outside-generator": "error",
    "oxlint-plugin-ilha/prefer-lowercase-events": "error",
    "oxlint-plugin-ilha/function-in-atom": "error"
  }
}
```

Save this as `.oxlintrc.json` at the repo root. Run `oxlint` in your lint script.

The plugin only treats `atom`, `watch`, and `when` as primitives when you import them from `"ilha"`. A router `action()` or a local binding does not match.

## Rules

| Rule | Catches |
| --- | --- |
| `no-conditional-primitive` | `atom()` / `watch()` / `when()` inside `if` or a loop |
| `no-primitive-outside-component` | Primitive calls at module top level — there is no fiber there |
| `no-instruction-outside-generator` | `when` outside a generator, or without `yield*` |
| `prefer-lowercase-events` | `onClick` instead of `onclick` |
| `function-in-atom` | `atom(fn)` misread as a derived initializer instead of a stored function — use `atom(Atom.map(...))`, `atom(Atom.transform(...))`, or `atom.lazy(() => fn)` |

---

# Server state with PubSub
Source: https://ilha.build/guide/recipes/pubsub-state

Server islands hold state in server memory. To push changes to every connected client, publish snapshots to an [Effect PubSub](https://effect.website/docs/v4/api/effect/PubSub) and expose one streaming action per module.

## The hub pattern

```tsx twoslash
// src/lib/tasks.server.tsx
import * as Effect from "effect/Effect";
import * as PubSub from "effect/PubSub";
import * as Stream from "effect/Stream";
import { action } from "oxidejs";

type Task = { id: string; text: string; completed: boolean };

const tasks: Task[] = [];
const hub = Effect.runSync(PubSub.unbounded<Task[]>({ replay: 1 }));
const notify = () => Effect.runSync(PubSub.publish(hub, [...tasks]));

// The streaming transport: one async generator per module.
export const getTasks = action(async function* () {
  yield* Stream.toAsyncIterable(Stream.fromPubSub(hub));
});

export const addTask = action(async (text: string) => {
  tasks.push({
    id: crypto.randomUUID(),
    text,
    completed: false,
  });
  notify();
});
```

Three pieces:

1. **The hub** holds the change feed. `replay: 1` gives late subscribers the latest snapshot immediately — this is your initial render.
2. **Mutations publish** a fresh snapshot after each change.
3. **One streaming action** is the transport the router wires to the client.

`replay: 1` is what makes SSR work: `renderToString` takes the first stream value, and the replay buffer delivers it instantly.

## Subscribe from an island

```tsx
// src/li/tasks.server.tsx
export const TaskList = async function TaskList() {
  return Stream.map(
    Stream.fromAsyncIterable(getTasks(), (error: unknown) =>
      error instanceof Error ? error : new Error(String(error))
    ),
    (list: Task[]) => (
      <ul>
        {list.map((task) => (
          <li key={task.id}>{task.text}</li>
        ))}
      </ul>
    )
  );
};
```

The scanner sees `Stream.fromAsyncIterable(getTasks(), …)` and wires `getTasks` as the client transport. On the browser, the proxy resumes the same generator over RPC — every publish repaints the island.

## Why the transport action stays

`getTasks` looks redundant — the hub is right there. It is the boundary: the hub lives in server memory, and the browser can only reach it through an RPC generator. Keep one streaming export per server module and call it with `Stream.fromAsyncIterable` inside each island that needs live updates.

## Related

| Topic | Guide |
| --- | --- |
| Server islands | [Server islands](/guide/routing/server-islands) |
| Streams and generators | [Streams](/guide/ui/streams) — paint Effect `Stream` values; `when` for per-emission generators |
| Triggering frames | [Server islands](/guide/routing/server-islands) |

---

# Test components
Source: https://ilha.build/guide/recipes/testing

Test components with Bun's runner. Use `renderToString` for HTML assertions. Add happy-dom only when you mount into real nodes.

## Render to HTML

`renderToString` builds HTML without a DOM. It is async — it waits until in-flight work is idle:

```tsx twoslash
import { atom, renderToString } from "ilha";
import { expect, test } from "bun:test";

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};

test("renders the count", async () => {
  const html = await renderToString(Counter);
  expect(html).toContain(">0<");
});
```

## Mount and simulate events

Mount and event tests need a DOM. Install happy-dom's global registrator and preload it when you mount into real nodes or touch browser-only APIs at import time:

```package-install
bun add -d @happy-dom/global-registrator
```

```toml
# bunfig.toml
[test]
preload = "./happydom.ts"
```

```ts twoslash
// happydom.ts
import { GlobalRegistrator } from "@happy-dom/global-registrator";

GlobalRegistrator.register();
```

For behavior, mount into a detached element and dispatch events:

```tsx twoslash
import { atom, mount } from "ilha";
import { expect, test } from "bun:test";

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};

test("clicking increments", async () => {
  const el = document.createElement("div");
  document.body.append(el);
  const unmount = mount(el, Counter);
  await new Promise((r) => setTimeout(r, 5));

  const button = el.querySelector("button")!;
  button.click();
  await new Promise((r) => setTimeout(r, 5));

  expect(button.textContent).toContain("1");
  unmount();
  el.remove();
});
```

The short sleeps let microtasks paint. `unmount()` stops streams and listeners — call it before removing the host so a late event cannot paint into a detached tree.

## Hydration round-trip

Render, inject, then hydrate to verify a snapshot restores. This path also needs the happy-dom preload above:

```tsx twoslash
import { atom, mount, renderToString } from "ilha";
import { expect, test } from "bun:test";

const App = () => <p>hello</p>;

test("hydrates SSR markup", async () => {
  const html = await renderToString(App);
  const el = document.createElement("div");
  el.innerHTML = html; // test host; markup is your own render output
  document.body.append(el);

  const unmount = mount(el, App, { hydrate: true });
  await new Promise((r) => setTimeout(r, 5));
  expect(el.textContent).toContain("hello");
  unmount();
  el.remove();
});
```

A snapshot-order bug logs a `hydrate mismatch` warning and falls back to a full mount — assert on the warning in CI if hydration is load-bearing for you.

## Related

| Topic                 | Guide                                           |
| --------------------- | ----------------------------------------------- |
| Render and hydrate    | [Render](/guide/ui/render)                      |
| Streams in tests      | [Streams](/guide/ui/streams)                    |
| Server islands in dev | [Server islands](/guide/routing/server-islands) |

---

# View transitions
Source: https://ilha.build/guide/recipes/view-transitions

You animate between UI states with the browser View Transition API. Ilha does not wrap it. Call `document.startViewTransition()` and update an atom inside the callback.

```tsx twoslash
import { atom } from "ilha";

export default function Card() {
  const checked = atom(false);

  const toggle = () => {
    document.startViewTransition(() => {
      checked.update((value) => !value);
    });
  };

  return (
    <button
      type="button"
      class="card"
      onclick={toggle}
      style="view-transition-name: card"
    >
      {checked() ? "Checked" : "Unchecked"}
    </button>
  );
}
```

The callback must update state synchronously so the browser can snapshot both sides of the transition.

---

# Showcase
Source: https://ilha.build/guide/resources/showcase

export const SHOWCASE = [
  {
    title: "Ilha Website",
    image: "/showcase-ilha.jpg",
    link: "https://ilha.build",
  },
  {
    title: "Areia UI",
    image: "/showcase-areia.jpg",
    link: "https://areia.ilha.build",
  },
  {
    title: "thojensen.com",
    image: "/showcase-thojensen.jpg",
    link: "https://thojensen.com",
  },
];

<div class="not-prose grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3">
  {SHOWCASE.map((item) => (
    <a
      key={item.title}
      href={item.link}
      target="_blank"
      rel="noopener noreferrer"
      class="group overflow-hidden rounded-xl border border-border bg-card no-underline transition-colors hover:border-border-strong"
    >
      <img
        alt={item.title}
        loading="lazy"
        class="aspect-video w-full object-cover"
        src={item.image}
      />
      <div class="p-3 text-sm font-medium text-foreground group-hover:text-primary">
        {item.title}
      </div>
    </a>
  ))}
</div>

---

# Deployment
Source: https://ilha.build/guide/routing/deployment

How you deploy depends on whether your app needs SSR/server islands or renders to static HTML.

## SPA + SSR (server-rendered)

For file-system routing with [oxidejs](https://npmjs.com/package/oxidejs), the SSR middleware serves the internal frame endpoint in production — the route-graph imports are implicit:

```ts twoslash
// vite.config.ts
import pages from "@ilha/router/vite";
import oxide from "oxidejs/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [oxide({ middleware: ["@ilha/router/ssr"] }), pages()],
});
```

The `@ilha/router/ssr` middleware serves `POST /__ilha/frame` for server-island and server-page re-renders.

Any host that runs an oxidejs fetch handler serves it. See [Server islands](/guide/routing/server-islands) and [Middleware and security](/guide/routing/middleware-and-security).

If you host the router in your own fetch handler instead, use the manual render methods — `render()`, `renderResponse()`, or `respond()` — described in [Server islands](/guide/routing/server-islands).

## Registering guards in production

Deny-by-default means `/__ilha/frame` returns `403` until you install a guard. Call the guard once at server startup, before handling requests:

```ts twoslash
import { setFrameGuard } from "@ilha/router/ssr";

function isSignedIn(_request: Request) {
  return true;
}
// ---cut---
setFrameGuard((request) =>
  isSignedIn(request)
    ? undefined
    : new Response("Unauthorized", { status: 401 })
);
```

See [Middleware and security](/guide/routing/middleware-and-security) for the full guard, origin, and CSRF model.

## Static prerendering (MPA)

When you do not need runtime SSR or server islands, set `mode: "static"` in the plugin options. The generated client module then exports a `registry` of pages without a route graph. Prerender each route's HTML at build time (for example with `renderResponse`), and mount the matching page from the registry:

```ts
import { mount } from "ilha";
import { registry } from "ilha:pages/client";

const host = document.querySelector<HTMLDivElement>("#app")!;
mount(host, registry["about"]);
```

Hash mode (`setHistoryMode("hash")`) is another static-host option when you cannot serve an SPA fallback for every URL. SSR + hydration is not supported in hash mode.

## Related

| Topic | Guide |
| --- | --- |
| Guards in production | [Middleware and security](/guide/routing/middleware-and-security) |
| Error handling | [Error boundaries](/guide/routing/error-boundaries) |
| Plugin `mode` and virtual modules | [File-system routing](/guide/routing/file-system-routing) |

---

# Error boundaries
Source: https://ilha.build/guide/routing/error-boundaries

A render failure in a page or layout does not take down the app. The nearest error boundary catches it and renders a fallback view.

## Throw from a page

Throw `RouteError` with `error()` (or `redirect()` for navigation):

```tsx twoslash
import { error } from "@ilha/router";

export default async function User({ params }: { params: { id: string } }) {
  const user = await findUser(params.id);
  if (!user) error(404, "No such user");
  return <h1>{user.name}</h1>;
}

async function findUser(_id: string) {
  return null as null | { name: string };
}
```

`error(status, message)` throws a `RouteError`; `redirect(to, status?)` throws a `Redirect` that the router converts into a client navigation.

## +error.tsx files

Drop a `+error.tsx` next to a page (or in a parent folder) to catch failures for everything under that folder. The nearest boundary wins:

```text
src/pages/
  +error.tsx          ← catches all routes
  user/
    +error.tsx        ← catches /user/*
    [id].server.tsx
```

```tsx twoslash
// src/pages/user/+error.tsx
import type { AppError } from "@ilha/router";
import type { View } from "ilha";

export default function ErrorPage({
  error,
  children,
}: {
  error: AppError;
  children?: View;
}) {
  return (
    <div class="card bg-base-100 shadow">
      <div class="card-body">
        <h2 class="card-title">{error.status ?? 500}</h2>
        <p>{error.message}</p>
        {children}
      </div>
    </div>
  );
}
```

Boundary components receive the `error` and the failed route as `children`.

## errorBoundary() on the builder

With a hand-built router, register a boundary per pattern:

```tsx twoslash
import { router } from "@ilha/router";
import { h } from "ilha";

const UserPage = async () => {
  throw new Error("boom");
};

// ---cut---
router()
  .route("/user/:id", UserPage)
  .errorBoundary("/user/:id", (err) => h("p", null, `Oops: ${err.message}`));
```

The handler receives an `AppError` (`message`, `status?`) and a route snapshot, and returns a view or a component.

## wrapError()

Wrap a single page when you want the fallback inline instead of a boundary file:

```tsx twoslash
import { error, wrapError } from "@ilha/router";
import { h } from "ilha";

const UserPage = async () => {
  error(418, "short and stout");
};

// ---cut---
export default wrapError(({ message }) => h("p", null, message), UserPage);
```

`wrapError` catches everything the page throws — `RouteError` or any exception — and calls your handler with `{ message, status? }`.

## Related

| Topic | Guide |
| --- | --- |
| Throwing redirects | [Routes and navigation](/guide/routing/routes-and-navigation) |
| Server pages and frames | [Server islands](/guide/routing/server-islands) |
| Hardening and status codes | [Middleware and security](/guide/routing/middleware-and-security) |

---

# File-system routing
Source: https://ilha.build/guide/routing/file-system-routing

The pages plugin scans `src/pages/`, wraps layouts, and generates a router. Pick the entry for your toolchain:

| Tool    | Import                 |
| ------- | ---------------------- |
| Vite    | `@ilha/router/vite`    |
| Rsbuild | `@ilha/router/rsbuild` |

## Setup

```ts twoslash
import pages from "@ilha/router/vite";
import { defineConfig } from "vite";

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

## File names

| File                  | URL            |
| --------------------- | -------------- |
| `pages/index.tsx`     | `/`            |
| `pages/about.tsx`     | `/about`       |
| `pages/user/[id].tsx` | `/user/:id`    |
| `pages/[...slug].tsx` | `/**:slug`     |
| `pages/+layout.tsx`   | wraps children |
| `pages/+error.tsx`    | error boundary |

`foo.server.tsx` uses the same URL as `foo.tsx` and renders on the server. See [Server islands](/guide/routing/server-islands).

## Page module

Export a default component:

```tsx
import { head } from "@ilha/router";

export default function Home() {
  head({ title: "Home" });
  return <h1>Home</h1>;
}
```

## Layout

```tsx twoslash
import type { View } from "ilha";

export default function Layout({ children }: { children?: View }) {
  return (
    <div>
      <nav>
        <a href="/">Home</a>
      </nav>
      <main>{children}</main>
    </div>
  );
}
```

## Client entry

```ts
import { pageRouter } from "ilha:pages/client";

pageRouter.mount("#app");
```

Hydrate when the host already has SSR markup:

```ts
pageRouter.mount("#app", { hydrate: true });
```

---

# Middleware and security
Source: https://ilha.build/guide/routing/middleware-and-security

`@ilha/router` hardens the server-island endpoint by default. This page is the full guard and origin model behind [Server islands](/guide/routing/server-islands).

## Security headers

Both `respond()` and the low-level `httpResponse()` emit sensible security headers by default:

| Header                   | Value         |
| ------------------------ | ------------- |
| `Content-Type`           | `text/html`   |
| `X-Content-Type-Options` | `nosniff`     |
| `Referrer-Policy`        | `no-referrer` |
| `Cache-Control`          | `no-store`    |

A header is added only when the caller has not already set it, so you can override any default by passing `headers`.

```tsx twoslash
import { httpResponse } from "@ilha/router";
const html = "<h1>Hi</h1>";
const nonce = "abc123";
// ---cut---
// Default: nosniff, no-referrer, no-store (see table above).
const res = httpResponse("<h1>Hi</h1>");

// Conservative default CSP via a nonce — pass the same nonce to <script nonce=…>.
const withCsp = httpResponse(html, { cspNonce: nonce });

// Full CSP string wins over the nonce-derived default.
const locked = httpResponse(html, {
  contentSecurityPolicy: "default-src 'self'",
});
```

| Option | Behavior |
| --- | --- |
| `status` | Response status (default `200`). |
| `headers` | Extra headers, merged over defaults. |
| `cspNonce` | Emit a conservative default CSP with `'nonce-${nonce}'` for `script-src`. |
| `contentSecurityPolicy` | Full CSP string; overrides the nonce-derived default. |

Prefer `respond()` when you are rendering a route — it runs the full render + head + headers pipeline. Reach for `httpResponse()` when you already have the HTML and only need a correctly-headered `Response`.

## Deny-by-default frame endpoint

In **production**, the internal frame endpoint is **denied unless you install a guard**:

| Endpoint | Serves | Method | Default when unguarded |
| --- | --- | --- | --- |
| `/__ilha/frame` | Re-render of a server island or server page | POST | Denied (`403`) |

An unguarded frame endpoint would let anyone re-render any server island by id — if an island's state holds private data you must install a session check. The **dev** middleware stays permissive unless you register a guard, so local iteration works out of the box.

## Installing guards

Register guards once at server startup for production, via the shared registry:

```ts twoslash
import { setFrameAuth, setFrameGuard } from "@ilha/router/ssr";

const expectedToken = process.env.CSRF_TOKEN;
function isSignedIn(_request: Request) {
  return true;
}
// ---cut---
// Gates /__ilha/frame in production; without this the endpoint returns 403.
setFrameGuard((request) => {
  if (!isSignedIn(request))
    return new Response("Unauthorized", { status: 401 });
});

// Optional: explicit trusted origins and a CSRF verifier for the frame POST.
setFrameAuth({
  trustedOrigins: ["https://app.example.com"],
  // Verify a per-session token issued by your server (double-submit cookie or
  // synchronizer token), compared in constant time. Never use a build-time
  // environment variable or literal string — anything shipped to the browser
  // is public and cannot be a CSRF secret.
  csrf: (request) => request.headers.get("x-csrf") === expectedToken,
});
```

In **dev**, configure the guard through the plugin options instead — pass `frameGuard` to the pages plugin.

### `setFrameAuth`

Tuning the frame-auth policy:

| Option | Type | Behavior |
| --- | --- | --- |
| `defaultAction` | `"open" \| "deny"` | `"deny"` is the default. `"open"` opts out of deny-by-default (not recommended). |
| `trustedOrigins` | `string[]` | Explicit origins to accept for frame origin checks. Otherwise the `Origin` header is compared against the request's own `Host`. |
| `csrf` | `(request) => boolean` | Extra verifier for the frame POST — covers non-browser callers that send no `Origin` header. |

## What is forwarded

The middleware forwards only `cookie`, `authorization`, and `user-agent` headers to the scoped frame render. It deliberately does **not** forward a client-supplied `x-forwarded-for` header — it is spoofable and must not be trusted for IP checks. If you relied on it for IP-based decisions, move that check to a trusted proxy layer instead.

## Validation and status clamping

- Frame bodies are streamed with a hard **16&nbsp;KiB cap**; oversized bodies return `413`.
- Frame paths are validated and **fail closed** — an invalid path returns `400` instead of falling back to `/`.
- Failures are typed: the frame render returns a `FrameError` result, and `redirect()` coerces invalid statuses to `302`; `error()` coerces invalid statuses to `500` (silently).
- Render failures surface as `"frame failed"` — error details are never leaked to clients in production.

## Related

| Topic | Guide |
| --- | --- |
| Server islands and frames | [Server islands](/guide/routing/server-islands) |
| Error handling | [Error boundaries](/guide/routing/error-boundaries) |
| Guards via the pages plugin | [File-system routing](/guide/routing/file-system-routing) |
| Production wiring | [Deployment](/guide/routing/deployment) |

---

# Router overview
Source: https://ilha.build/guide/routing/overview

`@ilha/router` matches URLs to components. It is a separate package from `ilha`. Add it when you need more than one page.

Every route is a component. The router matches the URL and mounts the page. Read the current route with `useRoute()`, `head()`, and `isActive()`.

## Install

```package-install
@ilha/router
```

## Import paths

| Import path | Use it for |
| --- | --- |
| `@ilha/router` | Runtime router, navigation, `head`, route hooks |
| `@ilha/router/vite` | Vite file-system routing plugin |
| `@ilha/router/rsbuild` | Rsbuild file-system routing plugin |
| `@ilha/router/server-island` | Client proxies for `*.server` modules (generated) |
| `@ilha/router/ssr` | `POST /__ilha/frame` middleware and frame guards |

There is no loader API. Fetch in an async page, or stream from a server module.

## Quick start

### Client SPA

```tsx twoslash
import { router } from "@ilha/router";

const HomePage = () => <p>home</p>;
const AboutPage = () => <p>about</p>;
const NotFound = () => <p>not found</p>;

router()
  .route("/", HomePage)
  .route("/about", AboutPage)
  .route("/**", NotFound)
  .mount("#app");
```

### File-system routes

```ts twoslash
import { pages } from "@ilha/router/vite";
import { defineConfig } from "vite";

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

Put pages in `src/pages/`. See [File-system routing](/guide/routing/file-system-routing).

### Server HTML

Add Oxide and the SSR middleware when pages or islands run on the server:

```ts twoslash
import pages from "@ilha/router/vite";
import oxide from "oxidejs/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [oxide({ middleware: ["@ilha/router/ssr"] }), pages()],
});
```

See [Server islands](/guide/routing/server-islands).

---

# Routes and navigation
Source: https://ilha.build/guide/routing/routes-and-navigation

Create a router, register each URL pattern, then mount it:

```tsx twoslash
import { router } from "@ilha/router";

const Home = () => <h1>Home</h1>;
const User = () => <h1>User</h1>;
const NotFound = () => <h1>Not found</h1>;

router({ notFound: NotFound })
  .route("/", Home)
  .route("/user/:id", User)
  .mount("#app");
```

## Match route patterns

| Pattern         | Example URL         | Params                            |
| --------------- | ------------------- | --------------------------------- |
| `/`             | `/`                 | `{}`                              |
| `/user/:id`     | `/user/42`          | `{ id: "42" }`                    |
| `/:org/:repo`   | `/ilha/router`      | `{ org: "ilha", repo: "router" }` |
| `/docs/**:slug` | `/docs/guide/intro` | `{ slug: "guide/intro" }`         |
| `/**`           | any unmatched path  | `{}`                              |

Static segments win over parameters, then catch-alls.

## Links and navigate

Use an ordinary `<a href>`. A mounted SPA router intercepts same-origin clicks:

```tsx twoslash
const Navigation = () => (
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
);
```

Use `navigate()` after application logic:

```ts twoslash
import { navigate } from "@ilha/router";

navigate("/about");
navigate("/account", { replace: true });
navigate("/results?page=2", { scroll: false });
```

## Read the current route

```tsx twoslash
import { useRoute } from "@ilha/router";

const UserPage = () => {
  const { path, params, search } = useRoute();
  return (
    <p>
      {path()} {params().id} {search()}
    </p>
  );
};
```

`isActive(href)` is true when the current path matches.

## Head

```tsx
import { head } from "@ilha/router";

export default function About() {
  head({ title: "About" });
  return <h1>About</h1>;
}
```

Layouts can set `titleTemplate`. On the client, `head()` updates `document` after mount and on navigation. See the [router reference](/reference/router).

---

# Server islands
Source: https://ilha.build/guide/routing/server-islands

Use [Oxide](https://npmjs.com/package/oxidejs) when a component must close over server data. You keep the SPA authoring model. Files named `*.server.tsx` never ship their render function to the browser.

```ts twoslash
import pages from "@ilha/router/vite";
import oxide from "oxidejs/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [oxide({ middleware: ["@ilha/router/ssr"] }), pages()],
});
```

The middleware owns:

| Endpoint             | Purpose                      |
| -------------------- | ---------------------------- |
| `POST /__ilha/frame` | Render a server island again |

There is no page loader endpoint. Fetch inside an async component, or yield from a streaming action.

## One island on the server

Put the component in `*.server.ts(x)`:

```tsx
import * as Stream from "effect/Stream";
import { action } from "oxidejs";

export const deleteTask = action(async (id: string) => {
  await db.tasks.delete(id);
});

export const getTasks = action(async function* () {
  yield await db.tasks.list();
});

export const TaskList = async function TaskList() {
  return Stream.map(
    Stream.fromAsyncIterable(getTasks(), (error: unknown) =>
      error instanceof Error ? error : new Error(String(error))
    ),
    (list: { id: string; text: string }[]) => (
      <ul>
        {list.map((task) => (
          <li key={task.id}>
            {task.text}
            <button type="button" onclick={deleteTask.with(task.id)}>
              Remove
            </button>
          </li>
        ))}
      </ul>
    )
  );
};
```

Import it from a regular page:

```tsx
import { TaskList } from "$lib/tasks.server";

export default function Home() {
  return <TaskList />;
}
```

The plugin replaces the server module with a client proxy. The proxy posts `/__ilha/frame`, morphs the HTML, and reconnects events.

Mark RPC functions with `action` from `oxidejs`. Bind them with `.with(...)` on event props so SSR can emit frame sentinels without running your handler during render.

Subscribe with `Stream.fromAsyncIterable(getTasks())` so the scanner wires a live stream. Each yield refetches the frame.

## Whole route on the server

Name the page `foo.server.tsx`. Export a default component. The client still mounts a proxy and pulls the first frame.

## Auth

Frames are deny-by-default in production. For a public demo:

```ts twoslash
import { setFrameAuth } from "@ilha/router/ssr";

setFrameAuth({ defaultAction: "open" });
```

Install `setFrameGuard()` when islands serve private data. See [Middleware and security](/guide/routing/middleware-and-security).

---

# Create component
Source: https://ilha.build/guide/ui/create

A component is a function that returns a view. Sync functions return JSX. Async functions can await. Generators `yield` streams or `yield*` Effects and `when`.

```tsx twoslash
const Hello = () => <p>Hello</p>;
```

Call `Hello` from another component as a nested function. Call `mount` or `renderToString` with `Hello` when it is the root.

## Props

Pass props as the first argument:

```tsx twoslash
const Greeting = ({ name }: { name: string }) => <p>Hello, {name}</p>;
```

When you mount a root that needs props, close over them:

```tsx twoslash
import { mount } from "ilha";

const Greeting = ({ name }: { name: string }) => <p>Hello, {name}</p>;

const root = document.getElementById("app");
if (root) mount(root, () => Greeting({ name: "Ada" }));
```

## Nested functions

A nested function shares the parent fiber. Atoms you declare there still belong to the parent. Keep call order stable across reruns.

```tsx twoslash
import { atom } from "ilha";

const Label = (props: Record<string, unknown>) => (
  <span>{String(props.text)}</span>
);

const Card = () => {
  const title = atom("Inbox");
  return (
    <section>
      <Label text={title()} />
    </section>
  );
};
```

## Async component

```tsx twoslash
const Page = async () => {
  const title = await Promise.resolve("Home");
  return <h1>{title}</h1>;
};
```

`renderToString` waits until the promise settles and later work goes idle.

## Generator component

Use a generator when you `yield` a `Stream` of views or `yield* when(...)`. See [Streams](/guide/ui/streams).

## JSX config

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "ilha"
  }
}
```

Markup, events, and lists are in [Templating](/guide/ui/templating).

---

# Custom elements
Source: https://ilha.build/guide/ui/custom-elements

`define(name, component)` registers a custom element. On connect it mounts the component. If the host has `data-ilha`, it hydrates.

```tsx twoslash
import { atom } from "ilha";
import { define } from "ilha/define";

define("ilha-counter", () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
});
```

```html
<ilha-counter></ilha-counter>
```

Disconnect unmounts. Use this when you want HTML to instantiate the component without a JS `mount()` call site.

---

# Render and hydrate
Source: https://ilha.build/guide/ui/render

A component returns JSX. You turn that into HTML on the server and into a live tree in the browser.

| API | Env | Output |
| --- | --- | --- |
| `await renderToString(component)` | Server | HTML plus snapshot wrap |
| `await renderToString(component, { markers: false })` | Server | Inner HTML only |
| `mount(el, component)` | Client | Live tree |
| `mount(el, component, { hydrate: true })` | Client | Hydrate existing HTML |

## Return a view

Prefer JSX. Strings become text nodes.

```tsx twoslash
const A = () => <p>Hello</p>;
const B = () => "hello";
```

## Server render

```tsx twoslash
import { atom, renderToString } from "ilha";

const Counter = () => {
  const count = atom(0);
  return <p>{count}</p>;
};

const html = await renderToString(Counter);
```

Default output looks like:

```html
<div data-ilha data-ilha-state='{"v":[0]}'>
  <p>0</p>
</div>
```

| Option           | Default | Meaning                                      |
| ---------------- | ------- | -------------------------------------------- |
| `snapshot`       | `true`  | Embed atom values for hydration              |
| `markers`        | `true`  | Wrap in `<div data-ilha>`                    |
| `timeout`        | none    | Serialize after this many ms even if busy    |
| `captureActions` | `false` | Probe event handlers for server-action calls |

Pass `{ markers: false }` when a host already exists (for example a frame target).

`renderToString` builds HTML without a DOM. It runs in Node, Bun, and edge runtimes with no polyfill.

## Mount

```tsx twoslash
import { mount } from "ilha";

const App = () => <p>Hello</p>;

const root = document.getElementById("app");
if (root) {
  const unmount = mount(root, App);
}
```

## Hydrate

If the host contains `[data-ilha]` markup from `renderToString`, pass `hydrate: true`:

```tsx twoslash
import { mount } from "ilha";

const App = () => <p>Hello</p>;

const root = document.querySelector("[data-ilha]");
if (root) mount(root, App, { hydrate: true });
```

Hydration restores atom snapshots in declaration order, then attaches events. A mismatch logs a warning and does a full mount.

## File routes

`@ilha/router` calls `renderToString` and `mount` for you. See [Routing](/guide/routing/overview).

---

# State management
Source: https://ilha.build/guide/ui/state

## atom()

Declare local state with `atom()`. Reads during render subscribe the component; writes rerun it.

```tsx twoslash
import { atom } from "ilha";

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};
```

| Call                         | Meaning                |
| ---------------------------- | ---------------------- |
| `count()`                    | Read the current value |
| `{count}` in JSX             | Read and subscribe     |
| `count.set(1)`               | Replace                |
| `count.update((n) => n + 1)` | Patch from previous    |

### Where you read matters

A read in the component body (`count()` or `String(count())`) subscribes the **whole component** to rerun. Passing the handle in JSX (`{count}`) gives that node its own subscription and updates only that subtree. Prefer `{count}` in markup when you do not need the value in logic.

In `async` components, declare atoms before the first `await`. After an `await`, pass handles in JSX instead of calling them in the body — only the synchronous setup pass collects render dependencies.

## Derived atoms

Pass `handle.atom` to Effect, wrap the result in `atom()`:

```tsx twoslash
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom } from "ilha";

const Cart = () => {
  const items = atom([
    { id: "a", n: 1 },
    { id: "b", n: 2 },
  ]);
  const total = atom(
    Atom.map(items.atom, (list) => list.reduce((sum, item) => sum + item.n, 0))
  );
  return <p>{total}</p>;
};
```

| API | Use when |
| --- | --- |
| `Atom.map(source, f)` | Pure function of one atom |
| `Atom.transform(source, (get, source) => …)` | Reads more than one atom via `get` |

```tsx twoslash
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom } from "ilha";

const Form = () => {
  const first = atom("");
  const last = atom("");
  const fullName = atom(
    Atom.transform(first.atom, (get) =>
      `${get(first.atom)} ${get(last.atom)}`.trim()
    )
  );
  return <p>{fullName}</p>;
};
```

## Side effects

Render subscription reruns the component — it is not `useEffect`. Use `watch()` for callbacks on atom changes:

```tsx twoslash
import { atom, watch } from "ilha";

const Profile = () => {
  const name = atom("john");
  watch(name, (value) => {
    document.title = value;
  });
  return (
    <input value={name} oninput={(e) => name.set(e.currentTarget.value)} />
  );
};
```

Call `watch()` before any `await` in async components. Guard DOM access on the server. For streams and `when`, see [Streams](/guide/ui/streams).

## Batching writes

`batch()` notifies subscribers once after multiple writes:

```tsx twoslash
import { atom, batch } from "ilha";

const Panel = () => {
  const a = atom(0);
  const b = atom(0);
  const reset = () => {
    batch(() => {
      a.set(0);
      b.set(0);
    });
  };
  return (
    <button type="button" onclick={reset}>
      {a}-{b}
    </button>
  );
};
```

## Async mutations

`atom(Atom.fn(...))` runs an Effect when you call `.set()`:

```tsx twoslash
import * as Atom from "effect/unstable/reactivity/Atom";
import * as Effect from "effect/Effect";
import { atom } from "ilha";

const Form = () => {
  const save = atom(
    Atom.fn((email: string) =>
      Effect.tryPromise({
        try: () =>
          fetch("/api/waitlist", {
            method: "POST",
            body: JSON.stringify({ email }),
          }).then((r) => r.json()),
        catch: (e) => e,
      })
    )
  );
  return (
    <form
      onsubmit={(e) => {
        e.preventDefault();
        const email = String(new FormData(e.currentTarget).get("email") ?? "");
        if (Atom.isWritable(save.atom)) save.set(email as never);
      }}
    >
      <input name="email" type="email" placeholder="you@company.com" />
      <button type="submit">Join waitlist</button>
    </form>
  );
};
```

For optimistic updates, use [`Atom.optimisticFn`](https://www.effect.website/docs/v4/api/effect/unstable/reactivity/Atom#optimisticfn).

## Lazy initialization

`atom.lazy(() => …)` runs once per slot. Use it for expensive init or to store a function value — not `atom(fn)`.

```tsx twoslash
import { atom } from "ilha";

const Panel = () => {
  const settings = atom.lazy(() => {
    if (typeof localStorage === "undefined") return {};
    return JSON.parse(localStorage.getItem("prefs") ?? "{}");
  });
  return <p>{JSON.stringify(settings())}</p>;
};
```

## Props vs state

State initialized from props does not reset when props change. Atoms hold data, not JSX.

---

# Streams
Source: https://ilha.build/guide/ui/streams

## Streams

Generator components can **yield** a `Stream` of views. Compose with Effect (`Stream.map`, `Stream.pipe`, …) — Ilha repaints on each emission. SSR takes the first value only; the client keeps listening after `mount`.

```tsx twoslash
import * as Stream from "effect/Stream";

function* Status() {
  yield Stream.map(Stream.fromIterable(["idle", "ready"]), (value) => (
    <p>{value}</p>
  ));
}
```

Async components can return a `Stream` directly — no generator required.

## Atom.toStream

Turn an atom into a change feed with [`Atom.toStream`](https://www.effect.website/docs/v4/api/effect/unstable/reactivity/Atom#tostream):

```tsx twoslash
import * as Stream from "effect/Stream";
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom } from "ilha";

function* List() {
  const items = atom(["a", "b"]);
  yield Stream.map(Atom.toStream(items.atom), (list) => (
    <ul>
      {list.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  ));
}
```

Use `items().map(...)` in a sync component for a simple list. Reach for `Atom.toStream` when a stream pipeline should drive updates (debounce, merge, server feeds).

## when

`when(stream, body)` runs a generator `body` per emission. A new value interrupts the previous body — stale async work does not paint.

```tsx twoslash
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom, when } from "ilha";

function* Search() {
  const query = atom("");
  yield (
    <input value={query} oninput={(e) => query.set(e.currentTarget.value)} />
  );
  yield* when(
    Atom.toStream(query.atom).pipe(Stream.debounce("200 millis")),
    function* (q) {
      if (!q) {
        yield <p>Type to search</p>;
        return;
      }
      const items = yield* Effect.tryPromise({
        try: (signal) =>
          fetch(`/api/search?q=${encodeURIComponent(q)}`, {
            signal,
          }).then((r) => r.json()),
        catch: (e) => e,
      });
      yield (
        <ul>
          {(items as string[]).map((item) => (
            <li key={item}>{item}</li>
          ))}
        </ul>
      );
    }
  );
}
```

`yield Stream.map(...)` is enough for a stream of views. Use `when` when each emission needs its own async generator.

## Generators

| Yield              | Meaning                                    |
| ------------------ | ------------------------------------------ |
| `yield <p>…</p>`   | Paint this view                            |
| `yield stream`     | Subscribe to a `Stream` of views           |
| `yield* effect`    | Run an `Effect` (fetch, sleep, `Deferred`) |
| `yield* when(...)` | Per-emission body; stale bodies interrupt  |

Uncaught failures paint an error view.

## Side effects

For atom-driven side effects in any component, use [`watch()`](/guide/ui/state#side-effects). In generators, `yield* Stream.runForEach` works for finite streams:

```tsx twoslash
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

function* Boot() {
  yield* Stream.runForEach(Stream.fromIterable([1, 2, 3]), (n) =>
    Effect.sync(() => console.log(n))
  );
  yield <p>Ready</p>;
}
```

Co-locate DOM effects in event handlers when you own the write site.

## Deferred

Paint UI, wait for input, then continue:

```tsx twoslash
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";

function* Gate() {
  const deferred = yield* Deferred.make<string>();
  yield (
    <button
      type="button"
      onclick={() => Effect.runSync(Deferred.succeed(deferred, "Ada"))}
    >
      Continue
    </button>
  );
  const name = yield* Deferred.await(deferred);
  yield <p>Hello, {name}</p>;
}
```

## Server feeds

Map a server stream to JSX with `Stream.fromAsyncIterable`. SSR serializes the first value; the client resumes the feed. See [Server islands](/guide/routing/server-islands) and [PubSub state](/guide/recipes/pubsub-state).

---

# Templating
Source: https://ilha.build/guide/ui/templating

Prefer JSX. Interpolated values escape. Use `class`, not `className`.

```tsx twoslash
const Hello = ({ name }: { name: string }) => <p class="lede">Hello, {name}</p>;
```

Use `h()` when a file cannot use the JSX runtime. See [Without JSX](/guide/recipes/h).

## Events

Event props are lowercase native names: `onclick`, `onchange`, `onsubmit`. Use a plain function. You do not need a special action wrapper on the client.

```tsx twoslash
import { atom } from "ilha";

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};
```

On a server island, bind `oxidejs` `action`s with `.with(...)` on event props so SSR can serialize frame sentinels. Plain client islands keep plain handlers. See [Server islands](/guide/routing/server-islands).

## Lists

Atoms hold data. Map an array during render:

```tsx twoslash
import { atom } from "ilha";

type Item = { id: string; text: string };

const List = () => {
  const items = atom<Item[]>([{ id: "1", text: "One" }]);
  return (
    <ul>
      {items().map((item) => (
        <li key={item.id}>{item.text}</li>
      ))}
    </ul>
  );
};
```

When `items` changes, the component reruns and morphs the list. Keys on `li` reuse DOM nodes when the array shifts.

For live server lists, paint a Stream into a hole. See [Streams](/guide/ui/streams).

---

# Astro reference
Source: https://ilha.build/reference/astro

See [Astro](/guide/astro) for setup.

Default export: `ilha(options?)` Astro integration.

| Option    | Meaning                                     |
| --------- | ------------------------------------------- |
| `include` | Glob or list of globs this renderer accepts |
| `exclude` | Glob or list of globs this renderer skips   |

Named exports: `getRenderer()`, `getViteConfig(options)`.

The server entry calls `renderToString`. The client entry calls `mount(..., { hydrate })`.

---

# Core package reference
Source: https://ilha.build/reference/ilha

Use this page as a map of the public `ilha` API. Start with [Introduction](/guide/getting-started/introduction) if you are building your first component.

## Component

A component is a function, async function, or generator that returns a view.

```tsx twoslash
import { atom } from "ilha";

const Status = () => <p>Ready</p>;

const Greeting = ({ name }: { name: string }) => <p>Hello, {name}</p>;

const Counter = () => {
  const count = atom(0);
  return (
    <button type="button" onclick={() => count.update((n) => n + 1)}>
      {count}
    </button>
  );
};
```

Nested functions share the parent fiber. `mount` / `renderToString` on a function makes it a root.

## Named exports

| Export | Purpose | Learn more |
| --- | --- | --- |
| `atom(init)` | Writable reactive value | [State](/guide/ui/state) |
| `atom.lazy(init)` | One-time initializer | [State](/guide/ui/state) |
| `batch(fn)` | Coalesce multiple atom writes | [State](/guide/ui/state) |
| `watch(source, fn)` | Callback on atom or stream changes | [State](/guide/ui/state) |
| `when(stream, body)` | Per-emission generator (interrupts stale) | [Streams](/guide/ui/streams) |
| `h` / `Fragment` | JSX factory | [Templating](/guide/ui/templating) |
| `mount` | Activate a component in the DOM | [Render](/guide/ui/render) |
| `renderToString` | Serialize a component to HTML | [Render](/guide/ui/render) |

Paint Effect [`Stream`](https://www.effect.website/docs/v4/api/effect/Stream) values with `yield Stream.map(...)` — see [Streams](/guide/ui/streams).

`define` lives at `ilha/define` — see [Custom elements](/guide/ui/custom-elements).

## atom

| Call               | Meaning                |
| ------------------ | ---------------------- |
| `atom(value)`      | Writable atom          |
| `atom.lazy(fn)`    | Run `fn` once on init  |
| `atom(effectAtom)` | Wrap an Effect atom    |
| `count()`          | Read                   |
| `count.set(v)`     | Replace                |
| `count.update(fn)` | Patch                  |
| `count.atom`       | Underlying Effect atom |

Derived values use Effect's `Atom.map` or `Atom.transform` — pass `handle.atom`, then wrap in `atom()`:

```tsx twoslash
import * as Atom from "effect/unstable/reactivity/Atom";
import { atom } from "ilha";

const items = atom([1, 2]);
const sum = atom(
  Atom.map(items.atom, (list) => list.reduce((total, n) => total + n, 0))
);
```

### Atoms from Effect

The initializer also accepts an Effect atom, an Effect, or a Stream:

```tsx twoslash
import * as Effect from "effect/Effect";
import { atom } from "ilha";

declare const effect: Effect.Effect<string>;
// ---cut---
const status = atom(effect);
```

The value of an Effect-backed atom is an Effect `AsyncResult`. During paint, waiting results keep the previous view, failures render the error text, and successes render the value. Use this to hold async data in atoms; for streams of views, prefer [Streams](/guide/ui/streams).

## watch

Order-based primitive — call at the top level of a component. Runs `fn` when `source` changes and once on mount. Accepts an atom handle, `handle.atom`, or a `Stream`.

## when

Generator instruction — use with `yield*` inside a generator component. Prefer yielding a `Stream` of views directly when you do not need per-emission interruption.

- `when(stream, body)` — run generator `body` for each value; a new value interrupts the previous body. SSR takes the first value.

Stream views (`yield Stream.map(...)`) also take one value on SSR. Side effects and user-gated flows use Effect (`Stream.runForEach`, `Deferred`) — see [Streams](/guide/ui/streams).

## renderToString

```ts
await renderToString(component, {
  snapshot?: boolean;      // embed atom values for hydration (default true)
  markers?: boolean;       // wrap in <div data-ilha> (default true)
  timeout?: number;        // serialize after this many ms even if busy
  captureActions?: boolean; // probe handlers for server-action calls
});
```

Waits until in-flight work is idle, then serializes. `when` and Stream views take one value.

## mount

```ts
const unmount = mount(element, component, {
  hydrate?: boolean;              // restore snapshots from existing markup
  onError?: (error) => void;      // component failure hook
});
```

## Types

`Component`, `View`, `AtomHandle`, `MountOptions`, `RenderToStringOptions`.

---

# Router reference
Source: https://ilha.build/reference/router

See [Router overview](/guide/routing/overview) for a guided tour.

## `@ilha/router`

### Router

```ts
router(options?: RouterOptions): RouterBuilder
```

| Router option | Meaning |
| --- | --- |
| `mode` | `"spa"` (default) or `"static"` (registry only) |
| `notFound` | Component for unmatched paths |
| `interceptLinks` | Intercept same-origin `<a>` clicks (default `true`) |
| `viewTransitions` | Wrap navigations in the View Transition API |
| `allowExternalRedirects` | Allow cross-origin redirects (default `false`) |

### Builder

| Method | Purpose |
| --- | --- |
| `route(pattern, page)` | Register a URL pattern |
| `errorBoundary(pattern, handler)` | Catch failures for a pattern |
| `mount(target, { hydrate?, interceptLinks? })` | Activate in the browser |
| `render(url)` | HTML string |
| `renderResponse(url)` | `{ kind, html / to, status, head }` |
| `respond(url)` | `Response` with security headers |

Render results are discriminated: `{ kind: "html" }`, `{ kind: "redirect", to, status }`, or `{ kind: "error", status, html, message }`.

### Route context

| Export | Meaning |
| --- | --- |
| `useRoute()` | `{ path, params, search }` accessors |
| `routePath()` / `routeParams()` / `routeSearch()` | Standalone accessors |
| `navigate(to, { replace?, scroll? })` | Programmatic navigation |
| `isActive(href)` | True when the current path matches |
| `afterNavigate(fn)` | Hook after every navigation |
| `setHistoryMode(mode)` | `"history"` (default) or `"hash"` |

### Head

```ts
head(
  title?: string;
  titleTemplate?: string | ((title?: string) => string);
  meta?: Array<Record<string, string>>;
  link?: Array<Record<string, string>>;
  script?: Array<Record<string, string> & { children?: string }>;
});
```

Call inside a page or layout. Layouts typically set `titleTemplate`; pages set `title`. Works during SSR and on the client (mutates `document.head` / `document.title`).

### Pages and errors

| Export | Purpose |
| --- | --- |
| `wrapLayout(layout, page)` | Wrap a page in a layout (`children` carries it) |
| `wrapError(handler, page)` | Catch page throws, render a fallback view |
| `defineLayout(layout)` | Type helper for layout components |
| `redirect(to, status?)` / `error(status, message)` | Throw `Redirect` / `RouteError` |
| `httpResponse(html, { status?, headers?, cspNonce?, contentSecurityPolicy? })` | Headered `Response` |

`AppError` is `{ message, status?, stack? }`. See [Error boundaries](/guide/routing/error-boundaries).

## `@ilha/router/vite` and `/rsbuild`

`pages(options?)` — file-system routing plugin. Default dir `src/pages`, out `.ilha`.

| Option           | Meaning                                |
| ---------------- | -------------------------------------- |
| `dir`            | Pages directory                        |
| `outDir`         | Generated modules directory            |
| `mode`           | `"spa"` or `"static"`                  |
| `frameGuard`     | Dev frame guard                        |
| `trustedOrigins` | Explicit origins for frame checks      |
| `csrf`           | Optional CSRF verifier for frame POSTs |

Virtual modules: `ilha:pages/client`, `ilha:pages/server` — see [File-system routing](/guide/routing/file-system-routing).

## `@ilha/router/ssr`

Production middleware for `POST /__ilha/frame`.

| Export | Purpose |
| --- | --- |
| `ssr` (default) | The fetch handler itself |
| `setFrameAuth` | `defaultAction`, `trustedOrigins`, `csrf` |
| `setFrameGuard` | Per-request allow/deny |
| `renderServerIsland(id, request, runWithScope, props?)` | Render one server island — returns `Effect<string, FrameError>`. Use `renderServerIslandResult` for a plain `Promise` |

## `@ilha/router/server-island`

Generated client proxies. You do not import this in app code.

---

# Tutorial: Atom
Source: https://ilha.build/tutorial/counter/atom

import { example } from "./atom.examples";

You declare reactive values with `atom()`. Reads during render subscribe the component. Writes rerun it.

<Preview code={example} size="lg" />

## Similar concepts

- React: `useState`
- Vue: `ref()`
- Svelte: `$state()`

---

# Tutorial: Events
Source: https://ilha.build/tutorial/counter/events

import { example } from "./events.examples";

Use lowercase native event props. A plain function is enough. You do not need a special action wrapper on the client.

<Preview code={example} size="lg" />

---

# Tutorial: SSR
Source: https://ilha.build/tutorial/counter/ssr

On the server:

```tsx twoslash
import { atom, renderToString } from "ilha";

const Counter = () => {
  const count = atom(0);
  return <p>{count}</p>;
};

const html = await renderToString(Counter);
```

In the browser, mount with `hydrate: true` when the host already contains that markup:

```tsx twoslash
import { mount } from "ilha";

const Counter = () => <p>0</p>;

const host = document.querySelector("[data-ilha]");
if (host) mount(host, Counter, { hydrate: true });
```

`@ilha/router` and `@ilha/astro` do this for you.