Static rendering and interactive islands
View has separate server/static and browser rendering entry points. Static pages render to HTML without a browser runtime. Interactive components become client bundles only when explicitly declared as islands or marked with an Astro client directive.
This is an explicit boundary model. View does not infer which arbitrary closures can be removed from an interactive component, and it does not automatically extract event handlers from a full page into separate resumable fragments.
Server-only rendering
import { renderToString } from "@hedystia/view/server";
const html = renderToString(() => <main><h1>Static content</h1></main>);SSR evaluates the tree inside a disposable reactive owner. Cleanup runs after serialization, including on failures. Client onMount and onReady callbacks do not run during SSR. Load required data before rendering; synchronous rendering does not await promises or provide streaming Suspense.
The Vite plugin compiles selected JSX to @hedystia/view/static/jsx-runtime in server environments and the browser JSX runtime in client environments. The static runtime creates deferred server nodes without importing the DOM engine. include and exclude select JSX modules; another explicit JSX import-source pragma is respected.
Build a static View site
import { buildStatic } from "@hedystia/view/build";
import { Island } from "@hedystia/view/server";
import Counter from "./src/Counter";
await buildStatic({
root: process.cwd(),
outDir: "dist",
viewTransitions: true,
pages: [
{
path: "/",
title: "Welcome",
render: () => <main><h1>No JavaScript needed</h1></main>,
},
{
path: "/counter",
title: "Counter",
render: () => (
<main>
<h1>This heading stays server-only</h1>
<Island component={Counter} src="src/Counter.tsx" props={{ initial: 1 }} when="visible" />
</main>
),
},
],
});Run this build script in a TypeScript/JSX-capable build environment such as Bun, with jsxImportSource: "@hedystia/view". Interactive builds use the existing optional Vite build peer; install Vite as a development dependency when building without Astro.
pages[].render is synchronous. Fetch data before calling the builder, or capture already-loaded data in each page callback. Each page emits an HTML document at its URL directory's index.html. The builder validates traversal, duplicate page outputs and output directories and refuses symlinked output paths. It preserves unrelated existing output files rather than deleting the entire directory.
Pages without islands receive no scripts. Pages with islands receive a small bootstrap and lazy component chunks produced by Vite. Server-only page callbacks and static shell content are absent from those client chunks. Island CSS is built into a shared stylesheet for interactive pages. A base option such as /docs/ prefixes emitted asset URLs.
viewTransitions: true adds native cross-document transition CSS. It does not add a client router or JavaScript to a static page; unsupported browsers keep ordinary page navigation.
Activation and state
Standalone islands support when="load", "idle", "visible" and "media:(min-width: 800px)". Visibility and media activation fall back to immediate activation when their browser APIs are absent; idle activation uses a short timeout when requestIdleCallback is unavailable. Removing an island cancels queued activation and disposes its reactive owner; an import resolving after removal cannot mount it.
Island props must be finite, acyclic JSON values. Functions, undefined values, BigInts, dates, symbols, sparse arrays and class instances are rejected instead of being silently changed. Do not pass secrets to client props. src is a developer-controlled component module inside the project, not a user-supplied path.
Activation hydrates compatible server DOM in place. Existing elements, focus, selection and live input, checkbox, textarea and select state survive activation. The next reactive value update applies normally. Events, reactive text, attributes, styles and flow markers connect directly to the adopted native nodes.
Hydration prepares a temporary native DOM template and adopts server nodes once. There is no virtual DOM or update-time tree diff: subsequent signal updates write directly to DOM references. Incompatible markup is repaired locally; state inside a replaced subtree cannot be preserved. Render the same initial structure on the server and client, and use ref callbacks for imperative access to the adopted elements.
Keep standalone island boundaries separate; nested standalone boundaries are rejected during SSR. Use Astro slots for server-rendered content and nested Astro islands. Hydration preserves those externally owned slot nodes instead of rebuilding their descendants.
hydrateIslands(loaders, root?) accepts a container or an island element as its scope and returns a stop function. Leaving that scope or removing its container disposes the island and cancels pending activation. Calling stop releases every owner, even if one cleanup throws; cleanup failures are reported together as an AggregateError. Import or render failures leave uncommitted server HTML available and dispatch a bubbling view:island-error event with the error in detail. This is hydration, not resumability: component setup still executes when the island activates.
Astro
Astro remains responsible for page generation, script selection and page transitions. A View component without a client directive becomes static HTML; client:load, client:idle, client:visible, client:media and client:only opt into browser behavior. See the Astro integration.
Adding Astro ClientRouter, an authored script or an interactive island intentionally adds JavaScript. A zero-JavaScript claim applies to static pages without those features, not every page in a mixed site.
