#Upgrading
Keep Krate, @krate/runtime, and @krate/components in sync and upgrade safely.
Krate ships as several packages that must stay on the same minor:
@krate/core- the CLI + Go compiler@krate/runtime- signals, DOM, router, server renderer@krate/components- the built-in component library
#Upgrading a project
npm install @krate/core@latest @krate/runtime@latest @krate/components@latest@krate/core declares an @krate/runtime peer; a version mismatch prints a
warning. Upgrade them together.
Then rebuild and check:
krate build
krate check#From 0.4 to 0.5
0.5 changes several defaults and hardens the compiler and the servers. Most
projects need one edit (tsconfig.json); the rest is a list of things to check.
In order, with the one that bites first at the top:
| # | What changed | How you notice | What to do |
|---|---|---|---|
| 1 | tsconfig baseUrl is honoured |
A KR7125 warning on every build (a target that exists nowhere is an error: cannot resolve import "@/...") |
krate fix --apply |
| 2 | Tailwind output follows v4 | Rings, shadows, blurs, outlines and colours look different; a reset appears | Rename classes, or tailwind.preflight: false |
| 3 | krate dev binds 127.0.0.1 |
Connection refused from a container, WSL or another machine | krate dev --host 0.0.0.0 |
| 4 | krate start no longer builds |
no build output found in dist |
Run krate build first, or use krate serve |
| 5 | tailwind.config.* runs in the config sandbox, not under npx tsx |
A Tailwind config that used a Node API fails to load | Check the API subset |
| 6 | Output layout | A deploy script cannot find dist/manifest.json |
Read dist/.krate/manifest.json |
| 7 | New hard errors | A build that passed on 0.4 fails | Per-code table |
| 8 | bin/krate is gone from @krate/core |
krate: command not found, or a script runs node_modules/@krate/core/bin/krate |
Use krate, npx krate or node_modules/.bin/krate |
| 9 | Server hardening | Middleware runs on more URLs; proxy headers read differently | See below |
#tsconfig.json: baseUrl is strict
0.4 ignored baseUrl when it resolved paths aliases such as @/*. The 0.4
project template shipped with
"baseUrl": "./src",
"paths": { "@/*": ["./src/*"] }which tsc reads as src/src/* and the 0.4 compiler read as src/*. From 0.5
Krate resolves paths exactly as tsc does: targets are relative to
baseUrl. When a target does not exist there but does exist relative to the
project root, as it does in the template above, Krate still reads it from the
root so the build works, and prints one warning on every build:
! config: [KR7125] tsconfig.json: paths target "./src/*" does not exist under baseUrl "./src" but does under the project root; Krate resolves it there, tsc does not. Run `krate fix --apply` to set baseUrl to "."tsc and your editor still read the file the strict way, so type-checking and
go-to-definition on @/ imports stay broken until you fix the file. A target
that exists in neither place is a real mismatch and fails the build:
Error (src/pages/index.tsx): bundling page src/pages/index.tsx:1:1: cannot resolve import "@/components/Counter" (matched tsconfig path alias "@/*")
hint: no file exists at the alias target; targets resolve relative to compilerOptions.baseUrl (/app/src). If baseUrl is "./src" and the targets also start with ./src/, run `krate fix --apply` to set baseUrl to "."To silence the warning and make tsc agree, make baseUrl the project root:
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }krate fix does this for you when it is unambiguous: baseUrl names a
directory, every paths target starts with that directory, and the targets
exist under the project root but not under baseUrl.
krate fix # dry run: tsconfig.json:13:16 KR7125 "./src" -> "."
krate fix --applyComments and formatting in tsconfig.json are kept. The edited file also
builds on 0.4, so you can make the change before upgrading and roll back
without undoing it. If you keep baseUrl: "./src" on purpose, write the
targets relative to it ("@/*": ["./*"]). Note that this changes meaning
silently: on 0.4 "./*" meant the project root, on 0.5 it means src/.
Related changes: a bare import that no paths entry and no package satisfies is
now tried against baseUrl (as tsc does with baseUrl alone); a
paths/baseUrl written with backslashes is normalised; an alias import of an
asset (import logo from "@/assets/logo.png") works like a relative one. See
TypeScript Setup.
#Tailwind output follows v4
With tailwind.enabled, the generated CSS now follows Tailwind v4 semantics,
and a reset is included by default. The same page differs like this (measured
with 0.4.0 and 0.5 on one page, shadow rounded border ring bg-blue-500 blur):
| 0.4 | 0.5 | |
|---|---|---|
| Colours | hex (#3b82f6) |
oklch(62.3% 0.214 259.815) |
| Reset (Preflight) | none | included in @layer base: margin/padding/border zeroed on every element, headings unstyled, lists without markers, button and form controls inherit font and colour, images are display: block |
ring |
3px, blue-500 at 50% |
1px, currentcolor (ring-3 is the old width) |
shadow-sm |
0 1px 2px |
0 1px 3px (what shadow was); shadow-xs is the old shadow-sm |
blur-sm, rounded-sm |
4px, 0.125rem |
8px, 0.25rem; blur-xs and rounded-xs are the old values |
outline-none |
outline: 2px solid transparent |
outline-style: none; outline-hidden keeps the old accessible behaviour |
| Layers | none | @layer theme, base, components, utilities, plus @property blocks |
@theme variables stay live, so utilities read them through var(), as in
Tailwind v4: .dark { --color-primary: ... } now re-themes bg-primary. A default
such as --color-blue-600 or --spacing goes live once your project sets it in a
scanned file. If a stylesheet already sets one of these names for another reason,
it now changes those utilities; rename the variable, or use @theme inline, which
copies the value into the utility.
What to do:
- To keep the old look, rename classes:
shadow-smtoshadow-xs,shadowtoshadow-sm,blur-smtoblur-xs,rounded-smtorounded-xs,ringtoring-3 ring-blue-500/50,outline-nonetooutline-hidden. - To drop the reset, set
tailwind: { preflight: false }inkrate.config.ts. There is no switch that restores Tailwind v3 output as a whole. - Unlayered CSS beats Tailwind utilities because utilities live in a layer. A
global
* { margin: 0; padding: 0 }now overridesp-*andm-*; move it into@layer base { ... }.
#krate dev binds 127.0.0.1
0.4 listened on all interfaces; 0.5 listens on loopback only (the browser on the
same machine is unaffected). In Docker, WSL2, a devcontainer or a remote
machine, the host's browser can get "connection refused" and the log says
http://localhost:3000 without mentioning the bind address. Bind all
interfaces explicitly:
krate dev --host 0.0.0.0or once in krate.config.ts:
export default defineConfig({ devServer: { host: "0.0.0.0" } });In Docker also publish the port (-p 3000:3000). With 0.0.0.0, the dev
server is reachable by anyone on the network, so use it only on a trusted one.
In WSL2, localhost forwarding from Windows may work with the default bind;
use the override when it does not, or when you browse from another device. krate serve and krate start
still bind all interfaces (server.host restricts them).
#krate start and krate serve
In 0.4 start was an alias of serve and rebuilt first. In 0.5 krate serve
builds and serves, and krate start only serves an existing dist/. A
"start": "krate start" script on a fresh checkout now stops with no build output found. Run krate build before it (the usual Dockerfile does), or
change the script to krate serve.
#Config files run in a sandbox
krate.config.ts has been evaluated inside the krate binary (esbuild plus an
embedded JavaScript engine, not Node) since 0.4. In 0.4 that engine had no Node
modules at all, so import path from "node:path" failed; 0.5 adds path,
url, os, read-only fs, process.env, process.cwd(), process.argv,
process.platform, Buffer, URL and crypto.randomUUID(). A config that
loaded on 0.4 loads on 0.5. child_process, net, zlib, fs/promises and
similar still do not exist and fail with an error that names the module. The full
list is in Configuration.
What does change is where npx tsx was used. With tailwind.executeConfig,
0.4 ran tailwind.config.* under npx --yes tsx, a full Node, so it could use
any Node API; 0.5 runs it in the same sandbox. And generateStaticParams,
API routes on a Node sidecar and the SSR renderer no longer start tsx at all:
they run on plain Node 20+, so they no longer need npx or a download. If a Tailwind config or plugin needs more than the sandbox offers,
compute the value in a script and read it from the environment, or move the
logic into a plugin.
#Build output
- The manifest moved from
dist/manifest.jsontodist/.krate/manifest.json(dist/.krate/server-manifest.jsonbeside it for server builds). Update scripts that read it. A static host or anrsyncrule that skips dot directories skipsdist/.krate/; static sites do not need it (krate deploystrips it), server builds do. 404.htmlloads a small hydration script (/__404/index.<hash>.js) so client-side navigation works from it, and carries<meta name="robots" content="noindex">. A host or CSP that assumed the page is JavaScript-free must allow the script.- Pages carry markers the runtime needs:
<script type="application/json" id="__krate_route">and<!--k:...-->comments, so HTML is about 15% larger (the starter'sindex.htmlwent from 2111 to 2452 bytes), andwindow.__KRATE_CFG__and the view-transition<style>moved to the start of<head>. Tests that compare HTML byte for byte need new baselines. - Pages that are only static no longer load the shared runtime chunk. Pages with an island or an action form do, as before.
- A
<Image width={n}>ships variants of that size (width={100}gives 100w and 200w) instead of six fixed 640-2000w files.
#New build errors
0.4 had no diagnostic codes and let these through; they are errors now. The full list is in Diagnostics.
| Code | Cause | Fix |
|---|---|---|
| (no code) | An import that resolves to no file or package, or an alias target that does not exist | Install the package, fix the path, or see the baseUrl section above |
KR7123 |
Importing .scss, .sass, .less or .styl (0.4 dropped the styles silently) |
Compile to CSS in a prebuild step, or use CSS modules or Tailwind |
KR7124 |
import { signal } from "@krate/runtime": a name the package does not export (it failed in the browser) |
Use the Krate name (createSignal, ...); see the runtime API |
KR8801 |
<Image src="/missing.jpg"> for a file not in public/ |
Add the file or fix the path |
KR7121 |
src/pages/data.json.ts-style endpoint threw at build time (0.4 built an empty HTML page for it) |
Fix GET, or move it to src/api |
KR8013 |
A hook of an npm React library (zustand, SWR, ...) in a server component, or a compiled component in a static layout | Add "use client" to the module that calls the hook; make the layout async |
KR3003, KR3007 |
A class component with an unsupported static member, or this in a static |
Rewrite the class as a function component |
KR7115 |
A tier decorator (@server, @client, ...) where it cannot apply |
Move it to a function, class or the default export |
KR9001, KR9002 |
Two 404/error files for one segment, or one in a @slot |
Keep one per directory |
KR8320 |
A dynamic tag (<Tag>) the build cannot resolve; it used to render an empty <span> |
Use a const, prop or prop default that folds, or a plain conditional |
KR8321 |
<ui.Button> where ui has no such component; it used to render a literal <ui.Button> element |
Fix the name, or export the component from the module |
KR8322 |
A @static or @server page reads a module value that top-level code changes in a way the build cannot run |
Compute the value in the component, or make the page hydrate |
KR8840 |
An <Icon> that cannot be resolved; its error text and a local path used to land in the page |
Fix the name, add icons/<name>.svg, or allow network access to api.iconify.design (fetched icons are cached in .krate/cache/icons) |
KR7142 |
A generateStaticParams entry with a missing or unsafe param, or two entries for one path |
Fix the entry the error names |
KR7143 |
middleware.ts exports no handler |
Add export function middleware(request) or a default export |
| (no code) | Malformed frontmatter: an unterminated quote, an unclosed [ or {, or a line that is not key: value |
Fix the file and line the error names |
| (no code) | A CSS, JS, runtime, chunk, manifest or image file that cannot be written (the build used to print "Done!") | Check disk space and permissions on the output directory |
Config is validated too: a value of the wrong type (devServer.port: "3000")
and a missing pagesDir are errors; an unknown key is a warning. Content
collections reject two entries with one slug (a.md and a.mdx) and a
non-ISO date. krate build ./typo fails instead of creating the directory.
KR7120 (a file in src/pages/api) and KR7125 (above) are not build errors
by themselves; the first warns, the second only appears in krate fix.
Stricter config handling can also fail a build that used to pass:
- A syntax error in
krate.config.*fails withfile:line:col, including in anextendsbase. Text afterexport default { ... }used to be ignored. checks.failOnaccepts only"error"or"warning"."off"is rejected; usechecks.enabled: false. Non-stringchecks.ignoreandchecks.customentries are errors.--config <path>fails when the file does not exist, on every command that takes it. It used to fall back to the defaults.viewTransitionsandpprnow take effect. They were ignored unless the config fell back to the static parser, so a setting left in a config can change output.
KR7140 (Tailwind input with Tailwind off) and KR7141 (unbalanced CSS) are new
warnings.
#spawn .../bin/krate EACCES on 0.5.0-beta.2
The 0.5.0-beta.2 platform packages were published without the executable bit,
so krate fails with EACCES on every Linux and macOS install, including Docker.
Windows is not affected. Upgrade to a later release, where the wrapper also
restores the bit itself, or stay on beta.2 and run this after installing:
chmod +x node_modules/@krate/core-*/bin/krate#bin/krate is gone from @krate/core
The @krate/core package no longer contains a compiler binary. In
0.5.0-beta.1 the tarball carried a stray single-platform bin/krate next to
the launcher (bin/krate.js), which made a clean install fail on Linux with
spawn .../bin/krate EACCES; the release now fails if a binary would be
published. The compiler comes from the @krate/core-<platform> package that npm
installs for your machine, and the launcher finds it under node_modules.
Nothing changes for krate ..., npx krate and package scripts. A script that
executes node_modules/@krate/core/bin/krate by path must call krate instead.
On npm 10 node_modules/.bin/krate could be missing after an install, because
the platform packages each declared bin and npm removes the shared link when
it rolls back the ones that do not match the machine. They no longer declare it;
the fix reaches you with the next release of the platform packages. Until then
run npm rebuild @krate/core or use npx krate. krate version reports the
native binary and warns when it differs from the npm wrapper.
#Server behaviour changes
These close holes; check them if you run krate serve behind a proxy or rely on
the old behaviour.
krate serveandkrate startrefuse to start when the build recorded middleware and.krate/middleware.jsis missing, so deploy.krate/withdist, or whenmanifest.json,server-manifest.jsonor.krate/api-routes.jsonis corrupt. Rebuild adistfolder made before this record existed; without it the server only warns.- A middleware module with a default export runs in every runtime. The Node, Bun
and Deno sidecars and the serverless adapters used to skip it, along with any
auth check inside it. One with no handler answers
503. - Middleware without a
matcherruns for every URL, including ones that end in a static extension (/api/files/report.pdf); only a real static file skips it. - With
server.trustProxy, the client IP is theX-Forwarded-Forentryserver.trustedProxieshops (default 1) from the right, not the leftmost entry. - The Node, Bun and Deno API sidecar answers only the Krate host; hitting its port directly is refused.
- Request headers are capped at 64 KiB; action cookies are
Secureover https; the no-JS flash cookie is signed; CORS responses carryVary: Origin. - A crashed SSR renderer restarts and pages answer
503until it is back, instead of serving the empty build-time shell. - A middleware or config rewrite to a page path without a trailing slash
(
/feedback) is served in place instead of answering301.
#Code blocks follow light and dark mode
<Code> and fenced code used to be dark in every mode. The default is now github
in light mode and krate-dark (github-dark's syntax colours on Krate's neutral
surface) in dark mode, so code on a light page turns light. To keep one theme in
both modes, set it as a string:
export default defineConfig({ codeTheme: "github-dark" });codeTheme: { light, dark } picks one for each mode. An unknown theme name is now
reported as KR7150.
#Component tiers are enforced
serverDirsandruntimeDirswith relative paths never matched anything. They do now, so components in those directories become server or runtime components and get the checks below.- A hook, an
onClickor a classsetStatein a@server,@staticor@runtimecomponent used to build and do nothing. It now fails withKR7110: remove the tier, or move the interactive part into a client child. - Tiers that contradict each other, such as
// @runtimeabove@serveror@runtimein a*.server.tsxfile, fail withKR7115.
#Your own Link, Head or Image wins
A project component named like a built-in (Link, Head, Script, Style, Icon,
Image, Suspense, Slot) used to be replaced by it without warning. Your component
is now used. If you relied on the built-in, import it from @krate/runtime.
#Links add the base path
If your site has a basePath, <Link>, navigate(), krateRouter and
redirect() now add it themselves, so remove the prefix you wrote by hand:
<Link href="/docs/about">About</Link> // 0.4, with basePath: "/docs"
<Link href="/about">About</Link> // 0.5
They add it even to a path that already starts with it, because /docs/intro
can be a real route under basePath: "/docs". Do not pass location.pathname;
usePathname() returns the path without the prefix.
A path in site.url now sets the base path. If your site.url has a path and a
proxy strips it before Krate, set basePath: "/" to keep the site at the root.
Redirects add it too. Config redirects match and send paths under the base
path, and a root-relative Location from an API route, middleware or server code
gets the prefix. Drop the prefix there as well:
{ source: "/old", destination: "/docs/new" } // 0.4, with basePath: "/docs"
{ source: "/old", destination: "/new" } // 0.5
A rule that should point outside the base path takes basePath: false.
Plain <a href="/x"> and <img src="/x"> are not rewritten. They now give a
KR7144 warning under a base path.
#New in 0.5
@krate/ts-pluginis a new package: a TypeScript language-service plugin that silences thetscerrors tier decorators (@server,@client, ...) cause. The scaffold adds it todevDependenciesand"plugins": [{ "name": "@krate/ts-plugin" }]totsconfig.json, with a"typecheck": "krate typecheck"script. Upgraded projects work without it; add it if you use decorators.krate fix,krate config,krate migrate nextjs,krate typecheckandkrate startare new commands, anddev,serveandstarttake--portand--host.create-krate-apppins@krate/*to its own version instead oflatest.
#Prereleases
Prereleases are published under a dist-tag (e.g. beta):
npm install @krate/core@betaPin exact versions in production. Prereleases may change config or output between builds.
#Breaking-change checklist
When upgrading across a minor:
- Read the release notes (GitHub Releases for the tag) and
CHANGELOG.md, which lists Breaking changes first for each release. - Re-read Configuration for renamed/removed keys - Krate now warns on unknown config keys.
- Run
krate fix(a dry run) for source andtsconfig.jsonfixes it can make safely, thenkrate fix --apply. Regenerate types:krate types. - Run
krate build && krate check && krate typecheck. - Diff
dist/if output shape matters to you.
#Version compatibility
| Package | Requirement |
|---|---|
Node (npm wrapper, generateStaticParams, SSR and API sidecars; not needed for the config file) |
20+ |
| Bun or Deno (optional sidecar runtimes) | current |
| Go (to build the compiler from source) | see packages/compiler/go.mod |
| Browsers | see Browser Support |
#Rolling back
Pin the previous version explicitly:
npm install @krate/core@0.4.0 @krate/runtime@0.4.0 @krate/components@0.4.0If a build broke after an upgrade, delete stale caches and rebuild:
rm -rf dist .krateGoing back to 0.4 after krate fix --apply needs no undo: "baseUrl": "."
builds on both.
#Component library: namespaced parts
@krate/components uses a namespaced compound API: Tabs.Trigger,
Breadcrumb.List, Table.Row, Steps.Step, Form.Field, FileTree.Folder,
and so on. The older flat exports (TabsTrigger, BreadcrumbList, TableRow,
Step, FormField, FileTreeItem, ...) still work as deprecated aliases, but
prefer the namespaced form - it is what the docs and examples use.
Last updated: 2026-11-17
Contributors: Noinkin