react-bun-ssrreact-bun-ssrBun-native SSR framework
APIAPI
Edit this page

API

react-bun-ssr/route API

Route module contracts, hooks, and helpers exposed to application routes.

apigenerated

Auto-generated from framework TypeScript exports. Do not edit manually.

Use this entrypoint inside route modules for hooks, route contract types, navigation helpers, and TanStack-style route error primitives. It is the package you import from day-to-day while building routes.

Examples

Loader + useLoaderData

import { useLoaderData, type Loader } from "react-bun-ssr/route";

export const loader: Loader = ({ params }) => {
  return { postId: params.id ?? "unknown" };
};

export default function PostPage() {
  const data = useLoaderData<{ postId: string }>();
  return <h1>Post {data.postId}</h1>;
}

Action + redirect helper

import { redirect } from "react-bun-ssr";
import type { Action } from "react-bun-ssr/route";

export const action: Action = async ({ formData }) => {
  const name = String(formData?.get("name") ?? "").trim();
  if (!name) return { error: "name is required" };
  return redirect("/docs/data/actions");
};

Route middleware

import type { Middleware } from "react-bun-ssr/route";

export const middleware: Middleware = async (ctx, next) => {
  if (!ctx.cookies.get("session")) {
    return new Response("Unauthorized", { status: 401 });
  }
  return next();
};

Deferred loader data

import { Suspense, use } from "react";
import { defer, useLoaderData, type Loader } from "react-bun-ssr/route";

export const loader: Loader = () => {
  return defer({
    title: "Dashboard",
    stats: Promise.resolve({ users: 42 }),
  });
};

function Stats(props: { stats: Promise<{ users: number }> }) {
  const value = use(props.stats);
  return <p>Users: {value.users}</p>;
}

export default function DashboardPage() {
  const data = useLoaderData<{ title: string; stats: Promise<{ users: number }> }>();
  return (
    <>
      <h1>{data.title}</h1>
      <Suspense fallback={<p>Loading stats…</p>}>
        <Stats stats={data.stats} />
      </Suspense>
    </>
  );
}

Exported symbols

Action

  • Kind: type
  • Source: framework/runtime/types.ts
  • Description: Route action function signature for handling mutating HTTP requests.
  • Learn more: Actions
export type Action = (ctx: ActionContext) => Promise<ActionResult> | ActionResult;

ActionContext

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Context object passed to actions with request metadata, parsed body helpers, and framework-normalized cookies exposed as Map<string, string> rather than Bun's CookieMap.
  • Learn more: Actions, Bun Runtime APIs, Cookies, HTTP server cookies
export interface ActionContext extends RequestContext {
  formData?: FormData;
  json?: unknown;
}

ActionResult

  • Kind: type
  • Source: framework/runtime/types.ts
  • Description: Allowed return union for actions, including data, redirects, and Response values.
  • Learn more: Actions
export type ActionResult = LoaderResult | RedirectResult;

defer

  • Kind: variable
  • Source: framework/runtime/helpers.ts
  • Description: Marks loader return data as deferred so promise-backed keys can stream progressively.
  • Learn more: Loaders, Streaming and Deferred
defer<T extends Record<string, unknown>>(data: T): DeferredLoaderResult<T>

DeferredLoaderResult

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Typed wrapper returned by defer() for loaders with immediate and deferred values.
  • Learn more: Loaders
export interface DeferredLoaderResult<T extends Record<string, unknown> = Record<string, unknown>> {
  __rbssrType: "defer";
  data: T;
}

DeferredToken

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Serialized payload token used internally to revive deferred values during hydration.
  • Learn more: Streaming and Deferred
export interface DeferredToken {
  __rbssrDeferred: string;
}

isRouteErrorResponse

  • Kind: function
  • Source: framework/runtime/route-errors.ts
  • Description: Type guard for narrowing unknown errors to framework caught route errors.
  • Learn more: Error Handling
isRouteErrorResponse(value: unknown): value is RouteErrorResponse

json

  • Kind: function
  • Source: framework/runtime/helpers.ts
  • Description: Creates a JSON Response with a default UTF-8 content-type.
  • Learn more: API Overview
json(data: unknown, init?: ResponseInit): Response
  • Kind: function
  • Source: framework/runtime/link.tsx
Link(props: LinkProps): Element

LinkProps

  • Kind: interface
  • Source: framework/runtime/link.tsx
export interface LinkProps
  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
  to: string;
  replace?: boolean;
  scroll?: boolean;
  prefetch?: "intent" | "none";
  onNavigate?: (info: RouterNavigateInfo) => void;
}

Loader

  • Kind: type
  • Source: framework/runtime/types.ts
  • Description: Route loader function signature for GET/HEAD data requests.
  • Learn more: Loaders
export type Loader = (ctx: LoaderContext) => Promise<LoaderResult> | LoaderResult;

LoaderContext

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Context object passed to loaders with URL, params, mutable locals, and framework-normalized cookies exposed as Map<string, string> rather than Bun's CookieMap.
  • Learn more: Loaders, Bun Runtime APIs, Cookies, HTTP server cookies
export interface LoaderContext extends RequestContext {}

LoaderResult

  • Kind: type
  • Source: framework/runtime/types.ts
  • Description: Allowed return union for loaders, including plain data, redirects, deferred data, and Response.
  • Learn more: Loaders
export type LoaderResult =
  | Response
  | RedirectResult
  | DeferredLoaderResult<Record<string, unknown>>
  | Record<string, unknown>
  | string
  | number
  | boolean
  | null;

Middleware

  • Kind: type
  • Source: framework/runtime/types.ts
  • Description: Middleware function contract executed around page and API handlers.
  • Learn more: Layouts and Groups
export type Middleware = (
  ctx: RequestContext,
  next: () => Promise<Response>,
) => Promise<Response> | Response;

notFound

  • Kind: function
  • Source: framework/runtime/route-errors.ts
  • Description: Throws a typed caught 404 route error for nearest not-found/catch boundary handling.
  • Learn more: Error Handling
notFound(data?: unknown): never

Outlet

  • Kind: function
  • Source: framework/runtime/tree.tsx
  • Description: Renders the next nested route element inside root/layout route modules.
  • Learn more: Layouts and Groups
Outlet(): ReactElement<unknown, string | JSXElementConstructor<any>> | null

Params

  • Kind: type
  • Source: framework/runtime/types.ts
  • Description: Dynamic URL params object shape exposed to loaders, actions, and hooks.
  • Learn more: File-Based Routing
export type Params = Record<string, string>;

redirect

  • Kind: function
  • Source: framework/runtime/helpers.ts
  • Description: Returns a framework redirect descriptor consumed by loader/action runtime flow.
  • Learn more: Actions
redirect(location: string, status?: 301 | 302 | 303 | 307 | 308 | undefined): RedirectResult

RedirectResult

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Redirect descriptor shape with destination and HTTP redirect status.
  • Learn more: Actions
export interface RedirectResult {
  type: "redirect";
  location: string;
  status?: 301 | 302 | 303 | 307 | 308;
}

RequestContext

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Base request context shared by middleware, loaders, actions, and API handlers, including framework-normalized cookies as Map<string, string> rather than Bun's CookieMap.
  • Learn more: Layouts and Groups, Bun Runtime APIs, Cookies, HTTP server cookies
export interface RequestContext {
  request: Request;
  url: URL;
  params: Params;
  cookies: Map<string, string>;
  locals: Record<string, unknown>;
}

RouteCatchContext

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Context passed to onCatch lifecycle hooks when a typed caught route error is handled.
  • Learn more: Error Handling
export interface RouteCatchContext extends Omit<RouteErrorContext, "error"> {
  error: RouteErrorResponse;
}

routeError

  • Kind: function
  • Source: framework/runtime/route-errors.ts
  • Description: Throws a typed caught route error with status/data for TanStack-style catch-boundary flows.
  • Learn more: Error Handling
routeError(status: number, data?: unknown, init?: { statusText?: string | undefined; headers?: HeadersInit | undefined; }): never

RouteErrorContext

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Context passed to onError lifecycle hooks for uncaught route failures.
  • Learn more: Error Handling
export interface RouteErrorContext {
  error: unknown;
  phase: RouteErrorPhase;
  routeId: string;
  request: Request;
  url: URL;
  params: Params;
  dev: boolean;
}

RouteErrorResponse

  • Kind: interface
  • Source: framework/runtime/types.ts
  • Description: Serializable caught route-error shape used by catch boundaries and transition payloads.
  • Learn more: Error Handling
export interface RouteErrorResponse {
  type: "route_error";
  status: number;
  statusText: string;
  data?: unknown;
  headers?: Record<string, string>;
}

Router

  • Kind: interface
  • Source: framework/runtime/router.ts
  • Description: Programmatic navigation contract returned by useRouter.
  • Learn more: Navigation
export interface Router {
  push(href: string, options?: RouterNavigateOptions): void;
  replace(href: string, options?: RouterNavigateOptions): void;
  prefetch(href: string): void;
  back(): void;
  forward(): void;
  refresh(): void;
  onNavigate(listener: RouterNavigateListener): void;
}

RouterNavigateInfo

  • Kind: interface
  • Source: framework/runtime/router.ts
  • Description: Navigation result payload delivered to Link.onNavigate, including the resolved nextUrl.
  • Learn more: Navigation
export interface RouterNavigateInfo {
  from: string;
  to: string;
  nextUrl: URL;
  status: number;
  kind: "page" | "not_found" | "catch" | "error";
  redirected: boolean;
  prefetched: boolean;
}

RouterNavigateListener

  • Kind: type
  • Source: framework/runtime/router.ts
  • Description: Listener signature accepted by router.onNavigate, receiving the resolved nextUrl after completed client-side navigations.
  • Learn more: Navigation
export type RouterNavigateListener = (nextUrl: URL) => void;

RouterNavigateOptions

  • Kind: interface
  • Source: framework/runtime/router.ts
  • Description: Options accepted by router.push() and router.replace().
  • Learn more: Navigation
export interface RouterNavigateOptions {
  scroll?: boolean;
}

useLoaderData

  • Kind: function
  • Source: framework/runtime/tree.tsx
  • Description: Reads loader data in route components, including deferred values as promises.
  • Learn more: Loaders
useLoaderData<T = unknown>(): T

useParams

  • Kind: function
  • Source: framework/runtime/tree.tsx
  • Description: Returns dynamic route params for the current matched route.
  • Learn more: File-Based Routing
useParams<T extends Params = Params>(): T

useRequestUrl

  • Kind: function
  • Source: framework/runtime/tree.tsx
  • Description: Returns the current request URL object in route components.
  • Learn more: Loaders
useRequestUrl(): URL

useRouteError

  • Kind: function
  • Source: framework/runtime/tree.tsx
  • Description: Reads error values inside ErrorBoundary route components.
  • Learn more: Error Handling
useRouteError(): unknown

useRouter

  • Kind: function
  • Source: framework/runtime/router.ts
  • Description: Returns a Next.js-style router object for programmatic client transitions and route-change listeners via router.onNavigate(...).
  • Learn more: Navigation
useRouter(): Router