Hedystia 2.5 - Typed Routing, Smart Caching & Static Islands
Two new packages, static HTML without browser JavaScript, and interactive islands that preserve the server DOM.
The next minor release after Hedystia 2.4 is 2.5. This update brings typed application routing and shared query caching to View, adds standalone static-site builds, and improves Astro islands with native DOM hydration.
Released on 15 November 2026.
@hedystia/router: typed navigation and lazy routes
The new View router infers route paths, parameters, validated search values and loader data from route definitions. Nested layouts keep their reactive state while child routes change.
import { createRoute, createRouter } from "@hedystia/router";
const home = createRoute("/", {
component: () => <h1>Welcome to Hedystia</h1>,
});
const user = createRoute("/users/$id", {
loader: ({ params }) => ({ greeting: `Hello, ${params.id}!` }),
component: ({ data }) => <h1>{() => data().greeting}</h1>,
});
const router = createRouter({ routes: [home, user], viewTransitions: true });
const app = router.mount(document.getElementById("app")!);
await router.navigate({ to: "/users/$id", params: { id: "Ada" } });Its Vite plugin generates a typed route tree from files and splits route modules into lazy imports. Guards run in route order, then independent loaders and component imports can load concurrently. Navigation and preloading share cached requests, and superseded results cannot overwrite a newer destination. Cancelling navigation restores the last committed state and clears its busy indicator.
Browser navigation includes normal link handling, history, scroll restoration, accessible focus and native View Transitions with reduced-motion support. SSR uses an isolated router for each request.
This is a TanStack-inspired router for View. It is not a drop-in TanStack API; the router guide documents the supported route conventions and limits.
@hedystia/query: shared data without a third-party cache
Query builds on View's signals, resources and actions. Concurrent consumers of one key share a request while retaining independent cancellation. The last consumer can abort abandoned work, and late responses cannot replace newer cached results.
import { createQueryClient } from "@hedystia/query";
const queries = createQueryClient();
const greeting = await queries.fetchQuery(
["greeting", "Ada"],
async () => ({ message: "Hello, Ada!" }),
);
queries.invalidate(["greeting"]);Reactive queries track key changes, and successful mutations can invalidate matching key prefixes and refetch mounted consumers. Cache keys use structural JSON identity. Inactive entries are bounded without polling or timer-based garbage collection. Create a separate cache per SSR request when handling personalized data.
Router and Query use Hedystia runtime packages rather than external routing or caching libraries. Vite remains a build-tool peer for route generation and interactive static builds.
View: static HTML with JavaScript only for islands
View now separates static/server rendering from browser rendering. The Vite plugin selects the static JSX runtime for server builds, while buildStatic generates complete HTML pages and bundles only explicitly declared island modules.
import { buildStatic } from "@hedystia/view/build";
await buildStatic({
viewTransitions: true,
pages: [
{ path: "/", title: "Welcome", render: () => "Hello from Hedystia" },
],
});This page emits HTML with no browser scripts. Static cross-document View Transitions use native CSS. Interactive pages receive a bootstrap and lazy component chunks, while their server-only shell stays out of the client bundle.
Standalone islands support immediate, idle, visible and media-query activation. Their props must be finite, acyclic JSON values, and output paths are validated against traversal, duplicates and symlinks. Load page data before invoking the synchronous page renderer.
See static builds and islands for the complete interactive example.
Native DOM hydration, without a virtual DOM
Island activation now adopts compatible server elements instead of clearing and rebuilding the island. Focus, text selection and live form edits survive the first activation. Event handlers and reactive text, attributes, styles and flow markers connect directly to the adopted native nodes.
The initial hydration prepares temporary native DOM and adopts matching server nodes once. View retains no virtual DOM render tree and performs no tree diff on signal updates. Direct applications can also call hydrate(component, target) and dispose the returned owner through the same lifecycle as mount.
Initial server and client markup should agree. Incompatible parts are repaired locally, and a replaced subtree cannot retain its old DOM state. Use ref callbacks for imperative access to adopted nodes. Standalone island boundaries remain separate; nested standalone boundaries are rejected during SSR.
Astro: static by default, reactive when requested
View components without a client directive render as static HTML. Astro's client:load, client:idle, client:visible, client:media and client:only directives control browser activation.
---
import Counter from "../components/Counter.tsx";
---
<h1>This heading stays static</h1>
<Counter initial={1} client:visible />The first activation hydrates server DOM in place and preserves Astro slots and their nested islands. Persisted components with unchanged serialized props retain their existing reactive owner. Changed props replace that owner, and client:only mounts fresh content. Removal releases listeners, reactive work and pending activation.
Zero-JavaScript output applies to static pages without interactive islands, authored scripts or Astro's client router. Astro continues to own page navigation; use the View SPA router for a separate application root.
Compact type builds: no unused any placeholders
Generated AppRoutes declarations now include only schema sections that were actually supplied. A route with no schemas compiles to {method:"GET";path:"/health"} instead of carrying eight unused any properties. The in-memory generator, file writer and server buildTypes entry point share this format.
Defined schemas are preserved, including explicit any, unknown, null, undefined, void and never. Configured global request schemas and declared subscription messages are retained. Update the client alongside regenerated declarations: absent request sections stay absent, untyped responses and errors become unknown, and URL parameters without a schema accept string | number. Existing full declarations remain supported. Nested .group() and .use() calls now preserve constructor-level global header and body types in createClient<typeof app>, including required request options, typed path parameters and scoped inheritance.
Swagger also omits absent request sections and fabricated response content. It retains the required success response, explicit unconstrained schemas, global request schemas and required path parameters inferred from the URL.
Before and after
The same fixtures were measured against the previous generator at f2604fb and the compact generator, including the declaration header:
Generated .d.ts fixture | Before | After | Smaller by |
|---|---|---|---|
| Five HTTP routes | 783 B | 452 B | 42.27% |
| 1,000 routes without schemas | 118,952 B | 32,952 B | 72.30% |
| 1,000 routes with response schemas | 138,952 B | 65,952 B | 52.54% |
| One fully declared route | 181 B | 181 B | 0% |
For the five-route fixture, gzip size also drops from 257 B to 216 B. These are generated declaration-file measurements, not JavaScript bundle or runtime-performance claims. Fully declared routes retain every field. See the fixture definitions and reproduction steps.
Reliability across the ecosystem
This update also improves existing packages:
- View resources and actions: cancellation, stale-response protection, ownership cleanup and concurrent action state.
- HTTP client: request controls and clearer abort and error behavior.
- Node adapter and server: streaming, embedded-request fidelity and consistent global-header validation.
- Database and Better Auth: cache boundaries, pagination and adapter behavior.
- Validation and generated types: object inference, portable contract generation and compact declarations without absent-schema placeholders.
- Swagger and WebSocket: clearer contracts and native client controls.
Validation
The focused Router, Query, View and Astro suite passed 258 tests, including real static-site and Astro production builds. TypeScript contracts, linting and builds for all 13 buildable workspace packages passed as well.
The combined type, client, server and OpenAPI suite passed 160 focused tests, including ten regression cases for global schema inheritance through nested groups, direct scoped clients, prefixed and unprefixed mounts, all body-bearing HTTP methods, invalid inputs and compatibility outside global scopes. Compiler contracts also check required fields, path literals, local parameter types and response types.
The broader suite's local HTTP/WebSocket tests could not be validated in the restricted development environment because opening local ports returned EPERM. These focused results do not claim a completely passing network integration suite or a performance benchmark against other frameworks.
Try the new packages
Once the 2.5 release is published:
npm install @hedystia/view@^2.5.0 @hedystia/router@^2.5.0 @hedystia/query@^2.5.0For Astro applications:
npm install @hedystia/view@^2.5.0 @hedystia/astro@^2.5.0