#Configuration
The krate.config.ts entry point and a map of every option group.
Krate is configured with a krate.config.ts file at the project root, typed
with defineConfig from @krate/core. Every supported key is type-checked -
unknown or misspelled options become compile errors.
import { defineConfig, sitemap, docs } from '@krate/core';
export default defineConfig({
entry: "src/index.tsx",
outDir: "dist",
pagesDir: "src/pages",
minify: true,
tailwind: { enabled: false, scanDirs: ["src"] },
redirects: [{ source: "/old", destination: "/new", permanent: true }],
plugins: [
sitemap({ baseUrl: "https://example.com" }),
docs({ contentDir: "src/content/docs", title: "Docs" }),
],
});React syntax (useState, useEffect, useRef, JSX) is transpiled to Krate
signals and effects automatically - no config is required. See
React Compatibility.
#Validation
Beyond editor type-checking, the compiler validates the file when it loads it:
- An unknown key at any depth, including inside arrays of objects
(
redirects[].permanant), is reported as a warning and ignored. - A value of the wrong type is an error that names the file, the key and the
expected type, for example
krate.config.ts: devServer.port must be a number (got string). - A
pagesDirthat does not exist (with noentryto fall back to) is an error:pagesDir src/nope does not exist. - In
krate dev, editingkrate.config.*,tailwind.config.*,tsconfig.jsonor an.env*file reloads the configuration and restarts the dev server; an invalid edit is reported and the running server is left alone.
#What a config file can use
krate.config.ts runs in-process (esbuild plus an embedded JavaScript engine),
not under Node, so it sees a subset of the Node API:
process.envholds the shell environment overlaid with the project's.envfiles (the shell wins), andNODE_ENVis"development"inkrate devand"production"otherwise unless the shell sets it.process.cwd()is the project root;process.platformandprocess.argvare available.node:path,node:url,node:fs(readFileSync,existsSync,readdirSync,statSync) andnode:os(platform,homedir,tmpdir,EOL,arch,type,cpus). Relativefspaths resolve against the project root.__dirnameand__filenamefor each module,import.meta.url,module.exports(alone or beside imports), top-levelawait,URL,crypto.randomUUIDand a smallBuffer(from,alloc,concat,toStringas utf8, base64 or hex).
fs is read-only, and statSync returns only isFile(), isDirectory() and
isSymbolicLink() (no size or times). Any other built-in (child_process,
crypto, net, zlib, fs/promises, ...), with or without the node:
prefix, fails with an error that names it (require("child_process") reports
Module not found: child_process). The global crypto.randomUUID() works; it
is the import that does not. A named import of something the shims lack, such as
import { createRequire } from "node:module", reports esbuild's
No matching export in "krate-node:module". Compute such values in a script
and read them from the environment, or move the logic into a plugin. Packages
from node_modules are bundled as usual.
#Option groups
This page is a map; the Config Reference documents every key and its default.
| Group | Key(s) | Reference |
|---|---|---|
| Build | entry, outDir, pagesDir, publicDir, minify, sourcemap |
Build |
| Dev server | devServer |
Dev server |
| Rendering | viewTransitions, ppr, ssr, output |
SSR / Streaming |
| CSS & Tailwind | tailwind |
Tailwind CSS |
| Markdown | markdown |
Markdown |
| Content | content, pathAliases, tsBaseDir |
Content collections |
| Server | server, basePath, redirects, rewrites |
Server |
| Security | csp, cors |
Content Security Policy |
| SEO | seo, robots |
SEO & robots |
| Checks | checks |
Quality checks |
| Plugins | plugins |
Plugins |
Last updated: 2026-11-17
Contributors: Noinkin