API Reference

Backend (@btst/stack/api)

createBackendStack

BackendPlugin

BackendStackConfig

BackendStack

toNodeHandler

Re-exported from better-call/node. Converts a BTST handler to a Node.js compatible request handler.

Client (@btst/stack/client)

createClientStack

Configure the shared API location, site location, React Query client, and optional server request headers once. Runtime-independent client plugin definitions receive the resolved values when the stack is created.

const clientStack = createClientStack({
  api: {
    baseURL: "https://app.example.com",
    basePath: "/api/data",
    headers: requestHeaders, // server/request stacks only
  },
  site: {
    baseURL: "https://app.example.com",
    basePath: "/pages",
  },
  queryClient,
  plugins: {
    example: exampleClientPlugin(),
  },
})

Use endpoints.<plugin>.api or endpoints.<plugin>.site only when one plugin implements its BTST contract at another endpoint. A path-only API replacement inherits the top-level origin and server request headers. Supplying another origin requires its own basePath and does not inherit request headers. An empty plugin endpoint block inherits both top-level locations unchanged.

Headers deliberately exposed to browser code use the explicit browserHeaders field and appear under the same name in the provider projection. Cookie, authorization, proxy-authorization, and set-cookie values are rejected there; keep request credentials in server-only api.headers. Cross-origin browser credentials must also be explicit.

The returned provider value contains API/site/query information for browser consumers, but never top-level server request headers. Browser-created stacks reject api.headers rather than silently serializing them.

ResolvedClientStackConfig

ResolvedClientPluginRuntime

ClientPluginDefinition

A definition may declare providerConfig when its browser components need a small subset of plugin factory values. The resolved provider projection exposes the exact inferred shape as plugins.<id>.config. These values must be safe to expose in the browser: do not include secrets, request headers, server-only objects, or the shared API/site/QueryClient runtime.

ClientProviderPluginRuntime

config is present only for definitions that project browser-safe factory values through providerConfig; it is not a provider override and applications do not configure it on StackProvider.

ClientPlugin

ClientStack

ResolvedClientStack

SitemapEntry

Sitemap

An array of SitemapEntry objects.

type Sitemap = Array<SitemapEntry>;

sitemapEntryToXmlString

metaElementsToObject

normalizePath

Client Components (@btst/stack/client/components)

RouteWithComponents

RouteRenderer

ComposedRoute

FallbackProps

ErrorBoundary

Context (@btst/stack/context)

StackProvider

useStack

usePluginOverrides

usePluginSiteNavigation

Use this client hook for links and programmatic navigation owned by a plugin. Pass the same literal plugin ID used in createClientStack({ plugins }); the hook reads that plugin's resolved site endpoint, including any endpoints.<pluginId>.site override.

resolve(...segments) returns the canonical path, the rendered href, and whether the destination is cross-origin. Same-origin links use the configured router and a path-only href. Cross-origin links use an absolute href that is stable during SSR and hydration, and navigate() performs a full-page browser navigation. Without a router adapter, navigate() also falls back to full-page navigation. Root-mounted sites are normalized to one leading slash.

"use client"

import { usePluginSiteNavigation } from "@btst/stack/context"

const TODOS_PLUGIN_ID = "todos" as const

export function AddTodoLink() {
  const { Link, resolve } = usePluginSiteNavigation(TODOS_PLUGIN_ID)
  return <Link href={resolve("todos", "add").href}>Add Todo</Link>
}

useBasePath

joinBasePath

Join the resolved site base path to a plugin route before passing it to a link or router navigation function. This produces one path separator even when the configured base path is /.

Prefer usePluginSiteNavigation(pluginId) inside plugin browser components so per-plugin site endpoint overrides are honored. Keep joinBasePath for non-hook or server-side path composition when you already have the correct resolved base path.

useNotify

Notifications are configured via the notify prop on StackProvider. Without an override, useNotify() routes to sonner toasts.

useTranslate

Without an i18n provider, useTranslate() returns the English default with {{param}} interpolation.

useListState

URL-synced list state (filters, tabs, pagination) via the router's getSearchParams / setSearchParams contract. Import useListState from the client-only @btst/stack/client/hooks entry. Server-safe parsing and serialization helpers remain available from @btst/stack/client.

For SSR loaders, read initial state with parseListStateFromSearchParams(namespace, schema, requestSearchParams).