Adapters
One core runs every library. An adapter, @hamur/adapter-<library>, renders pages and layouts with its library and hands you the hooks. Routing, loaders, head, state and the server are the same everywhere. Pick the library in hamur.config.ts with framework, or install one @hamur/adapter-<library> and Hamur detects it. One app uses one library.
| Library | Package | Install next to it | Files | Server rendering |
|---|---|---|---|---|
| React 19 | @hamur/adapter-react | react, react-dom | .tsx | streams |
| Vue 3.5 | @hamur/adapter-vue | vue | .vue | string, no streaming |
| Preact 11 | @hamur/adapter-preact | preact, preact-render-to-string | .tsx | string, no streaming |
| Svelte 5 | @hamur/adapter-svelte | svelte | .svelte | string, no streaming |
| Solid 1.9 | @hamur/adapter-solid | solid-js, babel-preset-solid, @babel/core, @babel/preset-typescript | .tsx | streams |
| html | @hamur/adapter-html | nothing | .ts | string; no client library |
Hamur has no dependencies of its own. The library and its compiler are peers that your app installs.
The same page in each library
A page that reads loader data, sets the title and keeps a counter in shared state. Every library has useData, useHead and useState; the form of the value differs.
React:
import { useData, useHead, useState } from "@hamur/adapter-react";
export default function Post() {
const { title } = useData<{ title: string }>();
const [likes, setLikes] = useState("likes", 0);
useHead({ title });
return (
<article>
<h1>{title}</h1>
<button type="button" onClick={() => setLikes(likes + 1)}>{likes} likes</button>
</article>
);
}
Preact:
import { useData, useHead, useState } from "@hamur/adapter-preact";
export default function Post() {
const { title } = useData<{ title: string }>();
const [likes, setLikes] = useState("likes", 0);
useHead({ title });
return (
<article>
<h1>{title}</h1>
<button type="button" onClick={() => setLikes(likes + 1)}>{likes} likes</button>
</article>
);
}
Solid reads values through accessors:
import { useData, useHead, useState } from "@hamur/adapter-solid";
export default function Post() {
const data = useData<{ title: string }>();
const [likes, setLikes] = useState("likes", 0);
useHead(() => ({ title: data().title }));
return (
<article>
<h1>{data().title}</h1>
<button type="button" onClick={() => setLikes(likes() + 1)}>{likes()} likes</button>
</article>
);
}
Vue uses <script setup lang="ts"> and refs:
<script setup lang="ts">
import { useData, useHead, useState } from "@hamur/adapter-vue";
const data = useData<{ title: string }>();
const likes = useState("likes", 0);
useHead(() => ({ title: data.value.title }));
</script>
<template>
<article>
<h1>{{ data.title }}</h1>
<button type="button" @click="likes++">{{ likes }} likes</button>
</article>
</template>
Svelte 5 uses <script lang="ts"> and objects with value:
<script lang="ts">
import { useData, useHead, useState } from "@hamur/adapter-svelte";
const data = useData<{ title: string }>();
const likes = useState("likes", 0);
useHead(() => ({ title: data.value.title }));
</script>
<article>
<h1>{data.value.title}</h1>
<button type="button" onclick={() => likes.value++}>{likes.value} likes</button>
</article>
Svelte reserves the $ prefix, so import $fetch under another name: import { $fetch as api } from "hamur/app".
html returns a string. It does not escape what a template literal interpolates, so an html page must escape every value it interpolates: route parameters, loader data and state. Only the HTML that Link and Outlet return goes in as it is.
import { useData, useHead, useState } from "@hamur/adapter-html";
const escape = (value: unknown) => String(value).replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
export default function Post(): string {
const { title } = useData<{ title: string }>();
const likes = useState("likes", 0);
useHead({ title });
return `<article>
<h1>${escape(title)}</h1>
<p>${escape(likes.value)} likes</p>
</article>`;
}
What differs
| React, Preact | Vue | Svelte | Solid | html | |
|---|---|---|---|---|---|
| Layout content | children | default slot | children snippet | props.children | children, a string |
Outlet | component | component | component | component | function returning a string |
useRoute() | the route | a reactive object | an object of getters | an accessor | the route of this render |
useData() | the data | ComputedRef | { value } | accessor | the data |
useState() | [value, set] | Ref | { value } | [accessor, set] | { value }, not reactive |
useHead() takes | an object | object, ref or getter | object or getter | object or accessor | an object |
useRouter() | yes | yes | yes | yes | yes |
ClientOnly | yes | yes | yes | yes | no |
Time | yes | yes | yes | yes | yes, a function returning a string |
LoadingIndicator, useLoadingIndicator() | yes | yes | yes | yes | yes, a function returning a string |
useLinkStatus() | { pending }, a boolean | { pending }, a ComputedRef | { pending }, a getter | { pending }, an accessor | no, the attribute only |
RouteAnnouncer, useRouteAnnouncer(), Announcer, useAnnouncer() | yes | yes | yes | yes | yes, functions returning a string |
useCookie, useRuntimeConfig, useAppConfig, useApp, useError, useNavigation, Link, ErrorBoundary and DefaultErrorPage exist in every library. useNavigation() tells you whether a navigation is idle or loading, and whether refresh() is revalidating. useAction(), useForm() and useFormStatus() run a handler from a component and a form; they exist in every library too. useRuntimeConfig() returns { public, app }: the public runtime config and the base URL and assets directory.
Link takes to (or href), replace, prefetch, prefetchOn, noPrefetch, viewTransition, pendingClass, external, noRel, prefetchedClass, scroll, prefetchDelay and onBeforeNavigate; other props go to the <a>. A link to another origin or with target="_blank" gets rel="noopener noreferrer" unless you give rel or noRel, and external renders a plain rel="external" link. Pass a function as children (a scoped slot with custom in Vue, a snippet with custom in Svelte) to render the link yourself from its LinkSlot. See the Link reference. app.link in the config sets the defaults of every Link (class names, the rel of an external link, the prefetch); defineLink(defaults) returns a Link with its own defaults, and useLink(to) returns the LinkSlot for a link component of your own. See defineLink and useLink.
While a navigation to a link is under way, the navigator sets aria-busy="true" on that link and adds its pendingClass (default router-link-pending), and takes both off when the navigation ends, is cancelled or is replaced. A link matches when its path and query equal the target of the navigation; the hash does not count, and a redirect moves the marks to the links of the new target. An aria-busy or a class you set yourself is left alone. This works in every library, html included, and for a hand-written <a data-hamur-pending-class="busy">. Inside a Link's children, useLinkStatus() returns { pending } for a spinner next to the text: const { pending } = useLinkStatus() in React and Preact, pending.value in Vue, pending() in Solid, status.pending in Svelte. Outside a Link it is always false.
Time prints a date the same on the server and in the browser: <Time datetime={post.publishedAt} dateStyle="long" /> renders <time datetime="..." data-locale="..." data-time-zone="...">. The server formats with locale, else the @hamur/i18n locale, else the first Accept-Language tag, else en, in timeZone, else i18n.timeZone, else UTC, and the browser starts from the same values, so there is no hydration warning. relative prints "2 minutes ago" and refreshes it every relativeInterval milliseconds (60000) while the component is mounted; the html adapter's Time(props) returns a string and does not refresh it.
LoadingIndicator draws a thin bar fixed at the top of the page while a navigation or a form submission runs: <LoadingIndicator /> once, in the app's root layout. It shows nothing for a navigation shorter than throttle (200 ms), fills toward 100 over duration (2000 ms), holds 100 for 500 ms when the navigation ends and fades. It is aria-hidden, and it follows useNavigation().state, so refresh() does not show it. The server writes the element without a style attribute, so a strict style-src is enough; the browser sets the styles through element.style. useLoadingIndicator() gives { progress, isLoading, error } (values in React and Preact, refs in Vue, getters in Svelte, accessors in Solid) and start(), finish({ force, error }), set(n) and clear() to drive it yourself. There is one bar state per app: the first LoadingIndicator or useLoadingIndicator(options) sets the options.
RouteAnnouncer and Announcer render the live regions of Announcing a page inside your app, on the server too, so a screen reader finds them before the first message. useRouteAnnouncer() and useAnnouncer() give { message, politeness } (values in React and Preact, refs in Vue, getters in Svelte and html, accessors in Solid) and set(message, politeness?), polite(message) and assertive(message). There is one announcer per app, and on the server the calls do nothing.
Page meta
meta is a named export of the page module. In React, Preact, Solid and html it is export const meta in the page file. In Vue it goes in a plain <script lang="ts"> block next to <script setup>; in Svelte it goes in <script module>.
<script lang="ts">
import type { PageMeta } from "hamur/app";
export const meta = { layout: "admin", middleware: ["auth"] } satisfies PageMeta;
</script>
<script setup lang="ts">
import { useHead } from "@hamur/adapter-vue";
useHead({ title: "Admin" });
</script>
<template>
<h1>Admin</h1>
</template>
<script module lang="ts">
import type { PageMeta } from "hamur/app";
export const meta = { layout: "admin", middleware: ["auth"] } satisfies PageMeta;
</script>
<script lang="ts">
import { useHead } from "@hamur/adapter-svelte";
useHead({ title: "Admin" });
</script>
<h1>Admin</h1>
Page and layout transitions
app.pageTransition and app.layoutTransition (see Configuration) work the same in every library: the core finds the elements the navigation added and removed under the app root, puts a clone of each leaving element where it was, and adds the <name>-enter-* and <name>-leave-* classes. Nothing is written per library: a page or layout component needs no Transition and no wrapper. The page must render an element and unmount the old one: the same page component with the same meta.key (a /blog/:slug page going from one slug to another) patches its elements in place, so it neither enters nor leaves. In hamur dev the console says pageTransition on /blog/b needs an element: the update added or removed none once per route; give the page a meta.key that changes with the param to animate it. In html the renders carry <!--hamur-page--> and <!--hamur-layout--> comments around the page and the layout, which update needs because it rewrites the whole root; leave them where they are if you build the HTML yourself.
Transitions: names and presets
hamur/transitions.css holds two ready animations, fade and slide. Import it once, for instance in the root layout:
import "hamur/transitions.css";
For a page or layout transition set the name in the config, pageTransition: { name: "fade" }; the file defines the classes the core adds (fade-enter-active, fade-leave-to, and so on). For a view transition turn it on with viewTransition: true; the root fades, and viewTransition: { types: ["slide"] } slides it, the other way on a back navigation. All of it is off under prefers-reduced-motion: reduce.
transitionName(name) names one element so a view transition moves it from the old page to the new one. It returns what the library spreads onto an element:
| React, Preact | Vue | Solid | Svelte, html |
|---|---|---|---|
<img {...transitionName("hero")} /> | <img v-bind="transitionName('hero')" /> | <img {...transitionName("hero")} /> | <img style={transitionName("hero")} /> (Svelte), style="${transitionName("hero")}" (html) |
Give the element the same name on both pages. A name that is not a CSS identifier throws a TypeError. Without View Transitions in the browser the page transition runs, and the named elements just swap.
Data in components
useFetch and useAsyncData return { data, error, status, refresh } in every library, in the form of the library's values: plain values in React and Preact, ComputedRefs in Vue, accessors in Solid, getters in Svelte, and plain values with subscribe in html. watch is a list of values in React and Preact, watch sources in Vue, and accessors or getters in Solid and Svelte; html has no watch.
The server waits for the data in every library, as the table in Data says, so it is in the first HTML.
Error boundaries
ErrorBoundary catches render errors, in the browser and on the server, and gives its fallback { error, reset }. React, Preact and Solid take a fallback function. Vue takes a fallback function or a #fallback slot. Svelte takes a fallback snippet. html takes children and fallback functions that return strings.