Krate Docs

#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):

  1. Tier decorator on the declaration, see below:
    @server
    export default function Stats() { ... }
  2. Directive in source (first non-comment line):
    // @server
    // @runtime
    // @static
    
  3. File convention:
    • *.server.tsx -> server
    • *.runtime.tsx -> runtime
    • *.static.tsx -> static
  4. Config name list:
    serverComponents: ["DataTable"]
    runtimeComponents: ["AuthCheck"]
  5. Directory membership:
    serverDirs: ["src/components/server"]
    runtimeDirs: ["src/components/runtime"]
  6. 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 // @server comment at the top. The composition rules below apply.
  • On any other declaration it classifies only that component, so one file can mix tiers. @client is useful here, to opt one component out of a // @server file.
  • @runtime must be on the default export or the only exported component, because a runtime component is bundled per file.
  • On an async component only @runtime is 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 / // @client comment,
  • the .server / .runtime / .static part of the file name,
  • the serverComponents and runtimeComponents config lists (by name or path),
  • the serverDirs and runtimeDirs config 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 time props.children is undefined.
  • In the browser props.children is a function returning an array of the children as h() descriptors, evaluated in the caller's scope: reactive props are thunks (position: () => [n(), 0, 0]), {cond && <x />} is a thunk, .map() is a krateList(...) value (its items, key, render and mode fields let the renderer reconcile it), and components are called with getter props. Event handlers (on*) and ref are 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 async and cannot be static, server or runtime, whichever way that tier is written (decorator, body directive, // @tier comment, file name or config list); that fails with KR7117. @renderer with @client is fine. A project decorator named renderer on 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