Introduction

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

It lets you render on the server and mount in the browser with fine-grained signal reactivity, without a virtual DOM or compiler overhead. The result is a UI model that stays close to HTML while still giving you state, events, lifecycle hooks, scoped styles, and hydration when you need them.

What ilha is

An island is a self-contained component that knows how to render itself to HTML and how to activate itself in the browser. That means the same component can be used for server-side rendering, client-side mounting, or both together in a hydration flow.

ilha is built around a fluent builder chain. You declare input, state, derived values, event handlers, effects, transitions, and styles, then finish with .render() to produce a reusable component.

Why it exists

Most UI stacks force you to choose between simplicity and interactivity. ilha keeps both close together: a small API surface, direct DOM updates through signals, and a rendering model that works naturally on the server.

This makes ilha a good fit when you want:

• Server-rendered markup.
• Small, focused interactive islands.
• Explicit state and behavior.
• No virtual DOM layer.
• A lightweight mental model for UI code.

How it feels to use

A typical island reads a lot like a small HTML-aware module:

The same component can render to a string on the server and mount into the DOM on the client. That keeps the component logic in one place instead of splitting it across separate templates and client scripts.

Core ideas

Isomorphic rendering

ilha can produce HTML on the server and activate the same component in the browser. That makes it useful for SSR, hydration, and progressive enhancement.

Fine-grained reactivity

State is handled with signals, so updates are targeted and local. You do not need to rerender an entire application tree just to change one value.

JSX-first authoring

ilha is designed to work naturally with JSX/TSX. The DOM-like syntax is familiar to most developers, and you get full TypeScript support, IDE autocompletion, and standard tooling out of the box.

If you prefer a lower-level option or need to avoid a build step, the html`` tagged-template API is also available. It uses the same runtime and reactivity model, so you can mix both styles or migrate incrementally.

Builder-based composition

The fluent API lets you layer behavior step by step:

• .input() for typed props.
• .state() for local reactive state.
• .derived() for computed values.
• .on() for events.
• .effect() and .onMount() for side effects.
• .css() for scoped styles.
• .render() to finalize the component.

When to use ilha

ilha is a strong fit when you want:

• Interactive UI with small, explicit components.
• SSR-friendly rendering without heavy framework machinery.
• A simple way to mix server output and client behavior.
• Reusable islands rather than one large application shell.

It is less about building a giant monolithic app framework and more about composing focused UI pieces that each own their own state and behavior.

Basic mental model

Think of an island as a component with three parts:

• Input: data from the outside world.
• State: reactive values owned by the component.
• Render: HTML output driven by that state and input.

Then add behavior on top with events, effects, bindings, and lifecycle hooks. Once you understand that pattern, the rest of the API is mostly a set of focused ways to connect those pieces.