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.

@rshono/core #

Functions #

See Routing and Configuration.

Types #

@rshono/core/server #

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

Functions #

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.

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.

That is the whole wrapper. What it adds over Hono's own Context is a proxy-aware cached URL, an env that merges runtime bindings over process env, and cookies without a second import. Anything else is ctx.raw — ctx.raw.req for the parsed request, ctx.raw.header(name, value) to set a response header. Route params come to a page as its params prop.

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.

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.

@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. 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), refresh() and the pending flag. All three are soft navigations: the new page's flight payload is fetched and applied in place, so client state outside the changed subtree survives. Off-site hrefs fall back to a full load. History traversal is history.back() and history.forward() — the router wrapped them once and added nothing, so it no longer does.

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.

Types #