API reference

Three entry points, and which one an import comes from tells you where the code runs. That is most of what there is to know about the surface.

@rshono/core pulls in no runtime machinery — importing it from server code is free. @rshono/core/server from a 'use client' module is a mistake: those run in the browser, where no request is bound. Read what you need on the server and pass it down as props.

These three are the whole public surface — the package's exports map lists only them, so there is no deeper path to import. Everything else is framework plumbing.

All three are ESM only: the map declares import and types conditions and no require one, so require('@rshono/core') is ERR_PACKAGE_PATH_NOT_EXPORTED. Use import, or await import() from CommonJS.

@rshono/core #

Functions #

See Routing and Configuration.

Types #

@rshono/core/server #

Server-only, and request-scoped. See Pages and Usage.

Functions #

publicUrl is the one export here meant for src/server.ts rather than a component: middleware is handed Hono's c and reads c.req.url, the address the server was reached on. Give Hono's own middleware the browser's origin instead — csrf({ origin: (origin, c) => origin === publicUrl(c).origin }). In a server component or an action, getRequestContext().url is the same value, cached per request.

redirect and notFound never return, so TypeScript narrows away the code after them and you don't need to return the call. Don't wrap either in a try/catch that swallows the signal.

Both have to be reached before the page shell is sent. A page streams, so the status line goes out as soon as the shell is ready and HTTP has no take-backs after that: called from a <Suspense> boundary that resolves later, neither can still be a 3xx or a 404. The response is committed as 200 text/html, a browser with JavaScript follows the signal through the payload, and a visitor without it stays on the fallback. Decide in middleware or in the page component body, above the boundary — rshono dev warns when a signal arrives too late.

import { getRequestContext, redirect } from '@rshono/core/server';

export default async function Dashboard() {
  const session = getRequestContext().cookies.get('session');
  if (!session) redirect('/login');
  return <Layout>Signed in as {session}</Layout>; // session is defined here
}

RequestContext #

What getRequestContext() returns, and the very same object a page gets as its ctx prop. Exported as a type only — one instance exists per request and application code never constructs it.

Reads are safe anywhere. Writes are not — see Writes happen before the render.

What this adds over Hono's own Context is a proxy-aware cached URL, an env that merges a platform's runtime bindings over process env, cookies without a second import, and writes that tell you when they cannot work. The long tail — executionCtx.waitUntil() and whatever Hono adds next — is ctx.hono.

Hono's response builders (redirect, notFound, json, text, html, body, status, header) are present as stubs that throw and name the right API, because a page returns JSX and the framework builds the response from it — reaching them through ctx.hono bypasses the error without making them work. They are permanent: the strike-through your editor draws over them comes from a @deprecated tag put there for the strike-through, not because they are going away.

ctx cannot be handed to a 'use client' component — it wraps the live request. Reading it on a render: 'static' page throws, because there is no request at build time.

Writes happen before the render #

A page streams. By the time its component runs the response head is already committed — on a soft navigation the flight response is built before the page's first line executes. A header set from there would land on a full page load and vanish on a soft navigation, so cookies.set, cookies.delete and setHeader throw inside a page render rather than work half the time.

Set them from a 'use server' action, which runs before the render:

'use server';
import { getRequestContext, redirect } from '@rshono/core/server';

export async function login(form: FormData) {
  const ctx = getRequestContext();
  ctx.cookies.set('session', await createSession(form), { httpOnly: true, sameSite: 'Lax', path: '/' });
  redirect('/dashboard');
}

Or from middleware, for anything belonging to the page rather than to one mutation — Cache-Control, X-Robots-Tag. Middleware and { type: 'endpoint' } routes run outside the request context, so getRequestContext() is not available in them; they are handed Hono's c instead, which is all they need:

// src/server.ts
server.use('/blog/*', async (c, next) => {
  await next();
  c.header('cache-control', 'public, max-age=600, s-maxage=3600');
});

Types #

An 'action' error is the one worth wiring up: React sends the client an opaque marker with no message in production, so a handler is the only place the real error is visible.

hono is the request's Hono context, for hono.var and hono.env — handed over because getRequestContext() is not reachable from the handler. waitUntil holds a serverless invocation open until the report has been sent; see error reporting for what it does per target.

@rshono/core/client #

Every export is itself a 'use client' module, so a server component can render AsyncBoundary directly. The hook needs a client component.

Hook #

url and params are computed on the server and travel in the flight payload, so they are right during SSR and update on every navigation. The fragment is the exception: a browser never sends #… to the server, so url.hash is read from the address bar after hydration and follows in-page links and Back/Forward with no request either way. In a server component, read the same data from getRequestContext().

'use client';
import { useNavigation } from '@rshono/core/client';

export function NextPage() {
  const { url, router } = useNavigation();
  const page = Number(url.searchParams.get('page') ?? '1');
  return (
    <button disabled={router.pending} onClick={() => router.push(`${url.pathname}?page=${page + 1}`)}>
      Next
    </button>
  );
}

router holds push(href), replace(href), back(), forward(), refresh() and the pending flag. Every one is a soft navigation: the page's flight payload is fetched and applied in place, so client state outside the changed subtree survives. Off-site hrefs, and a traversal that leaves the app, fall back to a full load.

Components #

loading on AsyncBoundary is required — a loading state is the reason to reach for it over CatchBoundary, so showing nothing while loading is an explicit loading={null}. error is optional: omit it and throws propagate to the next boundary out or the global error page. A redirect() is never absorbed by either boundary — it's navigation, not failure.

AsyncBoundary is scoped to the route: a soft navigation to a different pathname mounts the incoming route's boundary, so its loading state shows while the new data streams, and a same-page update (refresh(), a server action, a query-string change) keeps the content it has already revealed. That scope is a remount — client state and mount effects under the boundary do not survive a route change — so a section whose state must outlive navigation wants a bare CatchBoundary instead. CatchBoundary is not scoped — pass resetKeys={[url.pathname]} to clear its error state on navigation.

Types #