#Component Tiers
Static, client, server, and runtime components - where each runs.
Components are classified into four tiers that determine how they're rendered and how much JavaScript reaches the client.
| Tier | Client JS | Rendering |
|---|---|---|
Static (@static) |
None | Evaluated at build time; output is pure HTML |
| Client (default) | Yes (hydration) | SSG + client hydration |
Server (@server) |
None | Evaluated at build time; HTML output only |
Runtime (@runtime) |
None | Rendered at request time by the sidecar and spliced into the static shell |
#Detection priority
The tier is resolved in this order (highest wins):
- Tier decorator on the declaration, see below:
@server export default function Stats() { ... } - Directive in source (first non-comment line):
// @server // @runtime // @static - File convention:
*.server.tsx-> server*.runtime.tsx-> runtime*.static.tsx-> static
- Config name list:
serverComponents: ["DataTable"] runtimeComponents: ["AuthCheck"] - Directory membership:
serverDirs: ["src/components/server"] runtimeDirs: ["src/components/runtime"] - Default -> client.
An async component is always a runtime component, whatever else it says. That
includes an async layout, which renders per request together with the page
below it (see Async layouts).
Only one source may name a tier for a component. When two of them name different tiers the build fails with KR7115 instead of picking one; see Tiers that disagree.
#Tier decorators
@server, @static, @runtime and @client can go directly on a component.
They work on functions, classes and consts, which ordinary JavaScript decorators
do not, because Krate removes them at compile time. Nothing runs at load time.
@renderer uses the same syntax but is not a tier: see
Renderer components.
import { Component } from "react";
@static
const Badge = ({ label }) => <b>{label}</b>;
@server
class Report extends Component {
render() {
return <table>...</table>;
}
}
@server
export default function Dashboard() {
return <main><Badge label="New" /><Report /></main>;
}- On the default export, or on the only exported component of a file, the
decorator classifies the whole file, exactly like a
// @servercomment at the top. The composition rules below apply. - On any other declaration it classifies only that component, so one file can
mix tiers.
@clientis useful here, to opt one component out of a// @serverfile. @runtimemust be on the default export or the only exported component, because a runtime component is bundled per file.- On an
asynccomponent only@runtimeis accepted.
A decorator above export default () => <div /> or export default memo(...)
(also forwardRef(...)) applies to the file's default component, like one above
export default function. Other misplaced decorators fail the build with
KR7115; for a default export of any other
expression, name the component (@client above const View = ...;, then
export default View;). If your project already imports its own decorator named
server or client and applies it to a class, that one is used instead.
A decorator can also go on a higher-order component application. @server
above export default withBox(Inner) classifies the file's default component and
the wrapper is applied, whether withBox is declared in the same module or in
another one of your modules. export default memo(Inner) and
export default forwardRef(Inner) name Inner as the default component. A wrapper
Krate cannot inline (one imported from a package, or one with statements besides
the component it returns) fails the build with
KR8030, since the component would otherwise
render nothing.
#Tiers that disagree
These sources name a tier for a whole file, and must all agree:
- the leading
// @server/// @static/// @runtime/// @clientcomment, - the
.server/.runtime/.staticpart of the file name, - the
serverComponentsandruntimeComponentsconfig lists (by name or path), - the
serverDirsandruntimeDirsconfig lists (paths are relative to the project root).
A tier written on a component, as a decorator or as a "@server" string at the top
of its body, must agree with the other one on that component, and a tier on the
file's default export or on its only exported component must also agree with the
file-wide sources above, because it classifies the whole file.
A decorator on any other component overrides the file's tier for that component
alone. This is how @client opts one component out of a // @server file:
// @server
@client
function LikeButton() { /* useState, onClick */ }
export default function Post() { return <article><LikeButton /></article>; }Everything else is a contradiction and fails with KR7115: // @runtime above
@server, @runtime in Card.server.tsx, @runtime on a component listed in
serverComponents, @client on the default export of a // @server file, or
@static together with a "@server" directive in the same function. Remove one
of the two.
#Build-time tiers have no JavaScript
Server, static and runtime components render to HTML and ship no JavaScript, so state, effects, class state and lifecycles, and event handlers cannot work in them. They fail the build with KR7110, naming the hook or handler, instead of producing a button that does nothing. Either remove the tier from the component, or move the interactive part into a client child:
// @server
import LikeButton from "./LikeButton"; // no tier marker: a client component
export default function Post() {
return <article><h1>Static</h1><LikeButton /></article>;
}#TypeScript
To TypeScript these are errors, since it does not know they are compile-time
only. Scaffolded projects handle that for you: npm run typecheck runs
krate typecheck, which leaves them out, and
@krate/ts-plugin does the same
in editors.
Plain tsc --noEmit still reports them. If you have to run it, add a comment on
the line above each decorator:
// @ts-expect-error tier decorator
@server
export default function Stats() { ... }A // @server comment or a *.server.tsx file name needs neither, and classifies
the whole file.
#Renderer components
@renderer marks a component that hands its children to a non-DOM renderer in
the browser, such as a three.js scene graph (see @krate/three).
It goes on a function, const or default export like the tier decorators, and
Krate removes it at compile time:
import { onMount } from "@krate/runtime";
import { createRoot } from "@krate/three/engine";
@renderer
export function Canvas(props: { children?: unknown }) {
let canvas: HTMLCanvasElement | undefined;
onMount(() => createRoot(canvas!).render(props.children as () => unknown[]));
return <div><canvas ref={canvas} /></div>;
}A "use renderer" (or "@renderer") string at the top of the body does the
same. A renderer component is a client component:
- Its own body renders and hydrates as usual. Its call-site children are never
rendered to HTML and get no hydration bindings, so any lowercase tag, camelCase
or dash-case prop (
position-x) and any value (new Vector3(), a function) is accepted there. At build timeprops.childrenis undefined. - In the browser
props.childrenis a function returning an array of the children ash()descriptors, evaluated in the caller's scope: reactive props are thunks (position: () => [n(), 0, 0]),{cond && <x />}is a thunk,.map()is akrateList(...)value (itsitems,key,renderandmodefields let the renderer reconcile it), and components are called with getter props. Event handlers (on*) andrefare passed as they are; every other function-valued prop is a thunk returning the function (attach: () => fn). - Components used in the children are declared in the caller's hydration scope.
- It cannot be
asyncand cannot be static, server or runtime, whichever way that tier is written (decorator, body directive,// @tiercomment, file name or config list); that fails with KR7117.@rendererwith@clientis fine. A project decorator namedrendereron a class is left alone.
#Browser code in a package: krate.vendor
A Krate package is compiled as Krate source. Code that must run as plain browser
JavaScript, such as a renderer's engine, is listed in its package.json:
{
"name": "@krate/three",
"exports": { ".": "./src/index.ts", "./engine": "./src/engine/index.ts" },
"krate": { "vendor": ["src/engine/"] }
}Each entry is a path prefix relative to the package directory (a trailing /
matches a whole directory). Imports of those files from client code, including
the package importing itself (@krate/three/engine), are bundled by esbuild
into the page script like an npm dependency, TypeScript included. A package that
both the page and a vendored file import, such as three, is bundled once. A
malformed list fails with KR7127.
#Composition rules
- Client components cannot import server/runtime components.
- Static components can be imported by anyone (they produce no client JS).
- Server/runtime components can import each other freely.
#Server components
// src/components/ServerTime.server.tsx (or: // @server)
export default function ServerTime() {
return <time>{new Date().toUTCString()}</time>;
}Server components are evaluated at build time. The HTML they produce is baked
into the page; they never ship JavaScript. new Date(), Date.now() and
Math.random() there mean the time of the build (see
Dates and times at build time).
An async server component (one that awaits) is rendered per request instead;
see Data fetching.
#Runtime components
// @runtime
export default function PriceTag({ price }) {
return <span>{formatCurrency(price)}</span>;
}Runtime components are compiled during the build into self-contained bundles
(dist/server-components/<Name>.runtime.js) that expose a __krate_render
render function. Their resolved props are baked into the page's region registry,
so the sidecar never re-derives them.
Each runtime component instance becomes a region of the page. At request
time the sidecar renders the region's bundle and the Go server splices the HTML
into the static shell at the component's marker (<!--region:...-->), streaming
as it resolves. Inside a <Suspense> boundary the fallback is what's baked and
shown until the region arrives (<!--suspense:...--> marker).
Pages that import runtime components are automatically treated as streaming (unless the page opts into ISR or SSR, whose per-request page region is the whole body).
Runtime components render on the server at request time - good for data that
changes, without sending JavaScript to the browser. Named exports are fully
supported, including arrow functions (export const Live = () => ...).
Compiled React packages (lucide-react, Radix) can be rendered from the runtime tier: stateless components become HTML, stateful ones become client islands inside the server-rendered output (see Compiled React packages in server components).
#Why tiers matter
Static and server components produce zero client JavaScript. Runtime components render on the server at request time - good for data that changes, without sending JavaScript to the browser. Client components get hydration so they can be interactive.
See Rendering for how tiers interact with SSG/ISR/SSR/streaming.
Last updated: 2026-11-17
Contributors: Noinkin