#Config Reference
Every krate.config.ts key, with types and defaults.
The complete krate.config.ts surface, type-checked with defineConfig.
#Build
entry: "src/index.tsx", // Entry point (default: src/index.tsx)
outDir: "dist", // Output directory (default: dist)
pagesDir: "src/pages", // Pages directory (default: src/pages)
publicDir: "public", // Static assets directory (default: public)
spa: true, // Client-side router (default: true; false omits it)
Set spa: false to use normal full-page navigation and omit the SPA router,
prefetch, and history code from the shared runtime. navigate() still works and
performs a full navigation.
The shared runtime chunk is assembled per site in production builds: the core
(signals, DOM bindings, events) plus the router, and only those optional pieces
(list rendering, class helpers such as cn/twMerge, server action forms,
error boundaries and class components) that the site's pages reference. A
counter page ships about 25 KB of gzipped runtime JS (about 17 KB with
spa: false); each extra piece adds between 2 and 5 KB gzipped. krate dev
always serves the full runtime.
#Site metadata
site is the canonical site metadata; seo is a deprecated alias (a config
using both gets a warning and site wins per field). The sitemap/feed/llms/robots
plugins inherit these values.
site: {
url: "https://example.com", // where the site lives; a path here is the base path
name: "My Site",
description: "Default meta description",
image: "https://example.com/og.png",
titleTemplate: "%s | My Site",
twitter: "mysite", // twitter:site handle (@ optional)
themeColor: "#0b1020",
locale: "en", // <html lang> + og:locale
htmlAttributes: { class: "dark" }, // attributes of every page's <html>
bodyAttributes: { class: "font-sans" }, // attributes of every page's <body>
},htmlAttributes and bodyAttributes take strings, numbers and booleans (true
writes a bare attribute, false and null drop it). Values are escaped. A page or
a layout can add to them or replace single attributes with <html> and <body>
elements inside <Head>; see Document attributes.
defineConfig also accepts a function invoked with the build context, and
--mode <name> selects the mode (and .env.<mode> files):
export default defineConfig(({ command, mode, isDev }) => ({
site: { url: isDev ? "http://localhost:3000" : "https://example.com" },
}));Config files may be krate.config.ts, .js, .mjs, or .json. A .json
config cannot call the factory helpers (docs(), defineContent); write the
equivalent plain objects, or use a .ts/.js file.
titleTemplate applies only to bare page titles; a title that already carries a
site/section suffix (e.g. docs pages: Guide - Site Docs) is left unchanged so
the suffix is not duplicated.
Builds write a JSON Schema to .krate/config.schema.json for editor/tooling
completion (it is a local build artifact, not served with the site). A .json
config can reference it with "$schema": "./.krate/config.schema.json".
#Minification
minify: true, // Enable all minification (default: true)
minifyHTML: false, // HTML minification (inherits minify); text keeps its white space inside <pre> and where CSS sets white-space to pre, pre-wrap, pre-line or break-spaces
minifyCSS: false, // CSS minification (inherits minify)
minifyJS: false, // JS minification (inherits minify)
Minification only controls whitespace/size optimizations. Duplicate declarations within a rule (including same-name CSS custom properties) are always folded to the last value, whether or not minification is enabled - formatting is preserved when it is off.
#CSS
Each page gets one stylesheet (identical sheets share one hashed file), @imports are inlined,
and the merged stylesheet is minified when minifyCSS (or minify) is on.
Tailwind generates CSS only for classes detected in the scanned sources, so
unused utility classes never ship. There are no per-feature CSS config toggles.
@import (and url()) may read .css files from the project root, from
packages in node_modules (including pnpm workspace links whose target is a
sibling package), and from the enclosing monorepo workspace root (the nearest
parent with pnpm-workspace.yaml or a package.json with workspaces). A
shared token file such as @import "../../packages/tokens/tokens.css" or
@import "@acme/tokens/tokens.css" therefore works in a monorepo. Anything
else is refused with a warning naming the resolved path; list extra
directories explicitly:
cssImportRoots: ["../shared-styles"], // relative to the project root, or absolute
In krate dev, edits to such files outside the project root rebuild the pages
that import them (the file's directory is watched, not its subdirectories).
#Features
sourcemap: false, // Write per-page sourcemaps (index.<hash>.js.map)
React syntax is always transpiled to Krate signals and effects; no config is required.
#Precompression
compress: { // opt-in; also enabled by `krate build --precompress`
brotli: true, // write .br siblings
gzip: true, // write .gz siblings
}Build-time precompression writes .br/.gz siblings beside compressible assets
(HTML, CSS, JS, JSON, SVG, XML, ...). krate serve negotiates them per request
by Accept-Encoding (brotli > gzip > raw) and always sends
Vary: Accept-Encoding, falling back to on-the-fly gzip for dynamic responses. Siblings are used only
by the static file handler, after middleware, redirects and the SSR/ISR
decision, so they never bypass them and are never used for the HTML of a
request-time page. Range requests are answered uncompressed.
Static hosts such as Cloudflare Pages and Netlify serve the siblings
automatically. Assets under 1 KB, already-compressed formats (images, fonts,
wasm), and internal .krate/ build artifacts are skipped.
#Head & scripts
head: {
meta: [{ name: "theme-color", content: "#0b1020" }],
links: [{ rel: "preconnect", href: "https://cdn.example" }],
scripts: [
{ src: "/analytics.js", defer: true },
// { content: "/* inline */", module: true },
],
// raw: ['<meta ...>'],
},
// concise raw form:
// head: ['<link rel="preconnect" href="https://cdn.example">'],
head injects into every page's <head> before CSP hashing. scripts supports
src/content, async/defer, type/module, and attrs. Use it for
analytics, fonts, and other site-wide tags.
#Response headers & security
These apply to
krate serveonly. Static hosts (Netlify, Cloudflare, Vercel) ignore them; configure headers there instead.
headers applies custom response headers; security overrides the defaults
("off" disables a header).
headers: [
{ source: "/assets/*", headers: { "Cache-Control": "public, max-age=31536000, immutable" } },
],
security: {
frameOptions: "SAMEORIGIN",
referrerPolicy: "strict-origin-when-cross-origin",
permissionsPolicy: "camera=(), microphone=()",
hsts: "max-age=31536000; includeSubDomains",
},krate deploy writes explicit headers rules to _headers (Netlify /
Cloudflare Pages) and to vercel.json (Vercel). Only explicit rules are emitted;
security defaults stay serve-only so static-host behavior is not changed
implicitly.
#Auth
auth configures authentication from
@krate/auth. It holds the parts that are data. Callbacks, the database
adapter and credentials logic stay in defineAuth(), and the code wins when
both set an option.
auth: {
providers: [{ id: "github" }, { id: "okta", name: "Company SSO" }],
session: { strategy: "jwt", maxAge: 60 * 60 * 24 * 7 },
pages: { signIn: "/login" },
adapter: { dialect: "sqlite" },
twoFactor: { enabled: true, issuer: "My App" },
passkeys: { enabled: true, rpName: "My App" },
protect: [{ source: "/dashboard" }, { source: "/admin", roles: ["admin"], status: 404 }],
},| Key | Type | Default |
|---|---|---|
enabled |
boolean |
on when anything is configured |
basePath |
string |
"/api/auth" |
trustHost |
boolean |
false |
debug |
boolean |
false |
providers |
{ id, type?, name?, enabled?, options? }[] |
[] |
session |
{ strategy, maxAge, updateAge } |
jwt, 30 days, 1 day |
pages |
{ signIn, signOut, error, verifyRequest, newUser, twoFactor } |
built-in pages |
cookies |
{ prefix, secure, sameSite, domain } |
krate-auth, secure on https, lax |
adapter |
{ dialect, tables } |
none |
twoFactor |
{ enabled, required, issuer, digits, period, algorithm, window, backupCodes } |
off |
passkeys |
{ enabled, allowSignUp, rpName, rpId, origins, userVerification, residentKey, attestation, timeout } |
off |
protect |
{ source, roles?, redirect?, status? }[] |
[] |
rateLimit |
{ enabled, max, window } |
20 per 60 seconds |
redirects |
{ signedIn, signedOut, allowed } |
none |
linking |
{ automatic } |
false |
Provider options may not contain secrets (clientSecret, secret,
password, apiKey, privateKey, token): the build fails and points to the
AUTH_<PROVIDER>_SECRET environment variable instead. session.strategy: "database", twoFactor.enabled and passkeys.enabled require
adapter.dialect. An unknown provider id is a warning unless type is
"oauth" or "oidc".
#Images
images: {
breakpoints: [640, 1080, 1920],
quality: 80,
sizes: "(max-width: 768px) 100vw, 50vw",
placeholder: true,
formats: ["webp", "original"],
remotePatterns: [{ hostname: "images.example.com" }],
// unoptimized: true,
},Controls the <Image> pipeline: generated widths, encode quality, default
sizes, blur placeholder, output formats, and allowed remote hosts. A remote
src not listed in remotePatterns is a build error; unoptimized passes the
original image through.
remotePatterns hostnames support *.example.com (one label) and
**.example.com (any depth); pathname supports * (one segment) and **
(any depth), e.g. "/images/**". Output formats are WebP and the original
format; AVIF is not supported (it needs a separate encoder).
#Dev server
devServer: {
port: 3000,
host: "127.0.0.1", // bind address (default loopback; "0.0.0.0" exposes the dev server on the network)
open: true,
overlay: true, // show the dev error overlay (default true)
toolbar: true, // show the dev toolbar (default true)
editor: "code", // editor command for "open in editor" (default "code" = VS Code)
proxy: { "/api": "http://localhost:8080" }, // forward matching paths during dev
}krate dev binds to loopback by default, and its /__krate/* endpoints only
accept requests whose Host and Origin are the dev server itself (this blocks
DNS-rebinding and cross-site calls to /__krate/open). Set devServer.host
(or server.host) to expose it, for example "0.0.0.0" to test on a phone; the
Host check is then relaxed to the configured address.
port is the dev server port and takes precedence over server.port in
krate dev (krate serve uses server.port, then devServer.port). If the
port is busy, dev moves to the next free one and says so; serve fails with a
hint instead.
editor is the editor command (for example "code", "cursor", "idea",
"subl", "vim" or "zed") and may include flags. Krate adds the right
line-number syntax for each (-g file:line for VS Code family editors,
--line N file for JetBrains IDEs, file:line for Sublime and Zed, +N file
for vim); an unknown editor is opened with the plain file path. It is used by the
overlay's location links and by GET /__krate/open. proxy forwards matching
path prefixes to a backend only in dev (longest prefix wins), so you can run a
separate backend without CORS. In development, the JavaScript generated for each
page is unminified (with component comments) so devtools are readable; the shared
@krate/runtime chunk is the prebuilt, already minified runtime in both modes.
Production output minifies the page scripts too.
#Logs
logs: {
enabled: true, // save each run's console output (default false)
dir: ".krate/logs", // relative to the project, must stay inside it
keep: 20, // log files to keep, oldest removed first (negative keeps all)
}With logs.enabled, krate dev, build, serve, start, check and deploy
write everything they print to <dir>/<timestamp>.log (colors removed, each line
stamped in UTC) and print the path when they finish. Add the directory to
.gitignore; the default .krate/logs is already inside .krate.
#Update notifier
updateNotifier: false, // default true
krate dev, build, serve, start, check, deploy and doctor print one
line on stderr when a newer krate version exists:
Update available: krate v0.5.0 -> v0.5.1. Run `krate upgrade` to update ...The line comes from a cached lookup, so it never slows a command down. The cache
(update-check.json in your user cache directory) is refreshed from the npm
registry in the background at most once a day; a command that finishes first waits
up to half a second for the answer. Nothing is sent but the registry request.
The notifier is off when updateNotifier is false, when CI is set (for
example CI=1), when KRATE_NO_UPDATE_NOTIFIER or NO_UPDATE_NOTIFIER is set,
when stderr is not a terminal, with --json, and for development builds.
#Tailwind CSS
tailwind: {
enabled: false,
scanDirs: ["src"], // directories to scan (or use `content` globs)
content: [], // Tailwind-style content globs; wins over scanDirs
preflight: true, // emit the Tailwind base reset (default; false to opt out)
strict: false, // warn about classes that produce no rule
darkMode: "media", // "media" | "class" | "selector"
executeConfig: false, // evaluate tailwind.config in-process (else static parse)
}#Content Security Policy
csp: {
enabled: false,
directive: "", // custom CSP string (empty = auto-generate)
}The generated policy hashes the final (minified) document: executable inline
<script> and <style> blocks (JSON data blocks such as the site config never
execute and are skipped), the inline speculation-rules script, and style="..."
attributes (allowed with 'unsafe-hashes' plus one SHA-256 hash per distinct
value). Styles set at runtime through the CSSOM (el.style.x = ...) are not
affected by CSP. When a CSP meta tag is present the client router does not
inject its runtime speculation-rules script (it would be blocked) and uses its
JS link prefetching instead. A CSP sent as an HTTP header cannot be seen from
the page, so there the router removes the script as soon as the browser blocks it.
#Markdown
markdown: {
gfm: true,
headingAnchors: true,
admonitions: true,
codeHighlight: true,
codeTheme: { light: "github", dark: "krate-dark" }, // or one name for both modes
math: false, // load KaTeX (CDN) and render $...$ / $$...$$
plugins: ["./md/transform.ts"], // AfterMarkdownParse HTML transforms
}codeTheme picks the syntax colours. A plain string ("monokai") is one theme
for both colour modes; { light, dark } picks one per mode, and a missing side
keeps its default (github, krate-dark). Any chroma style name works, and an
unknown one warns (KR7150) and falls back to the default for that mode. The
stylesheet follows the page's mode - the system preference, or a data-theme
attribute on <html> - and the markup is the same in both modes, so switching
needs no JavaScript and no second copy of the HTML. It applies to the Code
component and to fenced blocks alike.
Code that changes in the browser or is only known per request is highlighted
after the build; highlight: { languages: ["ts"] } lists the languages to load when
lang is not a literal (see Code Highlighting).
Beyond GFM (tables, task lists, strikethrough, autolinks), the renderer supports
definition lists, footnotes ([^1]), emoji shortcodes (:rocket:), and
component directives - :::card, :::steps (::step), :::tabs (::tab),
and :::code-group. The Tabs/Steps/Card/Code components are auto-imported
for the docs plugin; elsewhere :::component Name wraps arbitrary components.
markdown.plugins lists JS/TS modules (relative to the project root) whose
default export transforms rendered HTML. Author them with defineMarkdownPlugin:
// md/transform.ts
import { defineMarkdownPlugin } from "@krate/plugin";
export default defineMarkdownPlugin((html) => html.replaceAll("TODO", "DONE"));Each runs on the AfterMarkdownParse hook (async transforms are awaited) and
applies to rendered Markdown for both .md/.mdx page files and docs-plugin
pages.
#Runtime
runtime: "node", // "node" | "bun" | "deno"
#SSR / Streaming
ssr: {
streaming: false, // force all *static* pages to streaming SSR
ssrRuntime: "node", // sidecar runtime: "node" | "bun" | "deno"
rendererPort: 0, // renderer sidecar port (0 = default)
timeout: 5000, // max render time (ms)
maxCacheSize: 128, // ISR in-memory cache size
middlewareRuntime: "quickjs", // middleware.ts runtime
apiRuntime: "quickjs", // API route runtime
apiWorkers: 8, // embedded QuickJS API worker pool (default min(NumCPU, 8))
apiIsolation: false, // true = fresh VM per request (no shared state; slower)
nodeWorkers: 8, // Node sidecar worker processes (cluster)
rendererWorkers: 1, // SSR renderer worker processes (cluster; default 1)
}ssrRuntime- which runtime launches the SSR sidecar that renders SSR/ISR/streaming regions."node"(default) runs the staged renderer driver with plainnode;"bun"runs it withbun run;"deno"runs it withdeno run --allow-net --allow-read --allow-env --allow-sys.streaming- forces all static (SSG) pages into streaming mode. Explicit per-pageisr/ssrconfig still wins.middlewareRuntimeandapiRuntime("quickjs"|"node"|"bun"|"deno") choose which runtime executes middleware and API routes."quickjs"(default) uses the embedded QuickJS runtime with no Node.js dependency;"node"/"deno"use the Nodehttpsidecar;"bun"uses a Bun-native sidecar built onBun.serve(no Node http stack, no cluster shim) - the fastest JS/TS sidecar option. The build bundles each API route only for the runtime that serves it, so runkrate buildagain after changingapiRuntime;krate servewarns when the build is for another one.nodeWorkersforks that many Node worker processes (cluster) for the API sidecar whenapiRuntime(ormiddlewareRuntime) isnode/bun/deno. (Ignored by the Bun sidecar, which is single-process.)rendererWorkersforks that many Node worker processes (cluster) for the SSR renderer, so page/region rendering uses more than one CPU. Default1(single process). Region and ISR caches are per-worker, and ISR disk persistence is disabled while clustered. Irrelevant when all request-time regions render on the Go host (Go components).apiWorkerssizes the embedded QuickJS API worker pool. Workers are long-lived VMs that each load a route once and reuse it, so module state persists across requests (Node semantics) and requests run in parallel.apiIsolationruns every API request in a fresh VM (no shared module state). Slower; dev uses it automatically so route edits are picked up.
Page-level rendering is opted into per page via
export const config = { isr | ssr | streaming, revalidate } - see
Rendering. SSR/ISR/streaming pages render in
the sidecar, which resolves only the page's dynamic regions against the baked
static shell; the embedded QuickJS runtime is used for middleware, API routes,
and community plugins.
#Shared cache
cache: {
adapter: "redis", // "memory" (default) | "redis" | a module path / package
url: process.env.REDIS_URL, // redis://[user:password@]host:6379/0, rediss:// for TLS
urlEnv: "REDIS_URL", // variable a deployed bundle reads the URL from
prefix: "krate:", // key prefix, so apps can share one store
timeoutMs: 250, // one cache call; slower counts as down
ttlSeconds: 604800, // how long ISR entries stay in the shared store
options: {}, // passed to a custom adapter
}Moves the ISR page cache and the data cache out of process memory and makes
revalidatePath / revalidateTag reach every instance. See
Sharing caches between instances.
krate deploy bundles the settings without url; the deployed server reads
urlEnv (or KRATE_CACHE_URL).
#Partial prerendering (PPR)
ppr: true, // cache dynamic regions on non-ISR pages
ppr: { revalidate: 60 } // ...with a custom window (seconds)
Dynamic regions (Suspense primaries + @runtime components) are already spliced
into the baked shell. PPR additionally caches each region independently with
stale-while-revalidate. Per-region directives win: add
export const revalidate = 30 to a *.runtime.tsx component to give just that
region a 30-second window. Region caches are bounded, persisted with the ISR
cache, and invalidated per route.
Region cache keys include the route, parameters, and query - not cookies,
headers, or sessions. Do not enable ppr for regions that render
per-user/per-session content, or one user's output can be served to another.
#View Transitions
viewTransitions: "auto", // "auto" (default) | "off" | true | false
When enabled, the SPA router wraps each navigation in the native View
Transitions API (document.startViewTransition), and every page emits the
cross-document @view-transition { navigation: auto } rule so full-page loads
morph too. Mark persistent chrome with data-view-transition="name" to morph it
instead of cross-fading. Reduced-motion preferences are respected.
Pages carry the router's settings in a JSON data block in <head>
(<script type="application/json" id="__krate_cfg__">), and only when a setting
differs from the defaults: a basePath, viewTransitions: "off", or krate dev.
A site on the defaults has no such block. The block is data, not code, so a strict
script-src 'self' policy needs no allowance for it. With View Transitions on,
the @view-transition rule is an inline <style> (a style-src policy needs
csp.enabled hashing or 'unsafe-inline' for it, or turn View Transitions off).
#Trailing slash
trailingSlash: "always", // "always" (default) | "never" | "ignore"
The URL form of pages, honoured the same way by krate serve/krate start and the
node, vercel, netlify and cloudflare targets:
"always":/historyanswers301to/history/."never":/history/answers301to/history(the site root stays/)."ignore": no redirect in either direction; both URLs serve the page. Set it when the platform or another layer owns canonicalization, or when you want to link both forms.
A URL that matches no page follows the same slash rule as pages (/nope goes to
/nope/ with "always", /nope/ to /nope with "never") and then answers 404
with the site's 404 page, whatever the Accept header says.
Files with an extension (/feed.xml), /api/* and the internal /__krate/* paths
are never redirected. The setting changes what the servers answer, not what the
build writes: canonical URLs, sitemap entries and generated links still use the
slash form, so with "never" they point at URLs that redirect (write your own
links and seo URLs without the slash). On the cloudflare target the generated
wrangler.jsonc sets assets.html_handling to match (drop-trailing-slash for
"never"; "none" plus run_worker_first: true for "ignore", because then the
Worker serves the pages from the assets). krate deploy --target vercel writes
trailingSlash into vercel.json ("always" is true, "never" is false,
"ignore" leaves it unset); deploy.options.trailingSlash still overrides it. On
vercel and netlify the CDN serves prerendered pages before the function, so
their URL form follows the platform's own setting; the function applies the mode to
the pages it serves.
#Plugins
import { sitemap, feed, docs, robots, llms } from "@krate/core";
plugins: [
sitemap({ baseUrl: "https://example.com" }),
feed({ baseUrl: "https://example.com", type: "all", count: 20 }),
robots({ disallow: "/admin" }),
llms({ title: "Krate Docs" }),
docs({ contentDir: "src/content/docs", title: "Docs" }),
]The sitemap plugin lists every statically generated page once, at the URL the
site is served from (with a trailing slash and the basePath), percent-encoded
and XML-escaped. It leaves out error pages, dynamic-route fallback templates
(blog/[slug]) and pages with <meta name="robots" content="noindex">. Pass
exclude: ["/admin/*", "/private/"] (path.Match patterns) to drop SSR or
private routes. Canonical URLs, og:url, hreflang links and the robots.txt
Sitemap: line use the same form, and the document <title> follows
site.titleTemplate. A layout and a page that both emit <title>, a meta
description or og:image produce a single tag: the page wins.
The feed plugin emits feed.xml (RSS), atom.xml, and feed.json from the
docs content and adds <link rel="alternate"> discovery plus JSON-LD
structured data to docs pages. robots and llms are typed factories like the
others; their options override the top-level robots/site metadata. The docs
plugin also renders tag/category index pages
(/docs/tags/<slug>/, /docs/categories/<slug>/) and fills each page's
"last updated" date from git history (disable with docs({ lastUpdated: false })).
Docs layout options:
docs({
// Sidebar: "auto" (default), "none", an explicit tree, or a JSON file.
sidebar: "auto",
// sidebar: [{ title: "Guides", children: [{ title: "Intro", url: "/docs/guides" }] }],
// sidebar: { from: "file", file: "sidebar.json" },
toc: true, // table of contents (default true)
breadcrumbs: true, // breadcrumbs (default true)
pagination: true, // prev/next links (default true)
editLink: { pattern: "https://github.com/org/repo/edit/main/:path" },
search: { placeholder: "Search the docs", hotkey: "/" },
})editLinkBase is deprecated; use editLink.base (base URL + source path) or
editLink.pattern (a URL template with :path). search.hotkey (e.g. / or
mod+k) focuses the search input, and search.placeholder sets its placeholder.
#Extends & presets
extends: "./base.config.ts",
// extends: ["@acme/krate-preset", "./local.config.ts"],
Bases are merged underneath this config: objects deep-merge (this config wins),
and additive arrays (plugins, redirects, rewrites, serverComponents,
runtimeComponents, serverDirs, runtimeDirs, cssImportRoots, hostFunctions, hostDirs) concatenate. Duplicate
plugins are de-duped by name, with the extending config winning. Paths resolve
relative to the extending config, then to node_modules (package presets -
resolved via package.json krate, exports, module, or main). Cycles are
rejected.
#Deploy
deploy: {
target: "vercel", // netlify | vercel | cloudflare | gh-pages
options: { cleanUrls: "true", trailingSlash: "false" },
worker: "src/cloudflare.ts", // cloudflare: module merged into the Worker (default src/cloudflare.ts)
},krate deploy uses this target unless --target is passed; the adapter options
customize the generated host files. The top-level trailingSlash
setting is mapped onto the host's own option where there is one.
deploy.worker is the module whose exports are merged into the generated
Cloudflare Worker: cron scheduled, queue, email handlers and Durable Object
classes. Without it, src/cloudflare.ts (or .mts, .js, .mjs) is used when it
exists; deploy.worker: "none" skips it. deploy.cloudflare.cache: true stores
cacheable SSR responses in caches.default. See
Cloudflare Workers.
#i18n & versions
i18n: { defaultLocale: "en", locales: ["en", "fr"], localeLabels: { fr: "Français" } },
versions: { current: "v2", versions: ["v2", "v1"], labels: { v1: "1.x (legacy)" } },localeLabels / labels override the built-in display names in the locale and
version switchers (docs plugin).
i18n and versions are docs-scoped. For app pages, use [locale] dynamic
routes + content collections (Krate does not auto-prefix arbitrary page routes).
Docs pages emit <html lang> for their locale server-side. Any page can override
it with export const lang = "fr" (or export const config = { lang: "fr" }).
#Redirects & rewrites
redirects: [
{ source: "/old-page", destination: "/new-page", permanent: true },
]
rewrites: [
{ source: "/docs/:path*", destination: "/documentation/:path*" },
]#SEO & robots
seo is retained for compatibility; prefer site (see Site metadata),
which also supports titleTemplate, twitter, themeColor, and locale.
seo: {
baseUrl: "https://example.com",
siteName: "Krate",
description: "A modern static site generator",
image: "https://example.com/og.png",
}
robots: {
allow: "/",
disallow: "/admin",
sitemap: "https://example.com/sitemap.xml",
}#Component tiers
serverComponents: ["DataTable"], // names -> @server
runtimeComponents: ["AuthCheck"], // names -> @runtime
serverDirs: ["src/components/server"],
runtimeDirs: ["src/components/runtime"],#React islands
react: {
islands: ["some-canvas-library"], // packages that must run on real React
},islands- npm packages that must run on realreactandreact-dom, not on Preact. A module that imports one becomes a client-rendered real-React island. Packages that depend onreact-reconciler,@react-three/fiberorreact-konva(@react-three/drei,react-konva, ...) are detected without being listed. See Libraries built on a React reconciler.
#Native (experimental)
hostFunctions: ["addTask", "src/lib/db.ts"], // names or paths -> host code
hostDirs: ["src/host"], // every module -> host code
native: { appId: "com.acme.app", productName: "Acme" },hostFunctions, hostDirs and the native block configure the desktop target.
See Native and Host code.
#TypeScript path aliases
pathAliases: {
"@/*": ["./src/*"],
},
tsBaseDir: ".",Path aliases are also read automatically from tsconfig.json
(compilerOptions.paths and baseUrl) - e.g. @/components/Button ->
src/components/Button.
#Content collections
content: {
blog: {
dir: "src/content/blog", // default: src/content/<name>
schema: {
title: "string",
order: { type: "number", required: true },
tags: "string[]",
status: { type: "string", enum: ["draft", "published"], default: "draft" },
},
},
},content may be a plain object or defineContent({...}) (an optional identity
helper for editor assistance). Entries under each dir are validated against
the schema; violations fail the build. Types are generated into
.krate/types/content.d.ts. See
Typed Routes & Content.
#Output mode
output: "static", // default: request-time rendering allowed
"static" makes the build fully static: dynamic routes only render the params
returned by generateStaticParams (unknown params 404), and SSR/ISR/streaming
are disabled. Individual pages can re-enable dynamic params with
export const dynamicParams = true. See
Static output & dynamic params.
#Browser compatibility
compat: {
mode: "modern", // "modern" (default) | "legacy" | "hybrid"
userAgent: false, // hybrid only: emit a UA-selectable legacy document
},Controls how CSS Signals are emitted for browser support (see Browser Support):
modern(default) -:has()selectors, zero client JS for CSS-signal pages. Requires:has()(Chrome/Edge 105+, Safari 15.4+, Firefox 121+).legacy- emits class-based selectors plus a tiny scoped shim instead of:has(), so interactive CSS-signal pages work on browsers without it.hybrid- emits both, each wrapped in@supports selector(:has(*)), and feature-gates the shim. Modern browsers keep the zero-JS:has()path; legacy browsers get the shim. One document, no server involvement.
userAgent: true (hybrid only) additionally writes per-page sibling documents
(index.modern.html and index.legacy.html), each linking a variant-only
stylesheet (modern-only / legacy-only). krate serve sends the matching sibling
to User-Agent-classified visitors, preferring Chromium's Sec-CH-UA client hint
(requested via Accept-CH) over the User-Agent string, and sets
Vary: User-Agent, Sec-CH-UA. The default
document stays the full hybrid, so static hosts (which cannot select per
request) still serve a document that works everywhere.
#Quality checks
checks: {
a11y: "error", // "error" | "warning" | "off" | boolean
seo: "warning",
perf: "warning",
rules: { "perf/js-budget": "error" },
ignore: ["seo/og"],
budget: { // per-route budgets, KB
js: 150, // hydration + shared runtime
hydration: 50, // route hydration bundle
islandJS: 100, // island chunks
route: 350, // HTML + CSS + JS + islands
},
failOn: "error",
custom: ["./checks/my-rule.ts"],
},failOn accepts only "error" or "warning"; any other value is a config
error (checked when the config loads, for every command).
When a checks object is present, krate build runs the quality gates and
fails on findings at or above failOn. krate check runs the same rules
against the emitted output. Alongside the a11y/SEO/perf rules, Krate checks
seo/broken-link (internal links resolve to a known route),
a11y/broken-anchor (in-page #id targets exist), seo/og-image (absolute
Open Graph image), and seo/duplicate-meta (unique titles/descriptions across
pages). See Quality Checks.
#Dead-code elimination (DCE)
dce: {
css: true, // prune unused CSS-module rules (default true)
js: true, // JS dead-code elimination (default true)
aggressive: false, // EXPERIMENTAL: also drop local helpers the scan can't prove unused
},CSS DCE removes .module.css rules whose scoped class never appears in the
page's HTML (global, Tailwind, and component styles are never touched). JS DCE
is conservative by default. Disable both with --no-dce.
Experimental: dce.aggressive additionally drops local helper functions the
reference scan cannot prove are used. This can remove a function that is only
referenced from a part of the component body the scan does not inspect, so it is
off by default and may change behavior. Leave it off unless you have verified the
output; use --no-dce to disable DCE entirely.
#Fonts
fonts: {
preload: true, // <link rel="preload"> for @font-face fonts (default true)
display: "swap", // default font-display injected when a face omits it ("off" to skip)
preloadLimit: 4, // most fonts preloaded per page
},Preloading covers every stylesheet (global and page-imported). Each
@font-face contributes its first woff2 source (woff/ttf fallbacks are never
preloaded unless they are the only source); relative url()s resolve against the
stylesheet, not the page. Faces for non-Latin unicode-range subsets are
skipped, and a /* no-preload */ comment inside an @font-face block opts that
face out.
#Go (components & API routes)
go: {
enabled: true, // default true
module: "krate-goapi", // module path when none is provided
deps: [{ path: "github.com/x/y", version: "v1.2.3" }],
replaces: [{ from: "example.com/x", to: "../local/x" }],
exclude: [{ path: "github.com/a/b", version: "v9.9.9" }],
tidy: false, // run `go mod tidy` before building
componentDirs: ["src/components"], // scanned for *.go components
apiDirs: ["src/api"], // Go API routes (first dir is used)
apiEnabled: true, // build Go API routes
},go configures the unified Go host that compiles Go API routes
(src/api/**/*.go) and Go components (componentDirs/**/*.go, see
Go Components) into one binary. It supersedes
the older goApi block (deprecated; its values are folded into go, and a
config that sets it gets a warning).
Go is enabled by default with componentDirs: ["src/components"] and
apiDirs: ["src/api"], so no config is needed for the default layout. Run
krate go:init once to set up editor intellisense (a project go.mod +
go.work, the vendored helpers under .krate/goext, and .krate/types in your
tsconfig.json). Go requires the Go toolchain at build time.
Source trees are preserved: helper files keep their package, and each route file
compiles into its own generated package. A src/api/go.mod or
src/components/go.mod is used verbatim; otherwise a project-root go.mod is
merged (its require/replace/exclude directives are copied and relative
replace paths rebased), falling back to a generated module. The helper
packages (krate, runtime) are vendored under .krate/goext and imported via
their real paths (github.com/kratejs/krate/packages/compiler/goext/...). See
API routes.
#Base path
Set where the site lives in site.url. A path there is the base path, so this
is all a site under a sub-path needs:
site: { url: "https://example.com/example/a" }, // served under /example/a
basePath sets the path directly and wins over site.url. Use it when the URL
path and the serving path differ, for example behind a proxy that strips the
prefix (basePath: "/" forces the root):
basePath: "/docs", // serve the whole site under a sub-path (default: path of site.url)
With a base path, the build prefixes:
- hydration scripts, runtime chunks, stylesheets, dynamic
import()chunks and workers; - imported assets,
<Image>output, and generated URLs in CSS; url(/x.png)in CSS and<link>and<script>URLs in<head>, when the file exists inpublic/. Other root-relative URLs may belong to another app on the host, so they stay as written;<Link href>,navigate(),krateRouterandredirect()in the browser, and root-relative links and images in Markdown;- canonical URLs, sitemaps, feeds and
llms.txt.
Write every one of these as a path from the site root, without the base path:
<Link href="/about">. Relative, #hash, ?query and absolute URLs are never
changed.
Plain <a href="/about"> and <img src="/logo.png"> stay exactly as written, so
they point outside the site. A literal value gives a
KR7144 build warning: use <Link>, or
<Image> or an import. A value computed at run time gets no warning.
#Linking to the rest of the domain
When Krate is one app of several on a domain (the marketing site at /, Krate
at /app), links to the other apps must not get the base path. Use the
explicit opt-out:
<Link href="/pricing" basePath={false}>Pricing</Link>
<a href="/blog" data-krate-no-base>Blog</a>
<a href="https://example.com/pricing">Absolute URLs also work</a>basePath={false} and data-krate-no-base use the URL as written, never
rewrite it (at build time, in server renders and in the browser), and keep the
click out of the client router, so it is a normal full-page navigation. They
also silence KR7144. <Link external> is different: it only skips client
navigation and still adds the base path, for in-site pages that must load
normally. Config redirects use basePath: false the same way.
krate serve and krate dev mount the site under the base path, and requests
outside it are redirected in. Code behind the base path sees paths without it, and
a root-relative Location it answers with gets the prefix on the way out. Config
redirects work the same way unless a rule sets basePath: false; see
Redirects & Rewrites. Static hosts serve dist/ as uploaded, so mount
it at the same path. See Deployment.
#Server
server: {
host: "", // bind address for `krate serve` (default: all interfaces, for containers)
port: 3000, // falls back to devServer.port, then 3000
maxBodySize: 1048576, // request body cap in bytes (0 = defaults)
trustProxy: false, // honor X-Forwarded-Proto/Host/For from a reverse proxy
trustedProxies: 1, // reverse proxies in front of Krate (with trustProxy)
shutdownTimeout: 15, // seconds in-flight requests get to finish on SIGTERM
},The port comes from --port, then the KRATE_SERVE_PORT and PORT
environment variables (serve/start only), then server.port (or
devServer.port); --host overrides server.host the same way
(KRATE_SERVE_HOST for serve/start). Request bodies are capped
(1 MiB for pages/middleware, 25 MiB for API routes by default). GET /healthz
is a liveness probe; GET /readyz is readiness (fails while an expected SSR
sidecar is down). Both stay reachable at the root even under a basePath.
By default the server ignores client-supplied X-Forwarded-* headers and
replaces them with what it observed, so handlers cannot be spoofed. Behind a
trusted reverse proxy set trustProxy: true: request URLs seen by middleware
and API routes use X-Forwarded-Proto / X-Forwarded-Host, the server-action
CSRF origin check compares against the forwarded host, and the client address is
the X-Forwarded-For entry trustedProxies hops from the right (default 1: the
address your proxy saw). Entries a client puts at the front of the header never
count. Set trustedProxies to the number of proxies in front of Krate if there
is more than one (a CDN and a load balancer, for example).
On the Vercel, Netlify and Cloudflare targets trustProxy has a third state: not
set means "what the platform guarantees", true adds the forwarded headers of a
proxy of yours, false trusts none. See
Proxy trust on the serverless targets.
On SIGINT/SIGTERM the server stops accepting connections, lets in-flight
requests finish for shutdownTimeout seconds (default 15), then stops its
sidecars and exits with status 0. A second signal exits immediately.
#Server packages, traced files and env directory
serverExternalPackages: ["sharp", "@napi-rs/canvas"], // stay in node_modules at run time
outputFileTracingIncludes: { // extra files for the node deploy output
"*": ["assets/fonts/**", "workers/image.js"],
"/api/og": ["node_modules/@resvg/resvg-js-*/**"],
},
envDir: "../..", // where .env files are read from
serverExternalPackageslists npm packages that server bundles do not bundle: API routes compiled for the embedded runtime (a route that imports one becomes Node-only and runs on the Node sidecar) and thenodedeploy bundle, which imports them from anode_modulesit writes next toserver.mjs. A package that contains a native.nodeaddon is detected and handled the same way without being listed. Entries are package names, not paths. The platform deploy targets (Vercel, Netlify, Cloudflare) bundle everything and refuse a native addon with an error that names the package. See Self-hosting.outputFileTracingIncludesmaps a route key (kept for compatibility with Next.js, any key works) to globs of project files thatkrate deploy --target nodecopies next toserver.mjsat their project-relative paths, and that--target dockercarries into the image. Globs are relative to the project root (*,?,[a-z]and**are supported), may not be absolute or contain.., and are checked against the project root when files are copied. Use it for files that import tracing cannot see: a worker entry loaded by path, a platform binary chosen by a computedrequire.envDiris the directory the.env,.env.<mode>,.env.localand.env.<mode>.localfiles are read from. A relative path resolves against the project root and may point at a parent directory, such as a monorepo root; it must exist. It applies tokrate dev,build,serve,startanddeploy, tokrate.config.tsitself (the config is evaluated again with the variables fromenvDir) and to everything that readsprocess.envat build or serve time.KRATE_PUBLIC_*values are still the only ones inlined into client code. Changes to files inenvDiroutside the project are not watched bykrate dev; restart it.
#CORS
cors: {
enabled: false, // default: same-origin only
origins: ["https://app.example"], // ["*"] when omitted
methods: ["GET", "POST"],
headers: ["Content-Type"],
credentials: false,
maxAge: 600,
},Preflight OPTIONS requests are answered automatically when enabled.
#API sidecar
Forward /api/* to your own HTTP service. Requests are forwarded first, and a
404 falls through to Krate's built-in Go/TS/QuickJS routes, so the sidecar can
own exactly the routes it wants (including dynamic segments like
/users/[id]) with no route declarations.
api: {
sidecar: {
// Supervised: Krate launches and stops the process.
command: "node", args: ["server.js"], port: 8080,
// ...or proxy-only for an already-running service:
// target: "http://127.0.0.1:8080",
prefix: "/api", // path prefix the sidecar owns (default "/api")
},
},See API Routes.
#Tailwind @apply
Plain utility @apply is expanded in your CSS (p-4, font-bold, ...).
Variant (hover:*, md:*) and descendant-selector (space-x-*) utilities
become nested rules inside the rule that applies them (native CSS nesting).
Unknown utilities are reported as build warnings and left unexpanded.
#Validation
validate: (config) => { /* optional build-time validation */ }#Config load errors
--config <path> selects a different config file. It resolves against the
project directory and must exist: a mistyped path is an error naming the path,
not a silent fallback to the defaults. Without --config, Krate looks for
krate.config.ts, .js, .mjs or .json and uses the defaults when none is
present.
A config that does not parse fails the command with file:line:col, the
offending source line and a hint - for example stray text after
export default { ... }, an unclosed brace, or invalid JSON in
krate.config.json. The same applies to a base pulled in with extends.
Configs are normally evaluated in the embedded JavaScript runtime, so imports,
TypeScript syntax and extends all work. If that runtime cannot run a
module-free config, Krate falls back to a static reader for a plain
export default { ... } literal and prints a warning saying so; extends is
ignored on that path. The static reader applies the same type rules as the
evaluated path: a wrongly typed nested value (for example server.port: "80")
is an error, not silently skipped.
Last updated: 2026-11-17
Contributors: Noinkin