Complete API reference

#Package entry points

• Runtime boundary: Keep server runtime imports out of browser-reachable components.
• Type-only imports: Type-only imports do not create runtime dependencies.

#Route exports

• Implicit methods: A page has an implicit GET when no explicit GET exists. Goribu derives HEAD and OPTIONS when needed.
• Special routes: _404, _500, and _middleware have special roles under routes.
• Document location: The optional app-wide Document lives in src/setup/_document with a supported JavaScript or TypeScript extension.
• Middleware export: A middleware default export is one function or an array. Return nothing to continue or a response result to stop.

#Request

Handlers and middleware share one request object.

Middleware may attach its own fields to req, such as req.user, for later middleware and the handler; declare them for TypeScript on AppRequestFields. See Request handlers.

• JSON bodies: JSON bodies must have an object root.
• Form bodies: URL-encoded and multipart forms return field objects. Uploads are File values, repeated names become arrays, and missing fields are absent.
• Text bodies: Text returns a string.
• Unsupported bodies: Empty or unsupported bodies return an empty object.
• Parse failures: Malformed supported bodies produce 400. See Request handlers.

import type { Handler } from "goribu/server";

export const POST: Handler = async (req, res) => {
  const { name } = await req.body() as Record<string, unknown>;
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ name: name.trim() });
};

export const POST = async (req, res) => {
  const { name } = await req.body();
  if (typeof name !== "string" || !name.trim()) {
    return res.invalid({ name: "Enter your name." });
  }
  return res.json({ name: name.trim() });
};

#Response

Return one terminal result from every handler. status() and headers() configure the builder and return it for chaining.

• Return values: Handlers cannot return raw Response objects or JSX. Use stream() for binary or streamed bodies.
• Streamed routes: A streamed route is never prerendered. Client navigation to it loads the document.
• Bodyless statuses: Bodyless statuses reject a body.
• Form outcomes: Enhanced Form outcomes are JSON, invalid, redirect, and same-page render. See Forms.

#Cookies

• Cookie options: domain, path, expires (Date), maxAge (seconds), httpOnly, secure, and sameSite.
• SameSite values: sameSite accepts Lax, Strict, or None, also lowercase.
• Security defaults: Cookie security options have no implicit defaults.
• Cookie encoding: Encode structured or Unicode data before setting a cookie.

#Navigation

• Active matching: NavLink matches pathname boundaries, ignoring query and hash. Root is exact-only.
• Native links: Link enhancement preserves native behavior for external links, downloads, modifier clicks, and same-document anchors. See Links & navigation.
• Static navigation: Production static navigation and prefetch reuse saved build-time data without invoking the Worker.
• Current static URL: Clicking the exact current URL scrolls a confirmed static page without fetching or rerendering.
• Current dynamic URL: Clicking the exact current URL of a dynamic page fetches fresh data.
• Current-URL history: Neither static nor dynamic navigation to the exact current URL adds a history entry.

import { NavLink } from "goribu";

export default function SettingsLink() {
  return (
    <NavLink
      href="/settings"
      end
      className={({ isActive }) => isActive ? "active" : undefined}
    >
      Settings
    </NavLink>
  );
}

import { NavLink } from "goribu";

export default function SettingsLink() {
  return (
    <NavLink
      href="/settings"
      end
      className={({ isActive }) => isActive ? "active" : undefined}
    >
      Settings
    </NavLink>
  );
}

#Form

Import Form from goribu. It accepts ordinary form props except that Goribu owns encoding and defines its method/action behavior.

• Initial Form state: { pending: false, errors: null, data: null }.
• Form errors: errors is an object of message strings.
• Result callback: onResult receives { ok: true, data?, response? } or { ok: false, errors, data?, response? }.
• Encoding ownership: Do not pass encType to Form.
• Hydration: GET/POST work natively. PUT/PATCH/DELETE require hydration.
• Submitter overrides: A submitter's formMethod supports only GET/POST. Declare extended methods on Form itself. See Forms.

#Metadata

meta is a RouteMetadata object or synchronous function receiving { props, url }, where url is a URL object.

• Optional link fields: as, type, media, sizes, hrefLang, crossOrigin, referrerPolicy, fetchPriority, imageSrcSet, imageSizes, and color are all strings.
• Rejected metadata: Unknown fields, event handlers, async results, and duplicate canonical/description representations are rejected.

#Document and browser entry

DocumentProps contains { children, head, nonce? }. Keep children under #root and head inside the document head.

• Stylesheet: Stylesheet() renders the current graph's styles and takes no public props.
• Client entry: ClientEntry({ src, nonce? }) renders the browser entry. src is the development fallback; production resolves the built asset.
• Custom Document: Keep one Stylesheet and one ClientEntry in a custom Document.
• Browser bootstrap: Import goribu/client once to hydrate and install navigation and Forms.
• Browser environment: Only import.meta.env.PUBLIC_* values are browser-visible. See Rendering.

#D1

Use the req.d1 tagged template in handlers or middleware. Values become parameters. A statement is lazy until a terminal runs.

• Tagged D1 values: Strings, numbers, booleans, null, ArrayBuffer, ArrayBufferView, and non-empty arrays of those scalars are supported.
• Unsafe parameters: unsafe() parameters are a flat scalar array.
• Rejected D1 values: Undefined, dates, objects, nested/empty arrays, functions, symbols, and bigints are rejected.
• Default consistency: Default D1 queries use the visitor session when replication is enabled.
• Facade restrictions: Fresh/public cannot be chained. Atomic belongs to the default facade.
• Batch session: A batch rebinds passed statements to its own session. See D1.

// Inside a handler; D1 and the posts table must exist.
type Post = { id: number; title: string };

const posts = await req.d1<Post>`
  SELECT id, title FROM posts ORDER BY id DESC
`.all();

const posts = await req.d1`
  SELECT id, title FROM posts ORDER BY id DESC
`.all();

#KV

• Default KV reads: Reads return text or null. JSON is parsed only when requested.
• Metadata result: Metadata reads return { value, metadata, cacheStatus }. Missing value and metadata are null.
• List result: Lists return keys, list_complete, and an optional cursor.
• KV completion: Await all operations.
• KV keys: Keys for get/put/delete are non-empty strings.
• JSON writes: JSON writes need explicit stringification.
• Unsupported KV calls: There is no bulk-get array, string shorthand for options, or separate getWithMetadata method.
• KV consistency: KV is eventually consistent, including cached misses. See KV store.

#Cache

Available in Goribu 0.9.0. req.cache needs no binding or configuration. The GoribuCache type is exported from goribu/server.

• Cache keys: Literal strings starting with /, scoped by origin and execution location.
• Cache failures: Invalid inputs reject. Platform failures warn and become misses or skipped operations.
• Pre-rendering: Pre-rendering bypasses the cache.
• Background writes: Use req.waitUntil explicitly. See Cache for freshness, Smart Placement, and deployment support.

#Configuration

defineConfig(config) validates and returns a frozen configuration. The fields are name, compatibilityDate, optional compatibilityFlags, database, kv, r2, domain, workersDev, and responseHeaders.

Available in Goribu 0.9.0. Optional top-level domain connects one application hostname during deployment. Available in Goribu 0.9.2: workersDev: false turns off the workers.dev address and requires domain.

• D1 declaration: { type: "d1", name, replication? }.
• KV declaration: { name }.
• Header callback: Receives { request, env, mode, nonce } and synchronously returns a plain object of strings or string arrays. See Configuration for defaults, allowed names, environment files, and header restrictions.

#CLI

Run from the application directory. The app scripts wrap the installed Goribu CLI.

• Production targets: Migrate, status, down, and d1 accept --remote.
• Development arguments: Dev accepts only --port and --host.
• Argument-free commands: Build, check, deploy, tail, and cloudflare-login take no arguments.
• CLI failures: Failures exit non-zero. Recognized Goribu failures print their repair message without a stack trace.
• Type checking: pnpm typecheck is the TypeScript starter's separate tsc --noEmit script.
• Scaffolding: pnpm create goribu@latest <name> creates an app.
• Scaffolder options: --js, --help, and --goribu-tarball <path> for a matching local framework archive.
• Scaffolder scope: Scaffolding never installs, authenticates, or deploys for you.

#TypeScript

Use import type. Types annotate behavior; they do not validate request input or stored JSON.

• Handler types: Handler<Props, Env, Params> and Middleware<Env>.
• UI types: Meta<Props> and Form<Data>.
• Data types: req.d1<Row> and req.kv.get<Value>(key, { type: "json" }).
• Body validation: Request body values still need narrowing and validation.

#Low-level app creation

createApp(options) from goribu/server returns a Worker app with fetch(request, env, ctx): Promise<Response>. Normal applications use goribu() in Vite; the build supplies the route graph and calls this API for them.

• Required app options: manifest, modules, and errorPages.
• Optional app options: documentId, middlewareByRoute, mode, clientAssetManifest, clientAssetBase, and applicationConfig.
• Compiled inputs: App options describe compiled routes, error pages, assets, and validated config. They are not additional goribu.config.js fields.