#Async Server Components
Async components that fetch data per request, and "use client" boundaries inside them.
An async function component is a server component. It can await
anything (fetch, a database client, cookies()), renders per request in the
SSR sidecar (Node, bun or deno), and never ships JavaScript to the browser.
No directive is needed: async is the marker.
// src/pages/post/[slug].tsx
import { cookies, notFound } from "@krate/runtime/server";
export default async function Post({ params, searchParams }) {
const { slug } = await params; // `params.slug` works too
const post = await fetch(`https://api.example.com/posts/${slug}`).then((r) => r.json());
if (!post) notFound();
const theme = (await cookies()).get("theme")?.value;
return (
<article class={theme}>
<h1>{post.title}</h1>
<Comments id={post.id} />
</article>
);
}
async function Comments({ id }) {
const list = await fetch(`https://api.example.com/comments/${id}`).then((r) => r.json());
return <ul>{list.map((c) => <li>{c.body}</li>)}</ul>;
}#Async pages
When the page component itself is async, the whole page body renders per request:
- The page is SSR, or ISR when it sets
export const revalidate = 60(orexport const config = { isr: true, revalidate: 60 }). - The static shell contains the layout around an empty page region; there is no build-time body and no hydration script.
- Async children render at any depth. Siblings resolve in parallel and
<Suspense>renders its resolved children (the response is sent when the page has rendered).
#Async children of a static page
An async component used from a synchronous page becomes its own request-time
region. The rest of the page is baked into the static shell at build time, and
the page is served in streaming mode ([KR7104] says so in the build output).
Inside <Suspense fallback>, the fallback is baked into the shell and
replaced by the rendered component.
Because the shell is built once, the props of such a component must be known at
build time (literals or module constants), and it cannot receive children
([KR7105]). Make the page async when the props come from request data.
#Request APIs
These come from @krate/runtime/server and work while a server component
renders (and inside server actions):
| API | Behavior |
|---|---|
params, searchParams props |
Plain objects that can also be awaited (await params), as in Next.js 15 |
headers() |
Request Headers; also awaitable |
cookies() |
Read-only view: get(name) returns { name, value }, plus getAll() / has(); set() throws during a render |
notFound() |
Stops rendering and answers 404 (the custom 404 page when present) |
redirect(url) |
Stops rendering and redirects |
fetch |
The runtime's fetch |
#Errors
An error thrown by a server component (or a failed fetch) answers 500
with the X-Krate-Error: render header and the custom 500.html when the
project has one. A server component never renders as an empty string, and the
synchronous renderToString throws if it meets a Promise.
#Client components inside server components
A module that starts with "use client" is a client boundary. When a server
component renders one of its exports, the server renders its initial HTML
into a <krate-island> element, with the serialized props in a
<script type="application/json"> just before it, and a small per-module
chunk hydrates it in the browser:
// src/components/Counter.tsx
"use client";
import { useState } from "react";
export default function Counter({ start, children }) {
const [n, setN] = useState(start);
return <div><button onClick={() => setN(n + 1)}>{n}</button>{children}</div>;
}// src/pages/index.tsx
import Counter from "../components/Counter";
export default async function Home() {
const start = await getStartValue();
return <Counter start={start}><ServerNote /></Counter>;
}- Client components run with React semantics through Preact (the same engine
as external React islands), so the
project needs
preactinstalled (pnpm add preact). - Props must be serializable, as in React Server Components: strings, numbers
(including
NaN,Infinityand-0), booleans,null,undefined,bigint,Date,Map,Set, typed arrays,ArrayBuffer,DataView,Symbol.forsymbols, plain objects and arrays. They arrive in the client component as the same types, so a database row can be passed as it is. Server actions may be passed and stay callable. A function, class instance or unregistered symbol fails the build when it is written inline ([KR7111]) and fails the request with the prop name otherwise. childrenpassed from a server component are rendered on the server, in place, inside the client component's HTML. So is any other prop that holds JSX, such asuserMenu={<UserMenu user={user} />}or an array of elements (a slot), and a client component inside a slot becomes its own island. The props carry only a reference to each slot: when the client component hydrates it adopts the server-rendered nodes where it renders the slot, so the children are in the page once, re-renders leave them in place, and a slot the component hides and shows again gets the same nodes back (with any islands inside them still running). A slot the server did not render, such as the content of a closed dialog, is sent as HTML in the props, and so are the server parts of a real-React island's children, since nothing renders them on the server. Each island's props are in the document once, however deep it is nested. JSX nested inside a plain object cannot be sent.- The child of a client component with
asChild(a RadixSlot, as in a shadcn<DropdownMenuTrigger asChild><Button>...</Button></DropdownMenuTrigger>) arrives as an element it can clone, as in Next.js, so the trigger's handlers, ref and ARIA props land on the button. A server component at the top of that child (a directive-lessButton) is run on the server to the element it renders, and client components in its output (anAvatar) render inside the same island instead of as islands of their own. Server components deeper inside it are still sent as HTML. A child that can only be sent as HTML (raw HTML) cannot receive props; the server logs a warning naming the component. - Context from a client component reaches the client components inside its
server children, as in Next.js. A root layout that renders
<Providers>{children}</Providers>(a"use client"module with a theme, a RadixTooltipProvideror a query client) gives every client component of the page that context, also across server components in between, and a provider whose value is state updates them when it changes. The server renders them inside the same context. Each nested component is still its own island: one on Preact shares the provider's instances, and a real-React island (one that reaches a reconciler library such as@react-three/fiber) gets its own copy of each context with the provider's current value. Not carried: context from a provider that is itself a real-React island, and, into real-React islands, contexts created while rendering. - Only what a client component imports and uses goes to the browser, as in
Next.js. A server helper (database client,
node:crypto, a native package) that sits in the same barrel as the component, or in a module the component never calls, stays out of the client chunks. If client code does use Node built-ins or a.nodeaddon, the build stops with KR8009. lazy(() => import("./heavy"))in a server component renders the module on the server, in place; no browser chunk is made for it.process.envreads in modules only the server tree uses are real, so KR8310 only fires for modules a client component bundles.- Pages without server components are unaffected: there,
"use client"changes nothing and components compile through the normal Krate pipeline.
#Compiled React packages in server components
Components from npm packages built on React (lucide-react icons, Radix
primitives, shadcn-style wrappers around them) work in async pages, async
layouts and async components. Krate treats such a package like Next.js treats a
package with a "use client" directive: its components are client boundaries
in a server tree, rendered with Preact on the server and sent as HTML.
import { Loader2 } from "lucide-react";
import { Dialog } from "radix-ui";
import { Checkbox } from "../components/ui/checkbox"; // wraps a Radix primitive
export default async function Settings() {
const prefs = await loadPrefs();
return (
<main>
<Loader2 className="spin" />
<Checkbox defaultChecked={prefs.email} />
<Dialog.Root>
<Dialog.Trigger>Delete</Dialog.Trigger>
<Dialog.Portal><Dialog.Content>...</Dialog.Content></Dialog.Portal>
</Dialog.Root>
</main>
);
}- A component without state or effects (an icon) renders to plain HTML and ships no JavaScript, in any tier.
- A component with state or effects (a checkbox, a dialog) becomes a
<krate-island>that hydrates in the browser, like a"use client"component. Its chunk is built from just the exports the page uses, so a barrel such as lucide-react does not pull in every icon. - Parts of one compound component keep their context:
Dialog.TriggerandDialog.Contentwritten insideDialog.Rootrender in the same Preact tree as the root, so they hydrate and talk to each other. Server components placed between the parts are rendered to HTML, so the parts on either side of one become separate islands, which still see the root's context. - Props follow the
"use client"rules: serializable values (see above) and server actions, no inline functions ([KR7111]). Put handlers in a"use client"wrapper, as in Next.js. - A local module that renders such components needs no directive unless it
uses hooks or event handlers. Calling a hook of an npm React library
(zustand, react-hook-form, swr, ...) outside a
"use client"module is[KR8013]. - The global
<Link>works in server components, async layouts and inside"use client"modules.
The bundle cost is the Preact runtime (shared across pages) plus the chunks of the islands a page actually renders. A page with only icons and server components ships none of it.
#Async layouts
A layout may be async. It renders per request in the SSR sidecar, so it can
await a session or flags and gate its subtree:
// src/pages/admin/_layout.tsx
import { redirect } from "@krate/runtime/server";
export default async function AdminLayout({ children }) {
const user = await getSession();
if (user?.role !== "admin") redirect("/login");
return <section class="admin">{children}</section>;
}redirect(),notFound(),forbidden(),cookies()andheaders()work in a layout exactly as in an async page, and stop the whole subtree.- The page and every layout between it and the outermost async layout render per request as one tree. Layouts above the outermost async layout stay baked into the static shell. Pages outside the async layout's directory stay static.
- Every page under an async layout therefore renders per request (SSR, or ISR
when it sets
revalidate), whether or not the page is itself async, and the build prints which pages that applies to. Pages and layouts inside it follow the server component rules: interactive parts go in"use client"modules ([KR7110]). - An
error.tsxbetween the page and an async layout is the error boundary of that page, as in Next.js. When the page (or a layout below the boundary) throws while rendering, the response is500withCache-Control: no-store(so no CDN keeps it or crawler indexes it) and the error page rendered inside the async layout, and the error page hydrates soresetworks (it reloads the page). The error prop is{ name, message, digest }with a generic message; the real error and its stack go to the server log with the same digest.redirect(),notFound(),forbidden()andunauthorized()are not caught. The async layout itself sits outside the boundary: if it throws, the error goes to the nexterror.tsxabove it (or the500page). - A
template.tsxbetween the page and an async layout is[KR7101]: it hydrates in the browser. Put it above the async layout. - Layouts below an async layout are not kept mounted across client-side navigation; the router replaces the whole request-time region.
#Server-only code
Inside a server tree, hooks (useState, useEffect, useContext, ...),
Krate signals and event handlers are build errors ([KR7110]): add
"use client" to the module that needs them. import "server-only" and
import "client-only" are accepted markers; a "use client" module that
reaches a server-only module (directly or through its imports) fails the
build ([KR7112]). In every server context (SSR bundles, route handlers,
server actions, middleware, and the build-time passes for metadata routes,
generateMetadata and generateStaticParams) server-only is a no-op, so the
npm package's "cannot be imported from a Client Component module" error never
fires there. client-only is a no-op everywhere: Krate does not report it when
a server context imports it.
#Error boundaries and streaming
A class error boundary around server components catches a failed child render
and renders its fallback on the server instead of answering 500. The boundary
receives the error through getDerivedStateFromError and may call
componentDidCatch for logging.
Sibling <Suspense> regions stream as they finish. The shell and fallbacks are
sent immediately, each region chunk inserts itself at its marker, and page
hydration scripts run after every chunk, so a slow region never blocks the rest
of the page. Nested boundaries and coarse SSR/ISR page regions stay on the
ordered path because they carry status or contain child markers. See
head tags in request-time pages for head tags set
inside a streamed region.
#Head tags in request-time pages
<title>, <meta>, <link> and <script> inside <Head> of an async page or an
async component are in the <head> of the first bytes of the response (SSR, ISR,
streaming pages and async components alike, in krate start and on the serverless
targets), so crawlers and social scrapers that do not run scripts read them:
export default async function Post({ params }) {
const { slug } = await params;
const post = await getPost(slug);
return (
<main>
<Head>
<title>{post.title}</title>
<meta name="description" content={post.summary} />
<meta property="og:image" content={post.image} />
<link rel="canonical" href={`https://example.com/blog/${slug}`} />
<script type="application/ld+json">{JSON.stringify(post.jsonLd)}</script>
</Head>
<h1>{post.title}</h1>
</main>
);
}- A tag of the page replaces a baked tag with the same key:
meta name,meta property,meta http-equiv,meta charset,link rel="canonical"andbase(a layout's orheadconfig's description loses to the page's). Severalpropertytags of the page (og:image,article:tag) all stay; a repeatedname,canonicalorcharsetkeeps the last one. - A tag identical to one already in the head is not added twice. Only
meta,link,base,script,styleandnoscriptare head content; anything else inside<Head>is dropped. Attribute values are escaped, and the text of a<script>or<style>is written as is (so JSON-LD stays valid JSON), with</scriptneutralised. - The title replaces the baked
<title>, or is added when the shell has none. - A
<Head>inside a<Suspense>region that streams out of order runs after the head was sent. Its tags are applied by the region's script, which a crawler that does not run scripts never sees, and the server logs a warning once per region. Put SEO tags in the page component outside<Suspense>. A region that is not streamed out of order (ISR pages, nested boundaries, a bare async component) gets its tags into the initial head.
#Not supported
| Pattern | Result |
|---|---|
template.tsx or error.tsx below an async layout |
Build error [KR7101] |
Server components with output: "static" |
Build error [KR7103] |
Module-level await in a page rendered at build time |
Build error [KR7102] |
async components in a "use client" module |
Build error [KR7113] |
export * from in a "use client" module |
Build error [KR7114] |
| Client-side (SPA) navigation into a page with islands | Not covered: the island loader runs on full page loads |
See the diagnostics reference for every code.
Last updated: 2026-11-17
Contributors: Noinkin