#Routing & Layouts
File-based routing, dynamic segments, and nested layouts.
Krate uses file-based routing: every file in src/pages/ becomes a route.
| Pattern | Route |
|---|---|
src/pages/index.tsx |
/ |
src/pages/about.tsx |
/about |
src/pages/blog/index.tsx |
/blog |
src/pages/blog/post.tsx |
/blog/post |
src/pages/video/[id].tsx |
/video/abc123 |
src/pages/docs/[...slug].tsx |
/docs/a/b/c (catch-all, one or more segments) |
src/pages/shop/[[...filter]].tsx |
/shop, /shop/red/xl (optional catch-all) |
src/pages/(marketing)/pricing.tsx |
/pricing (route group) |
When several patterns match a URL the most specific wins, segment by segment:
a static segment beats [param], which beats [...catchAll], which beats
[[...optional]] (/docs/intro.tsx serves /docs/intro even with
/docs/[...slug].tsx present). The order is the same in krate dev,
krate serve and SSR.
#Dynamic routes
Files named [param].tsx map to dynamic segments. The segment value is passed
to the component as params:
// src/pages/video/[id].tsx -> /video/abc123
export function generateStaticParams() {
return [{ id: "abc123" }];
}
export default function VideoPage({ params }) {
return <h1>Video {params.id}</h1>;
}A statically-built dynamic route provides generateStaticParams (as above) to
expand the route into concrete pages. Each param value is passed to the
component as params (so params.id matches the [id] segment).
A catch-all param is the matched segments joined with /
(/docs/a/b gives params.slug === "a/b"); an empty optional catch-all is
"".
#Route groups
A directory named (name) organizes files without adding a URL segment:
src/pages/(marketing)/about.tsx serves /about. A _layout.tsx inside the
group wraps only the pages in that group, so groups give different sections
different shells. Two pages that resolve to the same URL from different groups
are a build error.
#Layouts
A _layout.tsx file wraps every page in its directory and subdirectories:
// src/pages/_layout.tsx - wraps every page in the directory
export default function Layout({ children }) {
return (
<div>
<nav><a href="/">Home</a></nav>
<main>{children}</main>
</div>
);
}Layouts nest: a src/pages/blog/_layout.tsx wraps blog pages inside the root
layout. Layouts receive their page content through {children}, which must be
rendered exactly once. A layout that fails to build (or has no default export)
fails the build; one that never renders {children} is reported as a warning.
#Async layouts
A layout can be async to await a session or feature flags, and can call
redirect() or notFound() to gate every page below it. Pages under an async
layout render per request; layouts above it stay static. See
Async layouts.
#Layout persistence
On a client-side navigation the router compares the layouts of the current and the next page and keeps every shared layout mounted: only the content of the deepest layout that differs is replaced. State, effects, focus, scroll containers and open menus in a kept layout survive the navigation, and its hydration code is not run again.
A layout under a dynamic segment (blog/[slug]/_layout.tsx) is kept only while
that segment's value is unchanged. A layout is remounted (and krate dev
logs why) when it renders a lazy() component, a <Suspense> boundary, or an
external island. Class components and error boundaries on the page do not stop
layouts from persisting.
#Templates
_template.tsx (or template.tsx) follows the layout convention but remounts
on every navigation that passes through it, including between sibling
pages and between params of the same dynamic route: its DOM is replaced and its
state and effects start fresh. In one directory the order is
layout > template > page:
// src/pages/blog/_template.tsx
export default function Template({ children }) {
return <div class="fade-in">{children}</div>;
}#Parallel routes
A directory named @name next to a _layout.tsx is a slot. The layout
receives each slot as a prop of the same name and renders it like
{children}:
// src/pages/_layout.tsx
export default function Layout({ children, modal }) {
return (
<>
<main>{children}</main>
{modal}
</>
);
}For a page under the layout, a slot renders the slot page with the same path
(@modal/settings.tsx for /settings), otherwise @modal/default.tsx. A
slot without a match and without default.tsx is a build error. On a client
navigation a slot keeps its current content when the new URL has no matching
slot page (it only resets on a full load), so add a catch-all slot page if a
navigation should clear it. Slot pages with dynamic segments are only
supported as intercepting routes (below).
#Intercepting routes
Inside a slot, a directory prefixed with (.), (..), (..)(..) or (...)
intercepts a URL: (.) matches the slot's own level, (..) one segment up,
(...) the app root. A photo gallery:
src/pages/
_layout.tsx renders {children} and {modal}
index.tsx the feed, links to /photo/1
photo/[id].tsx the full photo page
@modal/default.tsx renders nothing
@modal/(.)photo/[id].tsx the photo as a modalClicking /photo/1 from the feed renders @modal/(.)photo/[id].tsx into the
modal slot while the feed stays on screen and the address bar shows
/photo/1. Back closes the modal (the slot's previous content is restored
without a request) and forward reopens it. A full load or reload of
/photo/1 renders the real photo/[id].tsx page. Interception only applies
while the layout that owns the slot is mounted.
Intercepting pages are built as fragments under /_krate/i/<slot>/...; the
router fetches them during the soft navigation. Dynamic fragments need
krate serve (or krate dev) like any dynamic route. Intercepting directories
outside a slot are a build error.
#Loading states
A loading.tsx next to (or above) a page is overlaid during SPA transitions
while the next page is fetched. It is not a route of its own:
// src/pages/loading.tsx
export default function Loading() {
return <div class="loading">Loading...</div>;
}#Not-found and error pages
Any directory under src/pages can hold its own not-found and error page. They
follow the same rules as _layout, _template and loading: a file applies to
its directory and everything below it.
| File | Role |
|---|---|
404.tsx or not-found.tsx |
The segment's not-found page (status 404) |
error.tsx or 500.tsx |
The segment's error page (status 500): a component that receives { error, reset } |
forbidden.tsx or 403.tsx |
The page for forbidden() (status 403) |
unauthorized.tsx or 401.tsx |
The page for unauthorized() (status 401) |
None of them is a route: blog/404.tsx does not serve /blog/404. Two files
for one role in a directory (404.tsx and not-found.tsx, error.tsx and
500.tsx, forbidden.tsx and 403.tsx) are a build error (KR9001), and so is a segment page inside a
@slot or an intercepting (.)x directory (KR9002). The root 404.tsx and
500.tsx keep working as the global fallback and are still written to
dist/404.html and dist/500.html.
// src/pages/blog/not-found.tsx
export default function BlogNotFound() {
return <p>That post does not exist. <Link href="/blog/">All posts</Link></p>;
}// src/pages/blog/error.tsx
export default function BlogError({ error, reset }) {
return (
<div>
<p>Something went wrong ({error.digest})</p>
<button onClick={reset}>Try again</button>
</div>
);
}#Which page answers
The page nearest to the failure is used, walking up from the requested URL (or from the route's source directory), and it renders inside that segment's layouts, so shared navigation stays in place:
- Not found (status 404): a URL that matches no route; a dynamic route with
dynamicParams = falseand an unknown param;notFound()thrown by a page or a server component (the page nearest to the route that threw). - Error (status 500): an uncaught error while an SSR, ISR or async page is
rendered. The response keeps
X-Krate-Error: renderand is never cached. - Forbidden (status 403) and unauthorized (status 401):
forbidden()orunauthorized()called while a page renders, in an async server component, in a server action or in an API route. The nearestforbidden.tsx/unauthorized.tsxanswers, inside its layouts, like a not-found page. See Forbidden and unauthorized.
Route groups scope segment pages like they scope layouts. (shop)/cart/404.tsx
answers notFound() and unknown params of routes inside (shop), but not a URL
that matches no route at all (no route says which group the URL belongs to);
that URL gets the nearest page outside any group. Two groups cannot both define
the page of the same URL directory.
Segment pages are prerendered once (blog/404.html, blog/500.html) and picked
per request from the segments map in the build manifest. A not-found,
forbidden or unauthorized page can instead render per request: give it
export const config = { ssr: true } (or make it async, or use a runtime
component) and it is rendered for every request that lands on it, with the
status of its role, so it can read cookies, headers and request-time
configuration:
// src/pages/404.tsx
import { headers } from "@krate/runtime/server";
export const config = { ssr: true };
export default async function NotFound() {
const host = (await headers()).get("host");
return <h1>Nothing at {host}</h1>;
}A page that renders per request is never cached, and its shell is not a URL of
the site. If its render fails, or calls notFound() itself, the baked shell
(rendered at build time without request data) answers instead. This works on
krate start, krate dev and the node, Vercel and Netlify handlers, and not
with output: "static", which prerenders every page. Error pages
(error.tsx, 500.tsx) are always prerendered, because they answer while the
app is failing; an ssr mode there is ignored (KR9003). Segment pages are noindex by default
(a robots meta you set yourself wins), carry no canonical link, and are left
out of the sitemap, the route list and krate types. krate inspect and the
MCP explain tool list each route's nearest not-found and error page.
The Krate server (krate start, krate dev) picks the nearest page per
request. A static host that only knows 404.html serves the root page for every
missing URL; the per-directory files are in the output for hosts and handlers
that look them up with the manifest's segments map. The serverless handler
(krate deploy --target node|vercel|netlify|cloudflare) does the same lookup, so
segment pages work there too (see the deployment guide).
#Forbidden and unauthorized
forbidden() and unauthorized() stop a render the way notFound() does and
answer with 403 or 401. They come from @krate/runtime/server (from
@krate/runtime in a client file) and are what next/navigation exports under
the same names.
// src/pages/admin/index.tsx
import { cookies, forbidden, unauthorized } from "@krate/runtime/server";
export default async function Admin() {
const session = (await cookies()).get("session")?.value;
if (!session) unauthorized(); // 401, nearest unauthorized.tsx
if (session !== "admin") forbidden(); // 403, nearest forbidden.tsx
return <h1>Admin</h1>;
}// src/pages/forbidden.tsx (or admin/forbidden.tsx for /admin only)
export default function Forbidden() {
return <p>You are not allowed to see this. <Link href="/">Home</Link></p>;
}| Where it is called | Result |
|---|---|
| An SSR, ISR or streaming page, or an async server component it renders | The nearest forbidden.tsx / unauthorized.tsx with that status; without one, a plain-text 403 Forbidden / 401 Unauthorized |
| A server action | Fetch actions get JSON ({ "ok": false, "error": { "message": "Forbidden" } }) with status 403 / 401. A no-JS form post gets the nearest page for the page the form was posted from |
| An API route | JSON { "error": "Forbidden" } or { "error": "Unauthorized" } with that status; notFound() answers { "error": "Not Found" } with 404 |
The response is never cached: ISR does not store it, it carries
Cache-Control: no-store, and a CDN never keeps it. A client navigation
(<Link>, router.push) to a URL that answers 403 or 401 swaps the page in
place like a 404 does: layout state is kept and back and forward work.
Everything above holds in the Go server (krate start, krate dev) and in the
portable handler (krate deploy --target node|vercel|netlify|cloudflare).
Two limits follow from how Krate renders:
- Static pages and layouts never run per request. A page that is built
statically, and every layout (layouts are baked into the shell), cannot call
forbidden()usefully: the call never runs and the page is served to everyone. The build warns (KR8604). Make the page request-time (export const dynamic = "force-dynamic"), or call the function from an async server component that the page renders. Where a whole directory must be gated, use middleware. - Streaming has already sent the status. In an out-of-order streamed page the
shell is on the wire before an async child runs, so a
forbidden()raised by such a child cannot change the status. Gate the page itself, not a streamed fragment.
#The error prop
On the server, error is { name, message, digest }. In production the
message is always "Internal Server Error": the real error is written to the
server log together with the same digest, so a visitor can quote the digest
and you can find the log line. krate dev shows the real message and stack.
The message and digest are filled into the HTML the server sends; text you
derive from them while rendering (error.message.toLowerCase()) appears once
the page hydrates.
#Error boundary around the segment
An error.tsx is also a client error boundary around the segment's pages, in
Next.js order: the directory's layout, then the error boundary, then its
template and the page. A render error, an error in an effect, or a reactive
update that throws below it shows the error page in place, with the layouts
still mounted. Event handlers are not caught (the same rule as React's
boundaries).
reset()mounts the segment's children again with fresh state.- Soft navigation clears the error page. A boundary that has not caught anything stays mounted while the user moves between the pages it covers, so layouts below it keep their state; one that caught an error is replaced on the next navigation.
- The nearest boundary catches first. If an error page throws itself, the error goes to the next boundary up.
- Pages without an
error.tsxabove them ship no boundary code. 500.tsxis the server error page only; it does not add a client boundary.
During soft navigation the router shows a 404 or 500 page the server returns in
place, keeps the layouts the two routes share (the boundary of an error.tsx is
swapped with the page), and leaves the requested URL in the address bar.
#The SPA router
Internal links written as <Link> (or an anchor carrying data-krate-link)
trigger client-side navigation; a plain <a href> is an ordinary full-page
load:
<Link href="/about">About</Link>Link is built in, so it needs no import. Under a
base path, <Link>, navigate() and
krateRouter add the prefix, so write hrefs from the site root. A path read from
usePathname() already has the prefix removed; location.pathname does not, so
do not pass it to them.
SPA navigation is enabled by default. Set spa: false in the config to omit
the router from the shared runtime and use normal full-page navigation; links
and navigate() keep working. The router is part of the shared runtime, which
a page loads only when it has something to hydrate: a page with no state or
handlers ships no JavaScript, so a link on it is a full-page load (the next page
then starts the router if it needs one).
The router handles:
- Prefetching -
data-prefetchon hover/focus and viewport entry, cached for 30 seconds and used once. - Layout persistence - shared layouts stay mounted (see above).
- Scroll restoration - forward navigation scrolls to top; back/forward restores the saved position of that history entry. Hash links scroll to the target element without a request.
- Modified clicks - Cmd/Ctrl/Shift/Alt-click and middle-click are never intercepted.
- External links -
http(s)://,mailto:,tel:,#,target="_blank"anddownloadanchors are left as plain links. - GET forms - submitted client-side (opt out with
data-krate-reload).
<Link> supports prefetch={false}, replace, scroll={false}, and
target="_blank" (which auto-adds rel="noopener noreferrer"), and
basePath={false} for a URL served outside the site's base path (see
Base path). After
navigation the link matching the current path gets aria-current="page".
Programmatic navigation, events and error handling are documented in the
runtime API reference.
#Prerendered endpoints
A .ts or .js file under src/pages whose name ends in a data extension
(json, xml, txt, csv, rss, atom, webmanifest, ics, yml, yaml)
is not a page. Its GET export runs once at build time, on Node (or the
configured runtime), and the response body is written to the output as a file:
// src/pages/data.json.ts -> dist/data.json
export async function GET() {
return Response.json({ items: [1, 2, 3] });
}src/pages/blog/feed.xml.ts becomes dist/blog/feed.xml. The build fails
(KR7121) when there is no GET, it throws, or it answers a non-2xx status.
The path cannot have a dynamic segment; for a response that depends on the
request, use an API route. A .ts or .js file
under src/pages/api is not an API route and warns with KR7120: API routes
live in src/api.
#File conventions reference
| File | Purpose |
|---|---|
src/pages/_layout.tsx |
Layout wrapper for directory + children (kept mounted across navigations) |
src/pages/_template.tsx |
Like a layout, but remounted on every navigation |
src/pages/(group)/ |
Route group: organizes files, no URL segment |
src/pages/@slot/ |
Parallel-route slot, rendered by the sibling layout as the slot prop |
src/pages/@slot/default.tsx |
Slot content when no slot page matches |
src/pages/@slot/(.)x/ |
Intercepting route (soft navigation renders it into the slot) |
src/pages/404.tsx, not-found.tsx |
Not-found page of the directory (the root one is the global fallback) |
src/pages/error.tsx, 500.tsx |
Error page of the directory; error.tsx is also a client error boundary |
src/pages/forbidden.tsx, 403.tsx |
Page for forbidden() in the directory (status 403) |
src/pages/unauthorized.tsx, 401.tsx |
Page for unauthorized() in the directory (status 401) |
src/pages/loading.tsx |
Loading component during SPA transitions |
middleware.ts |
Request middleware (runs before page rendering) |
src/pages/name.json.ts |
Prerendered endpoint: GET runs at build time and writes name.json |
src/api/*.ts |
JS API routes |
src/api/*.go |
Go API routes |
Last updated: 2026-11-17
Contributors: Noinkin