#React Compatibility
How Krate transpiles React source to signals, runs compiled React packages as Preact islands, and what is intentionally not supported.
Krate supports React in two ways:
- Source transpilation. Any file that imports from
react(or uses theReact.*namespace) is rewritten at build time to Krate signals and effects. There is no React runtime and no virtual DOM: the compiler rewrites imports and calls, then compiles the component like hand-written Krate code. - Islands for compiled packages. Packages that ship only compiled
JavaScript and were built against React (for example
@radix-ui/react-*) are bundled into a small, isolated Preact island, server-rendered where possible, and hydrated in place. See Compiled React packages.
This page covers both paths. For the current status of every surface and the tests backing it, see the compatibility matrix.
#Source transpilation
// You write React...
import { useState, useEffect, useRef } from 'react';
export default function Timer() {
const [seconds, setSeconds] = useState(0);
const intervalRef = useRef(null);
useEffect(() => {
intervalRef.current = setInterval(() => setSeconds(s => s + 1), 1000);
return () => clearInterval(intervalRef.current);
}, []);
return <p>Seconds elapsed: {seconds}</p>;
}// ...and the compiler emits the equivalent Krate code.
// useState -> createSignal useEffect -> createEffectDeps
// useRef -> { current: null } {seconds} -> seconds()
#Hooks
| React | Rewritten to |
|---|---|
useState |
createSignal(init, krateHookState) (React state snapshots; a lazy initializer useState(() => x) or useState(loadFn) is called once) |
useEffect |
createEffectDeps(fn, () => deps) (passive phase, see Effects) |
useLayoutEffect / useInsertionEffect |
createEffectDeps(fn, () => deps, 'layout' / 'insertion') |
useMemo |
createMemoDeps(fn, () => deps); without deps, createMemo |
useReducer |
createReducer(reducer, init(arg), krateHookState) (stable dispatch, Object.is bail-out) |
useRef |
{ current: initial } |
useCallback |
createCallbackDeps(fn, () => deps); without deps, the wrapped function |
useContext |
Context.useContext() |
useId |
a per-instance id shared by the HTML and the hydration code (see useId) |
useTransition |
a pending signal plus an async-aware startTransition (see Suspense) |
useDeferredValue |
a deferred getter (createDeferredValue) |
useSyncExternalStore |
a store getter (createExternalStore) |
useImperativeHandle / useDebugValue |
compat shim |
useEffectEvent |
a stable function over live state that does not subscribe its caller (see useEffectEvent) |
use |
use(promise) suspends the nearest <Suspense>; use(Context) is a context read |
Named imports, aliased imports (import { useState as state }), and the
React.* namespace all work:
import React from 'react';
export default function Counter() {
const [count, setCount] = React.useState(0);
return <button onClick={() => setCount(count + 1)}>{count}</button>;
}#Components and helpers
| React | Behavior |
|---|---|
forwardRef |
lowered: the ref parameter becomes props.ref, which binds at the rendered element |
ref as a prop (React 19) |
supported: function Input({ ref, ...p }) { return <input ref={ref} {...p} /> } needs no forwardRef |
createRef |
lowered to { current: null } |
useImperativeHandle |
attaches the handle before effects run; re-created when a dependency changes, detached on unmount |
createContext |
supported: <Ctx.Provider value>, React 19 <Ctx value>, <Ctx.Consumer>{(v) => ...}</Ctx.Consumer>, any constant default (objects included), provider values that change at runtime, and nested or self-nesting providers (see Context) |
createElement |
lowered to h |
memo |
identity (components already run once) |
lazy |
rendered at build time; its hydration code is a separate chunk (see Suspense) |
Suspense |
a real boundary: fallback while anything inside is pending |
<Fragment> / <React.Fragment> |
a JSX fragment |
react/jsx-runtime, jsx, jsxs, jsxDEV |
lowered to Krate JSX |
react-dom / react-dom/client |
createPortal and flushSync map to the compat runtime; useFormStatus and requestFormReset are supported; findDOMNode, render, hydrate and unmountComponentAtNode (removed in React 19) report KR8001 |
Children.only / toArray / count |
folded at build time on literal input, otherwise compat shim |
Children.map |
folded at build time for a literal list and inline arrow, including props.children of a call site written with literal elements (Tabs / RadioGroup); otherwise compat shim |
cloneElement |
folded at build time on a literal element and props, otherwise compat shim |
isValidElement |
folded at build time on literal input, otherwise compat shim |
createPortal / <Portal> |
mounted into its container after hydration (see Portals) |
<title> / <meta> / <link> (React 19) |
hoisted into <head> (see Document metadata) |
Component / PureComponent |
lowerable class components (see below) |
useActionState |
lowered to signals: [state, formAction, isPending], sequential queue, previous state sent to server actions, no-JS fallback with permalink |
useOptimistic |
lowered to signals: updates apply while an action is pending and revert when it settles |
useFormStatus |
form-scoped status (pending, data, method, action) of the form containing the component |
<form action={fn}> / formAction={fn} |
server actions and client functions, run in an async transition without a page reload, form reset on success |
StrictMode / Profiler |
render their children; Profiler's onRender is never called (warning KR4005) |
<Activity mode> |
children render in a wrapper that hides them while keeping their state; effects clean up while hidden (see Activity) |
<ViewTransition> |
names its element child for view transitions (see ViewTransition) |
<SuspenseList> |
renders its children; revealOrder and tail are ignored (warning KR8031) |
cache |
identity: Krate renders each page once |
flushSync |
flushSync(fn) is fn(): state changes already apply synchronously |
useFormState (react-dom) |
useActionState |
preload, preinit, preconnect, prefetchDNS, preloadModule, preinitModule (react-dom) |
add the <link> or <script> to the document head once per URL: on the server as a tag in the <head> of the response (also from islands and client components the server renders), in the browser only when the document does not have it yet (see Resource hints) |
version, captureOwnerStack |
"19.2.0" and null (as in production React) |
| custom element props | strings, numbers and booleans are attributes; objects, arrays and functions are properties (see Custom elements) |
#Class components
Classes extending Component or PureComponent are lowered at build time:
render() becomes the component body (so the page is rendered to HTML at
build time), and a small runtime instance provides this. The semantics
follow React 18:
- Updates are batched.
this.setState(partial | updater, callback)andthis.forceUpdate(callback)queue an update;this.statechanges when it commits. Updaters run in order with(state, props). - Render and commit phases. An update recomputes props and state,
applies
static getDerivedStateFromProps(props, state)(also before the first render), asksshouldComponentUpdate(nextProps, nextState)(or compares shallowly forPureComponent), callsgetSnapshotBeforeUpdate(prevProps, prevState)before the DOM changes, then writes the DOM.componentDidUpdate(prevProps, prevState, snapshot)and setState callbacks run after the DOM is updated, children before parents. A skipped update still updatesthis.props/this.stateand runs the callbacks, as in React. - Props are live. A parent's state change reaches
this.propsand triggerscomponentDidUpdate. A class re-renders when the component that created it re-renders (unless it bails out), but not when it was passed in asprops.children. - Mounting follows conditionals. A class inside
{show ? <Child/> : null}mounts when the branch is shown and unmounts (componentWillUnmount, parent first) when it is hidden; showing it again creates a fresh instance with fresh state. Components in an initially hidden branch do not mount until it is shown.cond ? <Child a/> : <Child b/>is one instance whose props switch (see Effects). - Also supported:
static defaultProps,static contextTypewiththis.context, getters and setters, private#members, class fields and arrow handlers, instance fields assigned in any method (this.timer = ...),componentWillReceiveProps/componentWillUpdateand theirUNSAFE_forms (skipped whengetDerivedStateFromPropsorgetSnapshotBeforeUpdateis defined, as in React), and refs:<MyClass ref={r}/>setsr.currentto the instance (with its public methods) aftercomponentDidMountand tonullbeforecomponentWillUnmount. - Render locals stay reactive.
const { count } = this.stateand other render locals derived from state or props are recomputed by every binding.
Rejected with a coded warning (the component renders nothing):
UNSAFE_componentWillMount (KR3005), legacy contextTypes (KR3006), other
static members and static blocks (KR3003), computed member names (KR3004),
this inside a static lifecycle (KR3007), and this.<name> reads of
properties nothing defines, such as string refs (KR3002).
Pages that render a class component hydrate through an owner tree (one owner
per component instance) that routes errors to boundaries and mounts and
unmounts components with their conditional branch, with the same fresh-state
remount semantics as other pages. A class's render() body is evaluated once
per mount (bindings update afterwards), so side effects inside render(), such
as logging, run fewer times than in React.
React's Component/PureComponent from @krate/runtime/react, rendered with
createElement at runtime, use the same instance controller. Compiled npm
packages run on Preact inside islands and keep Preact's class semantics.
Code that runs on Preact (a "use client" module, an island, an npm package)
gets the React 19 APIs Preact's compat layer lacks from react:
useOptimistic, useActionState, use (promises and context), cache and
useEffectEvent, plus useFormStatus, useFormState and requestFormReset
from react-dom. startTransition and useTransition accept async functions
and keep optimistic updates applied until the promise settles. A function
passed as <form action> or formAction runs on submit with the form data and
resets the form on success. useFormStatus reads the status of a form that the
same Preact tree renders, not of a form rendered by a server component around
the island, and use(context) must be called unconditionally.
#Error boundaries
A class with static getDerivedStateFromError(error) and/or
componentDidCatch(error, info) is an error boundary:
class ErrorBoundary extends Component {
state = { error: null };
static getDerivedStateFromError(error) { return { error: error.message }; }
componentDidCatch(error, info) { report(error, info.componentStack); }
render() {
if (this.state.error) {
return <button onClick={() => this.setState({ error: null })}>Try again</button>;
}
return this.props.children;
}
}- What is caught mirrors React: errors thrown by descendants while they
hydrate, while a binding re-renders, in a render-time guard
(
if (this.state.n === 5) throw ...re-checks on every update), in lifecycles and in effects. Errors in event handlers, timers and promises are not caught. - On an error the boundary unmounts its whole subtree (cleanups and
componentWillUnmountrun for components that had mounted), renders the state fromgetDerivedStateFromError, then callscomponentDidCatch(error, { componentStack })after the fallback is in the DOM. Caught errors are logged withconsole.error, like React. - Recovery. When the boundary renders its children again (for example
after
setState({ error: null })), the children mount fresh. Changing a class element'skey(<ErrorBoundary key={attempt}>) unmounts it and mounts a new instance with fresh state. - Render retry. As in React 18, an error thrown while rendering during an
update is retried once before the fallback commits, so
getDerivedStateFromErrorruns twice for it (once for errors in effects and lifecycles). - Nesting. The innermost boundary catches. An error thrown by a boundary's own render or fallback goes to the boundary above it.
- At build time a
throwwhile the page is rendered inside a boundary renders the boundary's fallback instead of failing the build (warning KR3009), andcomponentDidCatchis called when the page hydrates. Retrying after a build-time error renders an empty children region, because the subtree could not be built; rebuild once the data is fixed. A build-time throw with no boundary fails the build (KR3010). - Without
getDerivedStateFromErrorthe subtree is unmounted but its last DOM stays untilcomponentDidCatchcallssetState(warning KR3008). - Uncaught errors. React 18 unmounts the whole root. Krate keeps the server-rendered page, logs the error with its component stack, and unmounts only the component that threw (and its descendants).
- Errors in a hidden conditional branch's bindings (which React would never
have rendered) are ignored. Each Preact island has its own error boundary;
a render failure shows a fallback in the island placeholder and sets
data-krate-island-error.
#Context
Context is resolved where a component is rendered, as in React: a read sees the
nearest provider above it, including providers that a parent component wraps
around {props.children} (<Level><Level /></Level> nests). A provider whose
value is a build-time constant is folded into the static HTML; a value that
reads state is passed to the readers as a getter, so every consumer updates
when it changes. Without a provider, readers get the createContext default.
const Theme = createContext("light");
function ThemeBox(props) {
const [dark, setDark] = useState(false);
return (
<Theme value={dark ? "dark" : "light"}>
<button onClick={() => setDark(!dark)}>flip</button>
{props.children}
</Theme>
);
}
<ThemeBox>
<Theme.Consumer>{(theme) => <p>{theme}</p>}</Theme.Consumer>
</ThemeBox>A Consumer child must be a single render function with a plain parameter
(or a { a, b } pattern), otherwise the build reports KR8004. Legacy context
(contextTypes, childContextTypes, getChildContext) was removed in
React 19 and reports KR8005.
#Portals
createPortal(children, container) (and the built-in <Portal container>)
renders its children in the component's place in the tree and moves them into
the container once the page hydrates; like React, the portal content is not
part of the server-rendered HTML. The container can be document.body,
document.getElementById("id"), document.querySelector("selector") or any
expression the component can evaluate in the browser (a container that cannot
be resolved reports KR8006 and falls back to document.body). React events
bubble from portal content to the component's ancestors, a portal inside a
conditional branch mounts and unmounts with the branch ({open && createPortal(...)} and {open ? createPortal(...) : null} both work), and its
content is removed when the component goes away. A createPortal call anywhere
else, such as inside a .map() callback, is not lowered and reports KR8010.
#Document metadata
As in React 19, a <title>, <meta> or <link> rendered anywhere in a
component is placed in the document <head>. A <title> that reads state
keeps document.title up to date; reactive <meta content> and <link href>
update in place. Identical elements (the same stylesheet rendered twice) are
emitted once, and <link rel="stylesheet"> is hoisted only with a
precedence, as in React. Elements inside <svg>, with an itemProp, or
inside a conditional branch or list item stay where they are rendered.
<Head> keeps working and is the way to set head content from layouts.
#Bare reads are auto-called
React reads a value directly ({count}); Krate signals are getters (count()).
The compiler bridges the difference by rewriting bare value-position reads to
calls, so unmodified React works:
const [count, setCount] = useState(0);
return (
<div>
<span>{count}</span> {/* -> count() */}
<span>{count + 1}</span> {/* -> count() + 1 */}
<span>{`n=${count}`}</span> {/* -> `n=${count()}` */}
<button onClick={() => setCount(count + 1)}>
{/* -> setCount(count() + 1) */}
Increment
</button>
</div>
);The rewrite is scope-aware: it never touches shadowed locals, function
parameters, setters, or values that are already called. Krate-native
createSignal code (which already writes count()) is left untouched.
#Values computed during render
React recomputes everything in a component body on each render. Krate runs the body once, so a body value that depends on state, props or context is compiled to a lazily recomputed derived value, and its reads are auto-called like state reads:
const [todos, setTodos] = useState(initial);
const [filter, setFilter] = useState("all");
const visible = todos.filter((t) => filter === "all" || t.done === (filter === "done"));
const left = todos.filter((t) => !t.done).length; // always current
const label = left === 1 ? "item" : "items";This covers plain const/let bindings, destructuring (const { a, b } = obj), values derived from other derived values, props.x reads in components
that take a props parameter, and a let built up by later body statements
(let cls = "a"; if (on) cls += " b";). Values that read nothing reactive stay
plain constants. A binding that cannot be recomputed safely (reassigned inside a
handler, or built by statements that also write other variables) keeps its
first value and is reported as KR8301. See
Reactivity.
#Custom hooks
A custom hook is an ordinary function that runs once per component instance,
so its own state and effects belong to that instance. When it returns a value
that depends on its state (return [on, toggle], return { value, setValue }),
the result is a derived getter, and the call site reads it like any other
derived value:
function useToggle(initial: boolean) {
const [on, setOn] = useState(initial);
const toggle = useCallback(() => setOn((v) => !v), []);
return [on, toggle] as const;
}
const [open, toggleOpen] = useToggle(false); // open is current, toggleOpen works
A project custom hook (declared in the module or imported from a relative
path) called with an argument that reads state or props gets that argument as
a live getter; the hook's plain parameters read through it, so
useDebounce(value, 300) and useDocumentTitle("count " + n) follow value
and n. A destructured hook parameter is read once, when the hook is called.
Hooks from packages are called with plain values. A hook that bumps a state it
never reads (const [, force] = useState(0) in a store hook) recomputes its
result when the bump happens.
An if at the top of a component or hook body that calls a state setter
(if (props.value !== prev) { setPrev(props.value); setChanges(changes + 1); },
React's "derive state from props" pattern) runs as an effect that re-checks the
condition when the state or props it reads change.
#Component patterns
These React patterns compile to live DOM, not a one-time snapshot:
- Destructured props (
function Label({ value, tone = "x", ...rest })) follow call-site changes; see Passing signals as props. - Function as children and render props:
<Toggle>{(on, flip) => ...}</Toggle>passes the function aschildren, andprops.children(on, flip)/props.render(n)render its result. Their markup is created in the browser, so the server HTML of that slot is empty. Children.map(props.children, (c, i) => cloneElement(c, {...}))unrolls over the elements the caller wrote. A child whose props read the caller's state is reported (the unrolled element would move into the wrong scope).- Higher-order components:
const Counted = withCounter(Button)wherewithCounterdeclares one inner function component and returns it compiles as that component with the wrapped component substituted. Wrappers with other statements, patterns or rest parameters are reported as unresolved. - Spread props:
<Inner {...props} />,<input {...field} />and conditional spreads apply their attributes and handlers, and re-apply them when the state they read changes. A component spread whose attributes are not known at build time (an arbitrary object) is reported and not passed. - JSX held in a variable (
const badge = on ? <b/> : <i/>, alet contentassigned in aswitch) renders and updates like an inline conditional. {n && <b/>}renders0forn === 0like React, and{name || <i/>}rendersnamewhen it is truthy.dangerouslySetInnerHTMLthat reads state re-applies when it changes; SVG elements created at runtime (list rows, conditional<g>) keep the SVG namespace, and a<foreignObject>is HTML again.- Context in list rows: rows of a list inside
<Ctx.Provider value={...}>read the provider's live value. - Store hooks made by a module-level factory (
const useStore = create(...),const { api, useStore } = create(...)) run in the browser; the component that calls them renders its slot empty on the server.
#Context values
useContext(Ctx) returns the provided value itself (an object, a number),
never the getter that carries it from the provider: const { color } = useContext(Theme), log(theme) and [theme] dependency arrays behave as in
React, and consumers update when the provider's value changes, including
through intermediate components.
#Module-level state
A module evaluates once. A module-level constant created by code (const store = createStore(0)) is created once per page and shared by every component that
uses it, top-level statements that use it (window.__store = store) run once,
and helpers its initializer calls are bundled into the page script, including
helpers imported from other local modules. An imported binding that hydration
code needs but the compiler cannot copy (for example one bound by a
destructuring export) is reported as KR8302.
User bindings named like runtime helpers (h, findSlot, kbind*,
krate*) are renamed in the compiled output, so hits.map((h) => <li>{h}</li>)
works.
#useId
useId() gives every component instance its own id, and the id in the static HTML is
the one the hydrated page uses, so htmlFor/id and aria-* pairs match before
and after hydration. It works in the page, in child components (also ones with no
state, rendered once at build time), in nested children, in lists, when a component
is rendered more than once, in conditional branches and in layouts.
The ids look like krate-<component path>, not React's :r0:. A component in a keyed list
row takes krate-<list>:$<key>-u<n>, numbered in render order within the row, and
rows the client creates later number theirs the same way, so a row has the same ids
whether the server or the browser rendered it. A hook of your own that calls useId
works too, but its ids exist only after hydration (the HTML has no id yet).
#useEffectEvent
const onTick = useEffectEvent(() => log(count)) returns a function that always
runs the latest closure, so it sees the latest props and state, and the effect that
calls it does not depend on what it reads (React 19.2 semantics). Call it from
effects (or other effect events); it is lowered to createEffectEvent, which is also
in the compat runtime and the trimmed runtime.
#Activity
<Activity mode="visible" | "hidden"> renders its children inside a
<krate-activity> wrapper with display: contents. In hidden mode the wrapper is
display: none and:
- the children stay in the page and keep their state, including DOM state such as an input's text and scroll position,
- their effects are cleaned up when the mode becomes
hiddenand set up again when it becomesvisible, and effects do not run at all while the page loads hidden, modemay be a literal or any expression, and a missingmodemeansvisible.
Differences from React: there is a wrapper element (React adds none and hides the
children themselves), class components inside run their lifecycles as usual rather
than unmounting, and nothing is rendered at lower priority. Props other than mode
warn (KR8031).
#ViewTransition
<ViewTransition name="hero" default="slow-fade"> gives its first element child
data-view-transition="hero" and data-view-transition-class="slow-fade"; the
router turns them into view-transition-name and view-transition-class and runs
navigations inside document.startViewTransition, as it does for any element with
data-view-transition. Without name Krate generates one; default="none" turns it
off. Style the animation with ::view-transition-group(*.slow-fade). Children that
are not a host element are wrapped in a <div>, and only the first element child of
several is named. enter, exit, update and share classes and the onEnter,
onExit, onUpdate and onShare callbacks have no effect and warn (KR8031): put
the class in default and select the event in CSS. unstable_ViewTransition is
accepted too. The router needs spa and viewTransitions left on.
#Custom elements
As in React 19, <my-card title="x" count={3} open data={{ a: 1 }} onSelect={fn} />
renders title, count and an empty open attribute; false is omitted; and
objects, arrays and functions render no attribute at all (the server HTML used to
contain data="[object Object]"). The client sets those as properties on the element,
and again when the element class is defined after the page loaded, so a property
setter on the class sees the value. A component that renders such a prop is
hydrated even when it has no state, because nothing else sets the property.
#useReducer
useReducer maps to createReducer, which returns [getter, dispatch] -- the
same getter contract as createSignal, so it reacts and hydrates like any other
signal.
#Suspense, lazy, use() and transitions
Boundaries. <Suspense fallback={...}> (also React.Suspense or an
aliased import) shows its fallback while any component inside it is suspended
and reveals the content once everything inside has settled. Siblings under one
boundary reveal together, and a suspension counts only for the innermost
boundary around it, so an outer boundary keeps showing its content (with the
inner fallback). The fallback is rendered as normal Krate output and can be
interactive. As in React, a reveal that replaces a fallback waits until at
least 300ms after the most recent fallback appeared, so sequential and nested
reveals do not flash, and content that suspends again outside a transition is
hidden in place (display: none !important, with the fallback after it)
rather than removed, so its state and DOM nodes survive.
At build time a boundary renders its content when the content does not depend
on pending work. When a component inside it reads use(promise) or a
createResource, the promise cannot be resolved at build time: the page ships
the fallback, and the content waits (already rendered, with its value slots
empty) in a hoisted <template>. Hydration binds the content there and swaps
it in when the boundary has nothing pending. Effects of the content run in the
commit after it is revealed, and are cleaned up while the boundary shows its
fallback again (like a hidden conditional branch, see Effects). Request-time (runtime and server)
components inside a boundary keep using streaming regions.
In a "use client" component of a server-rendered page (a Preact island), the
island root is a boundary, as React's root is: a component that suspends with
no <Suspense> of its own (a lazy() component rendered after mount) keeps
the server HTML until it has loaded. A server render of such a component uses
the getServerSnapshot argument of useSyncExternalStore.
use(promise). Write it as the initializer of a declaration in the
component body:
function User({ userPromise }) {
const user = use(userPromise); // may be conditional: cond ? use(p) : null
return <p>{user.name}</p>;
}The value is reactive. While the promise is pending the component's hydration
is suspended (its boundary shows the fallback); when it resolves the component
runs again with the value. As in React, the same promise object never suspends
again once it resolved, a rejected promise is reported to the nearest error
boundary, and promises must be cached: a promise created during rendering is
reused by position when the component runs again, like React's replay. If the
promise changes later (for example a new promise in state), the boundary shows
its fallback again, except inside a transition, where the revealed content
stays and the transition stays pending until the new promise resolves.
use(Context) is a plain context read and works anywhere. The compiler
decides from bindings, not names: an argument bound to a createContext(...)
result, in the same module or imported from another bundled module, is a
context read (folded to its default at build time); anything else is treated
as a possible promise, and the runtime checks the context marker on Krate
context objects, so a promise named userContext suspends as expected.
use(promise) used
outside a declaration (KR4003) or destructured (KR4004) is a build error, and a
component calling it outside any <Suspense> gets warning KR4008.
lazy(). Declare lazy components at module level with a static import:
const Chart = lazy(() => import('./Chart'));
const Panel = lazy(() => import('./panels').then((m) => ({ default: m.Panel })));
const Editor = lazy(() => import('./editor').then((m) => m.Editor));Krate renders the HTML of a lazy component at build time like any other
component, so splitting its render code would save nothing. What is split is
its hydration code: the component's event handlers and bindings (and those
of its children) are written to lazy-<Name>.<hash>.js next to the page
script. As in React, the enclosing <Suspense> shows its fallback until the
component is ready: the build ships the fallback with the lazy content (already
rendered) in a template, and the chunk is loaded with a dynamic import when the
component first renders on the client, that is when the page hydrates, or when
a hidden branch holding it is first shown. The page links the chunk with
<link rel="modulepreload">, so its download overlaps the page load; it
still only runs when the component renders. The boundary reveals the content
once the chunk has run, so it is interactive from the first frame it is
visible.
A loader that is not a static import works too when it resolves to a local
component, for example lazy(() => delay(300, { default: Report })): the
loader runs when the component first hydrates and the boundary shows its
fallback until it resolves. The default export must be a component (KR4007);
a failed load is reported to the nearest error boundary. Other loaders are
rejected (KR4001), lazy() must not be called inside a component (KR4002),
and a lazy package import (import('some-package')) is compiled like a static import
(warning KR4006).
Transitions. useTransition() returns [isPending, startTransition].
isPending becomes true when a transition starts and stays true until the
action settles, including async actions and the work they await, and until
every overlapping transition started through the same hook settled. The
top-level startTransition accepts async functions too. Form actions,
useActionState dispatches and useOptimistic share this one transition
scope: optimistic values stay applied, and a Suspense boundary keeps its
revealed content, until every transition and action has settled. Updates made after an
await inside an action are ordinary updates, as in React 19; wrap them in
another startTransition to mark them.
useDeferredValue(value, initialValue?) returns a getter that keeps the
previous value during an urgent update and catches up in a later task (a
setTimeout(0) after the update). With initialValue (React 19) the first
value is initialValue and the real value follows the same way. Updates made
inside a transition are not deferred again.
useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?) returns
a getter. It subscribes once, re-reads the snapshot on every store
notification and once right after subscribing (so a change between the first
read and the subscription is not missed), stores a new snapshot only when it
differs by Object.is, and unsubscribes when the page is torn down. The build
renders getServerSnapshot (when it is an inline function) and the client
hydrates from getSnapshot. A getSnapshot that returns a new object on
every call logs a warning, as React does.
The compat runtime (@krate/runtime/react, used by code that is not lowered
at build time) implements the same semantics with render-time placeholders:
a component that suspends renders a placeholder that the nearest <Suspense>
claims, and the placeholder re-renders the component when its promise settles.
#Effects
Krate components run once, so there is no render for an effect to follow.
Each effect hook instead watches its dependency array: the compiler passes a
thunk (() => [a, b]) that the runtime re-reads whenever a signal it reads
changes, and the effect re-runs in the next commit when any element differs
by Object.is (so NaN equals NaN and +0 differs from -0). Setting
state to the value it already has (by Object.is) is a no-op: no binding or
effect re-runs.
State snapshots. useState and useReducer state follows React's
render snapshots. Outside rendering (event handlers, effect bodies,
cleanups) a state read returns the value of the last commit, so
setCount(count + 1) called three times in one handler adds one, while
functional updates (setCount((c) => c + 1)) always see the latest pending
value. Effect setups and cleanups read the state and props of the commit
they belong to: a cleanup sees the values of the render its effect ran for,
as a React closure would. Krate-native createSignal signals keep reading
their latest value.
Commit order. Signal writes are batched: every update made in the same
task produces one commit. Updates made while a discrete event (click, key,
input, change, submit, focus, ...) is dispatched are flushed synchronously
once all of that event's handlers ran: render, commit, layout and passive
effects complete before the browser event returns (React's synchronous
lane). Continuous events (mouse and pointer moves, scroll, wheel) keep the
normal batching. The updates an async action makes when it settles (its
result, the pending flags of useActionState and useFormStatus,
optimistic reverts) commit in a later task, like React's transitions, so
the pending render is on screen for at least one task. Like React's commit,
each commit reads document.activeElement, so a focused element the commit
disabled (a submit button with disabled={pending}) keeps or loses focus as
it does under React in each browser. An update made elsewhere (a timeout, a
promise callback) commits in a later task, after the microtasks queued with
it. A commit runs after the DOM bindings have been updated, in React's order:
- Mutation phase, per component: insertion-effect cleanup and setup, then layout-effect cleanup.
- Layout phase: layout-effect setups. This happens in a microtask, before the browser paints.
- Passive phase, in a later task (after paint): every passive cleanup, then every passive setup.
Within each phase, children run before parents and siblings in document order; effects of one component run in declaration order. Pending passive effects are always flushed before the next update is processed, as in React. A layout effect that sets state therefore re-commits before paint.
Dependency arrays.
| Pattern | Behavior |
|---|---|
[a, b] |
re-runs when a or b changes |
[] |
runs once after mount; its cleanup runs on unmount |
const deps = [a, b] in the same component |
inlined, same as [a, b] |
an expression (props.deps, cond ? [a] : [b], [...items, a]) |
evaluated live and compared at run time |
| a parameter or imported array | compared at run time, but the captured array never changes (KR2001) |
an inline function, object or array, or a local bound to one ([handler], [{ page }]) |
re-runs after every commit that changes the component's state or props, since React sees a new identity on every render |
omitted (or null / undefined) |
re-runs after every commit that changes the component's own state or props (KR2002) |
React re-runs a dependency-less effect after every render. Krate has no
re-renders, so it uses the closest observable equivalent: the effect's
dependencies are the component's useState/useReducer state and its props.
Re-renders caused only by a parent or a context change are not modelled; pass
an explicit array when that matters.
useMemo(fn, deps) recomputes synchronously, when it is read, after its deps
changed, so the value is current within the same update. useCallback(fn, deps) keeps one function identity until its deps change (so effects that
list the callback re-run exactly when React's would). useImperativeHandle
attaches the handle in the layout phase, re-creates it when its deps change,
and resets the ref to null on unmount.
Unmounting. When a list re-render removes a component, its cleanups run
parent before child (React's deletion order): insertion and layout cleanups
immediately, passive cleanups in the passive phase. A component inside a
conditional branch ({show && <Counter />}, cond ? <A /> : <B />) is
unmounted when the branch hides: its cleanups run, its refs and bindings are
released and its state is discarded. Showing the branch again mounts a fresh
instance, so state starts from its initial value and every effect runs
again, as in React. The branch's DOM nodes are reused and re-bound, so
uncontrolled DOM state inside them (typed text in an uncontrolled input,
scroll position) survives the toggle, which React would reset.
Same type in both branches. isEdit ? <Form mode="edit" /> : <Form mode="new" /> keeps one Form instance, as React does: the compiler lowers the
pair to <Form mode={isEdit ? "edit" : "new"} />, so flipping the condition
changes the props and leaves state, typed input, refs and mount effects alone.
Props set in one branch only switch to undefined in the other, differing
children switch with the condition, and chains (a ? <X/> : b ? <X/> : <X/>)
and early returns of one type (if (alt) return <X/>; return <X/>;) work the
same way. Only components that hold state are lowered; a stateless component
keeps its two branches, so its output does not change. Branches with different
key props (or a key on one side only) remount, as in React. When a pair
cannot be lowered, the build warns with KR8360 instead of resetting state
silently: render-prop function children, a ref or spread that differs between
the branches, a condition with side effects, a lazy component, or the same
component inside a wrapper element that each branch builds
(cond ? <div><X/></div> : <div><X/></div>). Render one element and pass the
differing values as props, or move the condition inside the wrapper.
Closures. Krate reads state through live getters, so a timer or promise callback created inside an effect reads the latest committed value when it runs, where React's closure would keep the value of its render.
Compiled packages and code the compiler could not lower use the same runtime
through @krate/runtime/react: useEffect, useLayoutEffect and
useInsertionEffect get their phases, and dependency elements that are state
getters are read live. There useMemo and useCallback compute once per
component, which is what React does when the deps never change.
#Effect diagnostics
| Code | Reported when | What to do |
|---|---|---|
| KR2001 | a dependency array is a binding the compiler cannot resolve | write it inline or as const deps = [...] in the component |
| KR2002 | an effect has no dependency array | pass the dependencies, or [] to run once |
| KR2003 | an effect callback is async (its Promise is not a cleanup) |
call an async function inside the effect |
| KR2004 | useCallback has no dependency array (one identity for the component's lifetime) |
pass the dependencies |
| KR2005 | useMemo has no dependency array (recomputes when a signal it reads changes) |
pass the dependencies |
| KR2006 | the dependency argument is not an array | pass [a, b] or omit it |
| KR2008 | a hook is called inside a condition or loop (Rules of Hooks) | call it unconditionally at the top level, or move the part into a child component |
These are warnings; diagnostics for files under node_modules are not
printed.
#Attributes and style
Elements and attributes are serialized with the same rules as
react-dom/server (React 19), from one table shared by every render path:
- Names. React prop names map to their HTML/SVG attributes:
className->class,htmlFor->for,tabIndex->tabindex,readOnly,autoComplete,colSpan,srcSet,contentEditable, SVG presentation attributes (strokeWidth->stroke-width,fillRule,clipPath, ...), and the namespaced SVG attributesxlinkHref->xlink:href,xmlnsXlink->xmlns:xlink,xmlLang,xmlSpace. SVG names that are already camelCase in SVG (viewBox,markerHeight,preserveAspectRatio) are kept as written. The JSX types accept both spellings (xlinkHrefandxlink:href,xmlSpaceandxml:space), thexmlnsdeclarations, all SVG elements (defs,linearGradient,clipPath,filter,fe*, ...) and event handlers on SVG elements, so SVG pasted from Figma, Illustrator or Inkscape typechecks as is. - Boolean attributes (
disabled,checked,hidden,readOnly, ...) render bare when truthy and are omitted whenfalse,nullorundefined.hidden="until-found"is kept.translateis enumerated ("yes"/"no"), anddraggable,spellCheckandcontentEditablerender"true"/"false".aria-*anddata-*stringify booleans. - Form values.
<textarea value>/defaultValuerender as the textarea's content;<select value>/defaultValue(an array formultiple) mark the matching<option selected>;defaultValue/defaultCheckedon<input>becomevalue/checked. - URLs. A
javascript:URL inhref,src,action,formActionorxlinkHrefis replaced, as in React 19, withjavascript:throw new Error('React has blocked a javascript: URL as a security precaution.'). The hydration runtime applies the same rule to reactive attribute updates. An emptysrc(and an emptyhrefother than on<a>) is omitted. - Text. JSX text is HTML-escaped, so
<p><b></p>renders the characters<b>, never a tag.<script>and<style>children are raw text. - Validation. Invalid element or attribute names, and children on void
elements (
<br>text</br>), are build errors. Void elements never get a closing tag.
style={{ ... }} objects are serialized to a CSS string: camelCase keys become
kebab-case, vendor prefixes keep their leading dash (WebkitTransition ->
-webkit-transition, msTransform -> -ms-transform), numbers get px
except for unitless properties (lineHeight, opacity, zIndex, flex,
fontWeight, ...) and custom properties (--gap), and null, undefined,
boolean and empty values are skipped. An object with no declarations omits the
attribute.
<div style={{ fontSize: 14, lineHeight: 1.5, '--gap': 4, color: null }} />
// -> <div style="font-size:14px;line-height:1.5;--gap:4">
Lowercase <script> and <style> elements render where they are written
(for example a <style> inside an <svg>). Use <Head>, <Script> and
<Style> to place content in the document head or body end.
key and suppressHydrationWarning never appear in the output. key drives
list reconciliation and remounting, see Keys and lists.
Event handler props are covered in
Events, forms and refs.
#Keys and lists
A .map() whose array can change at runtime is reconciled by key, with React's
semantics:
- Rows are matched by
key, the key of the element, component or<Fragment key>the callback returns. Keys may be strings or numbers and compare as strings (1and'1'are the same key). A row whose key is still present keeps its DOM nodes, input values, focus and selection, component state, effects and refs, and is moved into the new order with the fewest DOM moves. Rows whose key disappeared unmount (effect cleanups run, refs detach) before new rows mount; new rows run their effects after they are inserted. - Without a key rows are matched by index, as in React: reordering the
array moves the data, while state (an input value, a component's
useState) stays with the position. - Rows update in place. When the item for an existing key is a new object,
or its index changes, only the parts of the row that read it update; the row
is not remounted. Components rendered in a row receive live props, including
simple destructured props (
function Row({ item })). A non-arrow callback (items.map(renderRow)) or a destructured callback parameter (items.map(({ id, name }) => ...)) receives plain values, so a row whose item changed is re-rendered (its state resets); preferitem => .... - Conditionals inside rows (
{open === item.id && <Panel />}) mount and unmount their components (effects and cleanups run on each toggle), and values a row derives from state or props stay live. - Duplicate keys log React's "Encountered two children with the same key" error. The first occurrence keeps its row; each duplicate gets its own row.
- Nested lists, text rows (
items.map(t => t.label)), keyed fragments, and lists inside<table>/<tbody>,<select>and<ul>all work: rows are delimited by comment markers, which are valid in every content model. - Hydration adopts server-rendered rows by key. The build renders each row
between
<!--k:ID:$key-->markers; on load the list binds the existing nodes (handlers, live attributes, component state) instead of re-rendering them, so refs attach once and nothing flickers. A row whose key could not be computed at build time is adopted by position.
Changing the key of a single element remounts it, React's "reset state with
a key" pattern:
<Profile key={userId} userId={userId} />
// a new userId unmounts the old Profile (cleanups run) and mounts a fresh one
This applies to any element whose key reads state or props, including inside conditionals and list rows.
Lists over build-time constants (a literal array, or a prop known at build time) cannot reorder, so they render statically and are never warned about.
#shadcn/ui
shadcn/ui copies component source into your project, so its components compile like any other Krate source -- no config. Components that wrap a Radix primitive run as Preact islands (see Using shadcn/ui with Krate). The patterns shadcn relies on are handled by the compiler:
cva(class-variance-authority) -- a literalconst x = cva(base, config)and calls likex({ variant, size })fold to a static class string at build time, includingdefaultVariantsandcompoundVariants.cn/clsx/tailwind-merge-- imported from@krate/runtime; a call with statically-known arguments folds to a literal class string.- Rest-spread props --
{...props}on an intrinsic element expands to the call-site attributes, andchildrenforwards through it. - Defaults --
const Comp = asChild ? Slot : "button"resolves at build time from the parameter default. asChild/Slot-- a<Slot>(or a tag aliased to it) renders its single child element with the Slot's props (includingclassName) merged onto it.- Attributes --
data-*,aria-*, and camelCase aliases pass through.
#Using shadcn/ui with Krate
npx shadcn@latest init does not detect Krate, so set the project up by hand
once, then npx shadcn@latest add button dialog tabs ... works as usual: it
only writes files into src/components/ui and installs packages.
-
Install the dependencies the generated components import:
pnpm add class-variance-authority clsx tailwind-merge lucide-react radix-ui preactpreactis required as soon as one component is built on Radix (see below). Current shadcn components passrefas an ordinary prop, as React 19 does; Krate deliversrefto function components as a prop on Preact 10 as well (a ref on a function component withoutforwardRefreaches its element, not a component instance). You do not needpreact-render-to-string; Krate bundles its own. -
Write
components.jsonin the project root (thenew-yorkstyle, no RSC, Tailwind CSS variables, and aliases that match yourtsconfig.jsonpaths):{ "$schema": "https://ui.shadcn.com/schema.json", "style": "new-york", "rsc": false, "tsx": true, "tailwind": { "config": "", "css": "src/styles/globals.css", "baseColor": "neutral", "cssVariables": true, "prefix": "" }, "iconLibrary": "lucide", "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" } }tsconfig.jsonneeds"paths": { "@/*": ["./src/*"] }, which the app template already has. -
Create the stylesheet
src/styles/globals.css: Tailwind, the theme variables, and an@theme inlineblock that maps them to Tailwind colors, so utilities such asbg-primaryandtext-muted-foregroundexist:@import "tailwindcss"; :root { --background: oklch(1 0 0); --foreground: oklch(0.145 0 0); --primary: oklch(0.205 0 0); --primary-foreground: oklch(0.985 0 0); --muted-foreground: oklch(0.556 0 0); --border: oklch(0.922 0 0); --ring: oklch(0.708 0 0); --radius: 0.625rem; } @theme inline { --color-background: var(--background); --color-foreground: var(--foreground); --color-primary: var(--primary); --color-primary-foreground: var(--primary-foreground); --color-muted-foreground: var(--muted-foreground); --color-border: var(--border); --color-ring: var(--ring); --radius-md: calc(var(--radius) - 2px); --radius-lg: var(--radius); }Copy the full variable list (accent, popover, card, destructive, ...) from the shadcn theming page for the components you add, and import the file once from your layout or page:
import "../styles/globals.css". -
Create
src/lib/utils.ts, thecnhelper every component imports:import { clsx, type ClassValue } from "clsx"; import { twMerge } from "tailwind-merge"; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }
What runs where. Components with no Radix primitive (Button, Card,
Badge, Input, Textarea, Table, ...) compile like any other Krate source
and ship no JavaScript. asChild works for them too: import { Slot } from "radix-ui" (and @radix-ui/react-slot, including createSlot and
createSlottable) is Krate's own Slot.
Components built on a Radix primitive (Dialog, DropdownMenu, Tabs,
Accordion, Select, Tooltip, Checkbox, Switch, Popover, ...) run as
Preact islands. A file that renders a component of a React package such as
radix-ui or lucide-react as a tag is bundled for Preact, and each outermost
use on a page, for example one <Dialog>...</Dialog> with everything inside it,
becomes one island. Krate renders the island on the server when it can, so the
trigger button is in the HTML before the island loads, and the island hydrates
in the browser. A page that has islands loads Preact once for all of them; a
page without any loads none. Two or more Radix-based components can share a page.
- A name like
Dialogcan be both your wrapper and a Radix export (import { Dialog as DialogPrimitive } from "radix-ui"insidefunction Dialog). That is how the generated files are written, and it is fine. - Provider components such as
TooltipProvidermust contain the components that need them in the same page tree: put<TooltipProvider>around the<Tooltip>elements you render. A Radix component rendered without its provider reports it in the build output (KR8008, the island stays client-only) and fails in the browser. - If the build prints
KR8008for an island, the message names the cause; it says Preact is missing only when it is.
#Known limits of Radix on Preact
Two differences between Preact and React change how a few Radix components
behave. They are in Preact, not in Krate: the same failures appear with a
plain Preact build and no Krate at all. They were checked in Chromium against
real React 19 running the same shadcn source, with radix-ui 1.6.7 and 1.8.1
and Preact 10.29 and 11.2 (11.2 is the newest release). Switching Radix or
Preact version does not help.
Tooltip closes about 10 ms after it opens. This affects the Tooltip that
shadcn generates (no open prop), on every Radix and Preact version above,
with hover and with keyboard focus. Radix announces an opening tooltip with a
tooltip.open event from a passive effect, and every other tooltip closes when
it hears it. React runs that effect before the tooltip content mounts. Preact
runs the content's own effect first, so the tooltip hears its own event and
closes. Make the tooltip controlled, which sends the event before the content
exists. Replace Tooltip in components/ui/tooltip.tsx:
function Tooltip({
open: openProp,
defaultOpen = false,
onOpenChange,
...props
}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
const [openState, setOpenState] = React.useState(defaultOpen)
return (
<TooltipPrimitive.Root
data-slot="tooltip"
open={openProp ?? openState}
onOpenChange={(next) => {
setOpenState(next)
onOpenChange?.(next)
}}
{...props}
/>
)
}With this wrapper, hover, focus, Escape and a tooltip inside a Dialog all stay
open and close correctly. Re-apply it after npx shadcn add tooltip --overwrite.
A layer opened inside another layer's content dismisses the outer layer.
Radix decides whether focus is still "inside" a popover by letting React
bubble the focus event up through portals. Preact does not, so opening a
Dialog from inside PopoverContent closes the popover and the dialog never
appears. Keep the Dialog outside the popover and open it with state:
const [popover, setPopover] = React.useState(false)
const [dialog, setDialog] = React.useState(false)
<Popover open={popover} onOpenChange={setPopover}>
<PopoverTrigger asChild><Button>Open</Button></PopoverTrigger>
<PopoverContent>
<Button onClick={() => { setPopover(false); setDialog(true) }}>Edit</Button>
</PopoverContent>
</Popover>
<Dialog open={dialog} onOpenChange={setDialog}>...</Dialog>Only Dialog inside Popover was tested. A menu, popover or similar layer opened
from inside another layer's content relies on the same mechanism, so use the
same state-driven pattern. A Select inside a Dialog and a Tooltip inside
a Dialog (with the controlled wrapper) work.
Tested and working: Dialog, Sheet, DropdownMenu, ContextMenu, Menubar, NavigationMenu, Popover, HoverCard, Select, Tabs, Accordion, Collapsible, Checkbox and Switch, on Preact 10 and 11.
#Compiled React packages (islands)
Some packages ship compiled JavaScript only, built against React's runtime
(react/jsx-runtime, React.*, and internal packages). Krate cannot transpile
those files, so it bundles the imported component into an island: a small
Preact tree that mounts into a placeholder and hydrates on the client.
import * as Popover from '@radix-ui/react-popover';
<Popover.Root>
<Popover.Trigger>Open</Popover.Trigger>
<Popover.Content>Hello</Popover.Content>
</Popover.Root>How it works:
-
A component is treated as an island when its implementation lives under
node_modules. Local React-compatible modules imported by the page and used as tags inside that subtree are bundled into the same island, so a local wrapper can contain or be contained by a compiled package component. A same-file function component is reported with a diagnostic because it belongs to the Krate runtime, not the island runtime. -
The subtree is captured as-is and rendered with Preact. Preact is not a Krate dependency; install it in your app:
pnpm add preactPreact 10.20 or newer is required. If Preact is missing, the build fails with an actionable error rather than shipping a broken island.
-
Each island gets an entry file (
chunks/island_<id>.js). The entries of all pages are bundled together with code splitting, so a module two pages import (a store, a query client, the library itself) is one shared file with one instance, and the Preact modules are emitted once and wired through an import map. See State across navigation. -
Where all bridged props have build-time initial values, Krate renders the island with
preact-render-to-stringand places that markup inside the placeholder. The client then hydrates it instead of replacing it. Islands with unknown runtime props, browser-only components, or portals stay client-only; the build warns when an island cannot be server-rendered. -
Signal-valued props are bridged as live getters, and the island re-renders when those signals change. Function props (event handlers and signal setters) are passed by reference, so page-to-island callbacks work. Plain object and string props are captured when the island mounts.
-
Each island is wrapped in a Preact error boundary. A render failure marks the placeholder with
data-krate-island-errorand shows a fallback instead of taking down the rest of the page. -
Krate warns when the installed Preact is older than 10.20, which is the minimum version the island hooks and compat behavior are tested against.
In an async page, layout or component the same packages render without a page
island: stateless components (an icon) become plain HTML, stateful ones
(a Radix checkbox) become <krate-island> boundaries rendered on the server
and hydrated in place, and parts of a compound component such as
Dialog.Root / Dialog.Trigger stay in one tree. See
Async Server Components.
Two runtimes are involved at an island boundary: the page (Krate signals) and the island (Preact). Props crossing the boundary may be serializable values, bridged signal getters, or function references (handlers and setters).
Primitives that keep internal pointer state (for example Radix Tooltip) work
when controlled: bind open to a page signal and wire onOpenChange plus
explicit pointer/focus handlers on the trigger.
#Choosing when an island mounts
By default an island mounts as soon as the page script runs. Put a client directive on the island's root tag to defer it:
import { LineChart, Line } from 'recharts';
<LineChart client:visible width={600} height={300} data={data}>
<Line dataKey="sales" />
</LineChart>| Directive | Mounts |
|---|---|
client:load |
at load (the default) |
client:idle |
when the browser is idle (requestIdleCallback, 2 s at most) |
client:visible |
when the island comes within 200 px of the viewport (IntersectionObserver) |
A deferred island keeps its server-rendered markup, which is not interactive
until it mounts. Its chunk is not preloaded and is not fetched before then, so
a heavy island below the fold costs nothing until it is needed. The directive is
removed at build time and never reaches the component. On anything that is
not an island the directive does nothing, and the build says so (KR8012).
Without IntersectionObserver the island mounts at load. A page that is itself a
React-library island (below) always mounts at load.
#Libraries built on React hooks (islands)
State, forms and data-fetching libraries from the React ecosystem call React's
hooks from their own code (useSyncExternalStore, useRef, useContext).
Krate's source components do not have React's render model: they run once and
update through signals, and a library's hooks cannot be lowered. A
component that calls such a hook therefore runs in a Preact island, where
React's model exists, instead of being lowered.
Krate decides this at build time. A user module is routed to the island path when it:
- calls a
use*hook imported from an npm package that depends onreact(useForm,useSWR,useQuery,useStore, ...), or a store hook made at module level (const useStore = create(...)), - calls a hook exported by another module that does (a custom hook wrapping
useSWR, a store hook exported fromstore.ts), - renders a component built by such a package at module level
(
const Box = styled.div`...`,motion(Button)), - hands a value built by such a package to a JSX attribute
(
const queryClient = new QueryClient()thenclient={queryClient}), or - starts with
/** @jsxImportSource <react package> */(emotion'scssprop).
// src/components/Counter.tsx
import { useStore } from '../store'; // const useStore = create(...)
export function Counter() {
const n = useStore((s) => s.n);
const inc = useStore((s) => s.inc);
return <button onClick={inc}>clicked {n}</button>;
}// src/pages/index.tsx: Counter is rendered as an island
import { Counter } from '../components/Counter';
export default function Home() {
return <main><Counter /><Counter /></main>;
}The module is compiled for Preact (react resolves to preact/compat) and
rendered on the server with the same code, then hydrated. Props follow the
island rules above: serializable values, signals bridged as live getters, and
function references. A page whose own module calls the hook is one island.
What was checked in Chromium (Preact 10.29): each page loaded without console errors and rendered the expected markup, and where the library has an interaction it was clicked or typed into.
| Library | Result | Version checked |
|---|---|---|
| zustand | works: store hooks, selectors, state shared by the islands of a page | 5.0.16 |
| valtio, jotai | work: useSnapshot, useAtom |
2.3.2, 2.20.3 |
| react-redux with Redux Toolkit | works: Provider in the island's module or in a layout, useSelector, useDispatch, a slice and configureStore |
9.3.1, 2.14.0 |
| react-hook-form | works: register, required validation, handleSubmit, formState |
7.91.0 |
| SWR | works: useSWR directly or inside a custom hook |
2.5.1 |
| TanStack Query | works: useQuery under a QueryClientProvider in the island's module or in a layout, one client for every island |
5.106.1, 5.105.3 |
| TanStack Table | works: useReactTable with flexRender, rendered on the server |
8.21.3 |
| react-i18next | works: useTranslation after i18n.use(initReactI18next).init() |
15.7.4 |
| usehooks-ts | works: useCounter, useToggle |
3.1.1 |
| recharts, Headless UI | work (they need import React from "react") |
2.15.4, 2.2.10 |
| framer-motion | works: motion.* and useAnimation |
11.18.2 |
motion (motion/react, v12 and later) |
works: motion.* with initial/animate/transition, AnimatePresence with an exit animation. Building logs the warning KR7116, which does not affect the result |
14.14.0 |
| cmdk | works: Command, Command.Input, Command.List, Command.Item filtering as you type, Command.Empty |
1.1.1 |
| embla-carousel-react | works: useEmblaCarousel, snap list, scrollNext() |
8.6.0 |
| @dnd-kit | works: DndContext, SortableContext, useSortable with the pointer sensor, reordering through a real drag |
core 6.3.1, sortable 10.0.0 |
| next-themes | works: ThemeProvider in the root layout and useTheme in a client component switch the <html> class and theme state; the theme state is per island (see below) |
0.4.6 |
| sonner | works: <Toaster /> in a static or async layout and toast() from a client component of a page, one store; toasts on screen are dropped by a client-side navigation |
2.0.8 |
styled-components, @emotion/styled, emotion css prop, MUI Button |
work, client-only (see below); a ThemeProvider in a layout reaches them |
6.6.0, 11.14.1, 11.14.0, 9.5.0 |
These were run by hand against the real packages. TestBrowserEcosystemLibraries
repeats the checks for motion, cmdk, embla-carousel-react, @dnd-kit,
TanStack Table, next-themes and sonner against the pinned versions in
packages/compiler/internal/build/testdata/ecosystem_libs/package.json; it is
skipped unless KRATE_BROWSER is set and either KRATE_ECOSYSTEM_LIBS points
at a node_modules directory holding them or KRATE_ECOSYSTEM_INSTALL=1 lets
it run npm install. The other repository tests run
stand-ins with the same import shapes (default import React, namespace
import, require("react")) and the same behavior (a store with module-level
state, a query client with a context provider, a theme provider), because the
repository does not install the libraries; they cover the behavior described on
this page in Chromium, but not the libraries themselves. A library that is not
listed may work, but nothing was run for it.
#Providers in layouts
A context provider a layout wraps around {children} reaches the islands of
every page under that layout, with one provider instance for all of them:
// src/pages/_layout.tsx
import { useState } from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Provider } from 'react-redux';
import { ThemeProvider } from 'styled-components';
import { store } from '../store';
const theme = { name: 'light' };
export default function Layout({ children }) {
const [client] = useState(() => new QueryClient());
return (
<div>
<nav><Link href="/">Home</Link></nav>
<Provider store={store}>
<QueryClientProvider client={client}>
<ThemeProvider theme={theme}>{children}</ThemeProvider>
</QueryClientProvider>
</Provider>
</div>
);
}The layout itself is compiled by Krate, and an island is a Preact tree, so
context cannot cross between them. Krate therefore lifts the wrappers out of the
layout: the layout renders {children} as if they were not there, and the chain
(Provider > QueryClientProvider > ThemeProvider, with the props as written)
becomes a generated module that every island of the page renders inside. This
holds on the server too: the markup rendered at build time already contains the
context, and the island hydrates onto it.
- One instance per page and site. The props are evaluated once, in the
generated module, and that module is shared by all islands and all pages, so
they receive the same
QueryClient, store or theme object. A client created withuseState(() => new QueryClient())in the layout is created once, not per render and not per island. - Nested layouts compose: the providers of the outer layout wrap those of
the inner one, so an inner
ThemeProvideroverrides the outer one for the pages under it. - Which wrappers. A tag on the path to
{children}that comes from an npm package built on React, or from a module of the project that renders such a component around itschildren(aProviderscomponent), is lifted. Other elements stay in the layout. - Props. A prop can be a literal, an import, a module-level value, or a
value the layout component computes from those: a plain
const,useState(() => value)with no setter in use, oruseMemo(() => value, []). Computing a prop from the layout's ownparams, from a signal, or from a state setter cannot work, because the islands would not see it change: the build reportsKR8015with the reason. - No markup of its own. A lifted wrapper must render only its children. One
that adds elements (a
<div>around them) cannot move into the islands, since Krate renders the page content; the wrapper then stays in the layout and the build reportsKR8016. Scripts are the exception: a provider that adds a<script>next to its children (next-themes' anti-flash script) is lifted, and the script is part of every island's server markup. - Layout components stay Krate's. Krate components in the layout still
cannot read the provider's context, and a hook of a React library called
inside the layout is still
KR8013.
#Islands in a layout
A static layout can render islands itself: a component of a client module of
the project (a "use client" wrapper around a library's component), or the
component of a package whose module-level state is shared with plain function
calls (sonner's and react-hot-toast's <Toaster />). The layout emits a
placeholder for each, and the pages under it build the island chunks together
with their own, so the layout's island and the islands of the page use one
copy of the library:
// src/pages/_layout.tsx
import { Toaster } from "sonner";
export default function Layout({ children }) {
return <>{children}<Toaster richColors /></>;
}
// src/components/SaveButton.tsx
"use client";
import { toast } from "sonner";
export default function SaveButton() {
return <button onClick={() => toast("Saved")}>Save</button>;
}A client module that calls a plain function of a React package (toast()) runs
as an island too, so it shares the library with the layout's island. Rules:
- Props of a layout island must be constants or imports; one that reads the layout's own state is reported.
- A layout that hosts an island is replaced on a client-side navigation instead of being kept mounted, so anything the island holds (toasts on screen) is lost when the page changes.
- An async layout (one that loads the session, say) needs nothing special:
its
<Toaster />and the"use client"components of its async and sync pages are client boundaries, built in the same code-split graph as the islands, sotoast()reaches the Toaster. Checked in Chromium with an async root layout, an async page and a sync page. - A static layout renders a component of a React package itself (compiled by
Krate, not as an island) except for
sonnerandreact-hot-toast, which are hosted as islands because their<Toaster />shares a store withtoast(). For another library whose component must share module state with calls from pages, wrap it in a"use client"component of your own: a wrapper is hosted whatever it renders. - A plain function of a React package called outside a
"use client"module and outside an event handler (in an effect of a module without the directive) is bundled into the page script with its own copy of the package; put the call in a"use client"module. ThemeProviderfrom next-themes in a layout is lifted like any provider, and every island renders its own copy of it. next-themes keeps its state in the provider, not in a module, so it is not shared: with two islands callinguseTheme,setThemein one updates<html>and the stored theme, but the other island shows its old value until it re-renders for another reason. Keep the theme controls and their display in one island, or read the theme from the<html>class.
#State across navigation
The islands of all pages are bundled together, so a module-level store is one store for the whole site, as in a React single-page app. A zustand or Redux store, a query client and the library modules they use are evaluated once; when the client-side router moves to another page, the new page's islands import the modules that are already loaded.
- Same instance, same value. The count in a zustand store, a Redux slice and the cache of a query client survive navigation, forward and back.
- Components start fresh. An island is a Preact tree under the page's
content, and the router replaces that content: when a page changes, its
islands unmount (effects clean up, store subscriptions and query observers are
released) and the next page's islands mount. State inside a component
(
useState) therefore resets, as when a React router swaps route elements. Keep what must last in a store. - Static pages stay static. A page without islands loads no island code, and the Preact import map is a small JSON block.
- Caching. The entry file of an island (
island_<id>.js) is revalidated on every visit; the shared chunks (isl-<hash>.js) are content-hashed and cached as immutable.
#Pages rendered per request
Pages with dynamic = "force-dynamic", revalidate = N (ISR) or a streaming
region run their JSX in Node on every request, where a component that needs
React's render model cannot run. Their islands are therefore not executed there:
the server answers with the placeholder of each island and the markup rendered
for it at build time, and the page script mounts it as on a static page. The rest
of the page is rendered per request as usual.
Because that markup is rendered at build time, an island's props must be known
then: a prop that only exists per request (a search parameter, a cookie) makes
the island client-only, as on a static page, and the build says so (KR8008).
#CSS-in-JS
styled-components, emotion and MUI create their styles in the browser while
rendering. Their islands are client-only: the build prints a KR8008
notice, the placeholder is empty in the server HTML, and the component and its
styles appear when the island mounts. For content that must be styled before
JavaScript loads (above-the-fold text, SEO content), use CSS modules, Tailwind
or a stylesheet. A css={...} prop on a DOM element in a module without
/** @jsxImportSource @emotion/react */ is reported as KR8014 (the styles
would be dropped). Setting jsxImportSource to emotion in tsconfig.json
for the whole project is not supported.
#Limits, and what the build refuses
Each limit below is either a build error or a documented behavior, never a silent failure in the browser:
- Hooks need a client component. A layout, a template or an
asyncserver page or component that (through its imports) calls a React-library hook fails withKR8013, naming the package and the hook. Add"use client"to the module that calls it (it then hydrates as a client component inside the server-rendered output), or usecreateSignal/createResource. Rendering the library's components (icons, Radix primitives) from a server tree needs no directive; see Compiled React packages in server components. A static (synchronous) layout cannot host compiled components at all: make itasync. - No bridge to Krate state from inside. The island reads the page's signals only as props, and the page cannot read the island's store. Krate components that import the same store module do not see it.
- A page that is itself an island cannot take props (
params,searchParams): the build fails withKR8013. Move the component that calls the hook into its own module and render it from a page that passes the values in. Such a module also cannot use Krate-only APIs (createSignal,<Head>). - Component state is not kept across pages. Module-level state is (see State across navigation); the state of a component resets when its island unmounts.
- No islands in layouts. A layout is rendered by Krate and persists across pages; a React-library island has to be rendered by a page. (Providers are the exception, see Providers in layouts.)
#Libraries built on a React reconciler (real-React islands)
@react-three/fiber, @react-three/drei, react-konva and similar libraries
draw through react-reconciler, React's renderer API. Preact does not have it,
so these libraries cannot run on the Preact islands above. A module that uses
one runs in a real-React island instead: an island bundled with react
and react-dom themselves, with no Preact alias anywhere in its subtree.
For three.js scenes there is also @krate/three, which
has the @react-three/fiber API but compiles with the page (or runs in the
Preact island of a "use client" component): it ships no React runtime, and
the scene reads page state directly. @krate/three/drei provides drei's
OrbitControls, Environment, Lightformer and useGLTF, and
krate migrate nextjs moves fiber and drei code onto them when that is all it
uses. Use the real-React island when you need other libraries built on
@react-three/fiber.
For 2D canvases, @krate/konva has the react-konva
API the same way: <Stage> compiles with the page (or runs in the Preact island
of a "use client" component), and krate migrate nextjs moves react-konva
code onto it when it only uses what @krate/konva provides.
// src/components/Viewer.tsx
import { Canvas } from '@react-three/fiber';
import { OrbitControls } from '@react-three/drei';
export default function Viewer({ color }: { color: string }) {
return (
<Canvas>
<mesh><boxGeometry /><meshStandardMaterial color={color} /></mesh>
<OrbitControls />
</Canvas>
);
}// src/pages/model.tsx
import Viewer from '../components/Viewer';
export default function Page() {
return <Viewer client:visible client:fallback="Loading 3D viewer..." color="#c33" />;
}#How a module opts in
Krate does not need a directive on every tag: the requirement belongs to the package, so the build decides from the module's imports, the same way it detects React-library hooks.
-
A package that depends on (or has a peer dependency on)
react-reconciler,@react-three/fiberorreact-konvaneeds real React. That covers@react-three/fiber,@react-three/drei,react-konvaand the libraries built on them. Nothing needs to be configured. -
Any other package can be added in
krate.config.ts:react: { islands: ["some-canvas-library"] },
A user module that imports such a package becomes a real-React island, and so
does every island module that imports it. Using the component as a tag in a page
renders the island there. A reconciler library used as a tag directly in a page
(<Canvas> imported in the page itself) is an island too. A library that pulls
in react-reconciler without being listed fails the Preact island build and the
message names react: { islands: [...] }.
#"use client" modules
The usual Next way works unchanged: a "use client" module that imports a
reconciler library ("use client"; import { Canvas } from "@react-three/fiber")
is a real-React island, whether a sync page, an async page, an async layout or
another "use client" component imports it. Everything inside the module
(its own hooks, effects and the other components it imports) runs on real
React. A "use client" parent that renders such a component becomes a real-React
island as a whole; Krate does not nest a real-React root inside a Preact island,
because the two runtimes cannot share a tree.
#Rendering
A real-React island is client-rendered. Server-rendering a WebGL or canvas
tree is not meaningful, so the server emits only the placeholder (and the
resource hints the island calls). Put
client:fallback="text" on the tag to render a text fallback there until
React mounts it (escaped, text only). To reserve space, wrap the tag in an
element with a fixed size. client:load, client:idle and client:visible
work as for other islands, so a heavy viewer below the fold is fetched only
when it nears the viewport. Both directives are removed at build time and
never reach the component.
#Resource hints
A preload() (or preinit, preconnect, ...) that a real-React island or
client component calls while it renders still reaches the <head> of the
server HTML, as in Next.js, so the browser starts the request while it parses
the page and a later fetch() of the same URL (with matching crossOrigin)
reuses it. The server does not render the island, so the build renders it once
with react-dom/server, only to record its hints: the markup is discarded and
a render error is ignored (hints called before the error are kept). npm
packages other than React are replaced by inert stand-ins for that render
(three.js and canvas libraries do not run), so it reaches the hint calls of
your own modules and workspace packages. In the browser react-dom finds the
<link> and adds nothing.
The build render has the island's build-time props, and a client boundary on
an async page renders without props, so it collects hints whose URL is a
constant or comes from module code (preload(WASM_URL, { as: "fetch" })). A
hint whose URL comes from request data, state, an effect or an event handler
is added in the browser after hydration only, and so is one that a library
calls; one built from a missing prop ("/img/undefined.png") is dropped.
Project code that throws at import time outside a browser yields no hints. Set KRATE_NO_REAL_HINTS=1 to skip the build
render.
#Props and children
- Props are serialized like any other island: literals, bridged signal getters (the island re-renders when the signal changes) and function references.
- The island is one React tree.
childrenand nested tags in the island's JSX (<Canvas><mesh/></Canvas>) are compiled for React inside it, and may use elements, components imported from packages and imported local modules. - Krate components cannot be passed in. A same-file Krate function used
inside the island, or JSX built by a Krate component and handed to a prop,
cannot cross the boundary; the build reports the same-file case (
KR8007). Move the component into its own module (it is then bundled and run on React) or render it outside the island. - The island cannot read Krate signals, only the props the page passes in, and Krate cannot read the island's state.
- Providers a layout wraps around its children are not applied to a real-React island. Render the provider inside the island's own module.
- A page that is itself a real-React island, and a synchronous layout, follow
the limits of the other React-library islands (
KR8013). - In
asyncpages and layouts a real-React component also works, used directly (<Canvas>from the library) or through a wrapper module. It never goes through the Preact boundary path: the server sends a<krate-island>with theclient:fallbacktext, the serialized props and the children as an element tree, and the browser mounts it withreact-dom. Props must be serializable (as for any client component); children may be host elements and other real-React components, with serializable props.
#Modules shared with Preact islands
Preact islands and real-React islands are bundled separately, because react
is preact/compat in one and the project's React in the other. A module both
reach that does not depend on React, directly or through its imports, is
bundled once, into a shared chunk both import, so there is one instance of
it on the page: a cache, a promise that dedupes a fetch, an event emitter or a
store made with zustand/vanilla holds one value for both kinds of island.
Modules that import each other (an import cycle) are bundled once together and
run in the order the islands would run them. The chunk exports only what the
islands import from it, so a large library both reach is still tree shaken.
That includes a namespace a library re-exports from its index:
import { z } from 'zod' keeps only the parts of zod the islands call
(z.string()), not every export and locale. A module an island loads with import() is split into the
island bundle too and imports the modules the island already loaded, so it
shares their instances (and the shared chunk when both kinds of island load
it).
A module that imports React, or a library built on it (a zustand create
store, a module that calls createContext), needs a copy for each kind of
island, and the copies do not share module-level state. The build reports such
a module when it declares state (a let or var, an object made with new,
or a store) with KR8017, naming the file and the import chain that reaches
React (src/lib/store.ts -> zustand/esm/index.mjs -> "react"). Keep the state in a module without React and import it from the hook
module. Contexts are the exception: a context from a provider in a layout
reaches both kinds of island (see
server components).
#What it costs
Real React is not part of Krate's runtime, and the 25 KB counter-page figure
does not include it. The cost is paid only by pages that load a real-React
island, as one shared chunk of react, react-dom and the libraries, cached
across those pages: React plus react-dom is roughly 60 KB gzipped for the
client renderer, and react-reconciler libraries add their own weight (Three.js
is several hundred KB). Pages without such an island load none of it, and
krate check counts the island bytes against the page budget. All real-React
islands of a page mount from one entry, and the pages of a site share the
React chunk, so a second viewer page adds only its own code.
The project must have react and react-dom (18.3 or newer, 19 recommended)
installed; the build says so if they are missing. Both resolve to the project's
copy, so a reconciler library and the island share one React.
#Events, forms and refs
Event handlers, form controls and refs follow React 18/19 semantics as
observed in a browser. The browser conformance suite (/react-events/ in
examples/) exercises them in a real browser.
#Events
- Synthetic events. Handlers receive a React-style event:
type,target,currentTarget(the element whose handler is running),nativeEvent,eventPhase,bubbles,cancelable,defaultPrevented,timeStamp,isTrusted,preventDefault(),stopPropagation(),isDefaultPrevented(),isPropagationStopped()and a no-oppersist(). Type-specific fields (key,code,repeat, modifier keys,button,clientX/pageX,relatedTarget,deltaY,touches,dataTransfer,clipboardData,data,animationName,propertyName, ...) andgetModifierState()come from the native event.currentTargetisnullafter the handler returns, as in React. - Root delegation. Like React 17+, bubbling events are delegated to the app
root (
#root, else<body>) with one capture-phase and one bubble-phase listener per event type, installed the first time a handler needs it. Capture handlers (onClickCapture) run top-down, then bubble handlers run bottom-up. Native listeners interleave the same way: a listener added withaddEventListeneron an element inside the root runs before React bubble handlers, a listener ondocumentruns after them. stopPropagation()stops the remaining React handlers and native propagation, sodocumentlisteners do not see the event. Called in a capture handler it also skips every bubble handler.- Event names.
onDoubleClickusesdblclick;onFocus/onBlurbubble (they usefocusin/focusout) and reporttypefocus/blur.onMouseEnter/onMouseLeave/onPointerEnter/onPointerLeave,onScroll,onLoad/onError,onToggle,onInvalidand media events (onPlay,onEnded, ...) do not bubble and are attached to the element.onSubmit/onReset, composition events (onCompositionStart/Update/End) and clipboard, drag, touch, wheel, pointer and animation/transition events are delegated. onChangefollows React: text inputs, textareas and range/number inputs fire on everyinputevent; checkboxes and radios fire onclick(only when the checked state actually changed, so clicking a checked radio does nothing); selects and file inputs fire onchange.onChangeruns afteronInputandonClickfor the same native event.onBeforeInputfires for text insertion (and at the end of an IME composition) withdata, not for deletions, matching React.- Errors thrown by a handler do not stop the other handlers; the first error is rethrown after the dispatch.
- Handlers on
window/documentregistered inuseEffectstay native listeners. Handlers inside a portal keep working, and events from portal content bubble to the React ancestors of the portal, not the DOM ancestors of its container.
#Forms
- Controlled fields.
valueandcheckedmake a field controlled: afteronChangethe DOM is restored to the state value, so a handler that does not update state (or a field withoutonChange) keeps its value, and a handler that transforms the value (setV(v.toUpperCase())) shows the transformed value immediately. Radio groups restore every radio in the group.<select value>and<select multiple value={[...]}>are controlled the same way. - Value attribute sync. As in React, the
valueattribute of a controlled input tracks the current value, soform.reset()restores the current controlled value. - Uncontrolled fields.
defaultValue/defaultCheckedset the initial value only. Changing them later updates the default (visible only while the user has not edited the field) and never overwrites user input.form.reset()restores the defaults. - Constant values.
value="fixed"with anonChangeis controlled too: typing snaps back to the constant, as in React. - Mount behavior. Text inputs get React's mount-time caret (at the end of
the value), so typing after
focus()appends; a controlled textarea starts with the caret at the beginning, as in React. AnautoFocuselement is focused when its conditional branch mounts, and focus stays on a list item (matched byid) when the list re-renders. value={undefined}(ornull) leaves the field uncontrolled. Switching a field between controlled and uncontrolled logs React's console warning at runtime.
#Refs
- Object refs (
useRef,createRef) getcurrentset to the node before any layout effect runs, including refs forwarded to a child component, and reset tonullon unmount (a conditional branch hiding, a list item removed, or navigation). - Callback refs are called with the node on mount and with
nullon unmount. A React 19 cleanup function returned by the callback is called on unmount instead. When the callback's identity changes the old callback is detached and the new one attached. An inline callback ref (ref={(n) => log(n, count)}) is re-bound whenever a state value it reads changes, and each call sees the state of its own render, matching React's new-callback-per-render behavior. Callback refs never subscribe the surrounding binding to signals they read. - Hydration refs attach after every component on the page has bound its DOM and before layout effects (components mounted later attach at once), so a ref on server-rendered list content that is re-rendered on hydration is never called with the stale node.
ref.currentread during render is shown once and not refreshed on later renders (Krate does not re-render); it is reported asKR5008. Keep values the UI shows in state.refas a prop,forwardRef, anduseImperativeHandle(ref, create, deps)are supported. Refs in lists keep the right element per item.- Refs to class component instances receive the instance (see Class components).
#Build diagnostics
| Code | Reported for |
|---|---|
KR5001 |
an unknown event prop on a built-in element (onClickcapture, onTap); a "did you mean" hint names the React event |
KR5002 |
a lowercase event prop given a function (onclick={fn}) |
KR5003 |
a string ref (ref="field", also in class components), removed in React 19 and ignored |
KR5004 |
value/checked without onChange, onInput, readOnly or disabled (a read-only field) |
KR5005 |
value with defaultValue, or checked with defaultChecked (the default is ignored) |
KR5006 |
value={cond ? x : undefined}: a field that switches between controlled and uncontrolled |
KR5007 |
onChange on a contentEditable element (use onInput) |
KR5008 |
ref.current read in rendered JSX (shown once, never refreshed) |
KR6001 |
a list that can change at runtime renders elements without a key |
KR6002 |
two items of a list resolve to the same key at build time |
KR6003 |
a map callback keys some returned elements but not others |
#What is not supported
- Running React itself in a page. There is no React runtime; compiled packages run through Preact islands, not React. The exception is a real-React island, for libraries built on a React reconciler.
- React libraries' hooks in lowered source components.
zustand,react-hook-form,swrand@tanstack/react-queryhooks need React's render model, so the module that calls them is run as a Preact island instead (see Libraries built on React hooks). Where an island cannot be used (layouts, server pages) the build fails withKR8013. The signal-based replacements arecreateSignal(with a module-level signal for shared state) for client state andcreateResourcefor fetching. - Sass, Less and Stylus. There is no compiler for them: importing a
.scss,.sass,.lessor.stylfile is a build error (KR7123). Compile it to CSS in a prebuild step, or use CSS modules or Tailwind (see Styling). - CSS-in-JS at first paint. styled-components, emotion and MUI work only as client-only islands; their styles do not exist in the server HTML.
- React 19-only semantics in compiled packages. Preact's compatibility layer is close to React 18 behavior; version-specific APIs may differ.
- State reuse across conditional branches, the uncommon shapes. One
stateful component type in both branches of a ternary keeps its instance (see
Effects). Shapes the compiler cannot lower restart the component
and warn with
KR8360: the same component inside a wrapper element each branch builds, a differingrefor spread, render-prop children.{c && <Panel/>}next to{!c && <Panel/>}are two positions, so they remount in React as well. A stateless component, or an external island, in both branches is not merged: uncontrolled DOM state inside it (typed text) is reset on the flip. - Hook ordering and rules-of-hooks for transpiled source. Components run once per mount, so there is no hook order to preserve.
ActivityDOM structure,SuspenseListordering,ViewTransitionevents. See the sections above.- A custom hook that calls
useIdhas no id in the static HTML. - Dynamic
Children.*/cloneElementinputs that are not statically known. Literal inputs fold at build time; dynamic inputs use the compat shim. Children.forEachand dynamicChildren.mapcallbacks run in the compat shim at runtime, not at build time.
If you rely on unsupported behavior, write the component in Krate's own style -- see Reactivity and Migrating from Next.js.
#Server actions
A file-level "use server" module is supported for mutations. Use an imported
action as a form action, or call it from an event handler:
import { saveFeedback } from "../actions/feedback";
<form action={saveFeedback}>
<input name="text" />
<button type="submit">Save</button>
</form>Forms work without JavaScript and are enhanced by the shared runtime.
#React 19 actions
<form action={fn}> and <button formAction={fn}> accept a server action or a
client function. On submit the function receives the FormData inside an async
transition; the page does not reload and uncontrolled fields reset after
success. The React 19 hooks follow React's semantics:
useActionState(action, initial, permalink?)returns[state, formAction, isPending]. Calls are queued in order and receive the previous state; with a server action the previous state travels to the server and the returned state back. Without JavaScript the form posts to the action with the initial state and redirects topermalink.useFormStatus()reads the pending status, data, method and action of the form that contains the component.useOptimistic(state, update?)applies updates while an action is pending and reverts to the latest state when it settles.requestFormReset(form)resets a form after its pending action.
Inline "use server" functions inside server components are hoisted into
generated server actions; in a "use client" module they are an error
(KR7001). See
Server Actions for the module format, wire
format, request context (headers(), cookies(), redirect()), runtime
requirements, and security model.
#Diagnostics and conformance
Compatibility limits are reported with stable diagnostic codes (KR2001,
KR8001, ...). Every code, with the reason it fires and what to do instead, is
listed in the diagnostic codes reference.
Behavior is checked against React itself. A browser differential runs a corpus
of React 18 source components and a React 19 reference app in both real
React 19 and Krate, drives them with the same clicks and keystrokes in
Chromium, Firefox and WebKit, and compares the DOM, form state, focus and the
order of effects, cleanups, lifecycles and ref callbacks after every step.
Known differences are tracked with a severity in the repository
(packages/compiler/internal/build/testdata/reactbrowser/divergences.json).
The four P2 differences that remain at v1 are all render-observability details,
not DOM or interaction differences:
| Fixture | Difference |
|---|---|
r18/class_pure_component |
A PureComponent render log is one update behind because Krate updates the text binding without re-running the body. |
r18/context_memo_child |
A memo child's render log differs for the same reason; the rendered context value is identical. |
r18/hook_usecallback_identity |
Render counters kept in refs differ because bodies are not re-run; handler behavior matches. |
r18/hook_useid |
useId strings use Krate's krate-<n>-... format instead of React's :r0: style; ids stay unique and labels resolve. |
P0 and P1 differences fail the differential (KRATE_REACT_EXIT=1). P2 entries
are intentionally documented rather than hidden.
See Compile-Time Evaluation for how
known React expressions, .map() callbacks, and local helpers are folded before
shipping.
Last updated: 2026-11-17
Contributors: Noinkin