Runtime configuration reference
Review page runtime, document, SSR handler, cache, and image options with their production defaults.
Configure shared route behavior through defineConfig
| API / option | Type | Default | Behavior |
|---|---|---|---|
ssr.getPageProps | () => record | unset | Adds application props to every page component. |
ssr.notFound | Component | src/pages/404 | Overrides the discovered not-found component. |
ssr.csrFallback | Child | function | empty route node | Server shell for CSR routes. |
ssr.csrActions | CsrActionsOptions | disabled | Routes browser form submissions to a configured action endpoint. |
ssr.middleware | PageMiddleware[] | [] | Runs before route and layout middleware. |
ssr.allowExternalRedirects | boolean | false | Permits normalized redirects to another origin. |
ssr.trustedHosts | string[] | local host policy | Allows inbound hosts for action-origin validation. |
ssr.i18n | I18nService | registered default | Resolves locale-aware paths, messages, and document direction. |
plugins | TavoPluginInput | [] | Accepts the public plugin array or { use, overrides } form and adds manifest-declared pages, middleware, capabilities, stores, head entries, endpoints, and build contributions. |
ssr.maxResolvedCacheEntries | number | 1024 | Bounds process-local resolved static route data. Zero disables reuse; invalid values throw TAVO_PAGES_001. |
ssr.instrumentation | TavoInstrumentation | unset | Receives isolated route lifecycle events. |
Document rendering options
| API / option | Type | Default | Behavior |
|---|---|---|---|
lang | string | "en" | HTML language unless the resolved i18n locale overrides it. |
title | string | "" | Escaped base document title; resolved route and component metadata can replace it. |
unsafeHeadHtml | string | "" | Trusted raw HTML inserted into the document head. Prefer escaped TSX metadata and use this explicit unsafe boundary only for reviewed markup. |
htmlAttributes / bodyAttributes / appAttributes | record | {} | Safe string, number, or boolean attributes. |
doctype | string | "<!doctype html>" | Document prefix. |
appContainerId | string | "app" | ID of the rendered application container. |
initialState | unknown | omitted | Serialized as escaped JSON when defined. |
stateScriptId | string | "__TAVO_STATE__" | ID of the JSON hydration script. |
nonce | string | unset | Applied to state, style, and deferred patch scripts where supported. |
beforeRender | () => void | unset | Re-establishes request context before render passes and stream chunks. |
styleRegistry | StyleRegistry | new registry | Collects SSR component styles with deduplication. |
SSR handler options
| API / option | Type | Default | Behavior |
|---|---|---|---|
modules | PageModules | required | Route module map used to create the pages runtime. |
canonicalOrigin | string | request host | Node-only public HTTP(S) origin behind TLS termination. Invalid origins throw TAVO_SSR_001. |
document | RenderDocumentOptions | {} | Base HTML shell and CSP settings. |
stream | boolean | false | Returns streamed HTML and enables progressive Deferred patches. |
images | ImageOptimizerOptions | optimizer defaults | Configures /_tavo/image processing. |
staticCache | SsrStaticCache | memory, 1024 entries | Rendered-response cache adapter. |
maxRequestBodyBytes | number | 10485760 | Node-only action body limit; excess input receives 413. |
Image optimizer defaults
| API / option | Type | Default | Behavior |
|---|---|---|---|
enabled | boolean | true | Enables the optimizer endpoint when image options are used. |
allowRemote | boolean | false | Remote sources remain blocked until explicitly enabled and allowlisted. |
publicDir | string | "public" | Root for absolute local image paths. |
quality | number | 75 | Default output quality. |
cacheMaxAge | seconds | 31536000 | Successful response cache lifetime. |
defaultFormat | ImageFormat | "webp" | Output format when negotiation does not select another configured format. |
sizes | number[] | 320, 640, 960, 1280, 1600 | Allowed responsive widths. |
timeoutMs | number | 5000 | Remote fetch timeout. |
maxBytes | number | 10485760 | Maximum source image size. |
memoryCacheMaxEntries | number | 128 | Process-local optimized image entries. |
maxConcurrentTransforms | number | 4 | Active transformations, clamped to at least one. |
maxPendingTransforms | number | 64 | Queued transformations before the endpoint returns 503. |
allowInsecureRemote | boolean | false | HTTP and private-network protections remain enabled by default. |
Look up exact public types
Follow linked API names to their canonical TypeScript declarations and package boundaries.