Routing
Declare routes, shells, middleware, and render modes in one src/routes.ts manifest, with typed links, path params, and search params.
On this page
Route manifest
Define the manifest in src/routes.ts with defineApp, route, and group:
import { defineApp, group, route, timeRevalidate } from "@pracht/core";
export const app = defineApp({
shells: {
public: "./shells/public.tsx",
app: "./shells/app.tsx",
},
middleware: {
auth: "./middleware/auth.ts",
},
routes: [
group({ shell: "public" }, [
route("/", "./routes/home.tsx", { render: "ssg" }),
route("/pricing", "./routes/pricing.tsx", {
render: "isg",
revalidate: timeRevalidate(3600),
}),
]),
group({ shell: "app", middleware: ["auth"] }, [
route("/dashboard", "./routes/dashboard.tsx", { render: "ssr" }),
route("/settings", "./routes/settings.tsx", { render: "spa" }),
]),
],
});URLs do not depend on file layout. Route modules live in src/routes/ by
convention, but any path works, and shells and middleware are named references
that any route or group can use.
The string paths tell the build which modules exist. A file the manifest never names, such as a draft, stays out of the client bundle.
To derive routes from files instead of writing a manifest, use the pages router.
API reference
defineApp(config)
shells and middleware map names to module paths, and routes is the route
tree. The config reference lists every defineApp
field.
route(path, file, meta?)
path is a URL pattern such as /blog/:slug. file is the route module's
path relative to src/routes.ts, even when route() is called from an
imported module. meta is an optional RouteMeta:
| Field | Type | Description |
|---|---|---|
id |
string | Stable route id for typed routes and <Link route>. Generated from the path when omitted |
capabilities |
string[] | WebMCP page tools active while this route is current |
render |
"ssr" | "ssg" | "isg" | "spa" |
Render mode. Defaults to "ssr" |
hydration |
"full" | "islands" | "none" |
How much of the page hydrates. See Islands |
shell |
string | Named shell that wraps this route |
middleware |
string[] | Named middleware to run before the loader |
prefetch |
"intent" | "viewport" | "hover" | "none" |
JS prefetch strategy. Defaults to "intent" |
speculation |
"prefetch" | "prerender" | { mode, eagerness } |
Browser speculation rules opt-in |
revalidate |
RouteRevalidate | timeRevalidate() / webhookRevalidate() for ISG routes |
loaderCache |
LoaderCache | Cache-Control policy for this route's loader response |
streaming |
boolean | Stream deferred values on full-hydration SSR routes. See Data loading |
markdown |
boolean | Declare that middleware negotiates a Markdown representation for this route |
group(meta, routes)
group() applies shared meta to its children: shell, middleware, render,
hydration, capabilities, loaderCache, speculation, streaming, and an
optional pathPrefix.
A route's own scalar settings override the group's. middleware and
capabilities add to the group's lists instead, so a route keeps its group's
page tools and adds its own. Navigation swaps in the destination route's tools,
and hydration: "none" routes cannot activate page tools.
Path patterns
route("/about", "./routes/about.tsx"); // /about only
route("/blog/:slug", "./routes/blog-post.tsx"); // /blog/hello-world → params.slug
route("/users/:userId/posts/:postId", "./routes/user-post.tsx"); // two params
route("/docs/*", "./routes/docs.tsx"); // /docs/a/b/c → params["*"] = "a/b/c"
route("/files/:path*", "./routes/files.tsx"); // same match, captured as params.pathMatch order
The first declared route that matches wins, so put specific routes first:
route("/blog/new", "./routes/new-post.tsx"), // first, or /blog/:slug takes it
route("/blog/:slug", "./routes/blog-post.tsx"),The dev server warns when an earlier route matches every URL a later one does, or when two routes share an id.
Reading params
Loaders, middleware, and API routes receive matched params as params:
export async function loader({ params }: LoaderArgs) {
return { post: await getPost(params.slug) };
}In a component, useParams() reads them from the active route, and returns
{} when no route is active. Fetch data with the loader's params, not
useParams().
import { useParams } from "@pracht/core";
export default function BlogPost() {
const { slug } = useParams();
return <article data-slug={slug}>…</article>;
}A catch-all segment is exposed under the key "*":
const { "*": rest } = useParams(); // /docs/a/b/c → "a/b/c"Not-found page
Set notFound to render a page with status 404 when a request matches no
route:
export const app = defineApp({
shells: { public: () => import("./shells/public.tsx") },
notFound: {
component: () => import("./routes/not-found.tsx"),
shell: "public",
},
routes: [...],
});create-pracht generates this entry and src/routes/not-found.tsx
(src/pages/404.tsx with the pages router). The shorthand
notFound: () => import("./routes/not-found.tsx") takes the route module
directly; the full form also accepts loader, middleware, and hydration.
Use notFound instead of a trailing route("/*", ...). A catch-all route
shadows static assets and later routes, and appears in typed routes,
prefetching, and SSG paths; notFound runs only after routes and static assets
both miss.
The page also renders when a loader or middleware throws
notFound(), unless the route exports its
own ErrorBoundary. Route-state and non-GET requests get a plain 404, as do
apps without notFound.
Search params
Export a search schema from a route module to validate its query string. Any
Standard Schema validator works, the same contract
defineApi() uses:
import { Link, useSearch, type ErrorBoundaryProps, type LoaderArgs, type SearchArgs } from "@pracht/core";
import * as z from "zod";
export const search = z.object({
page: z.coerce.number().int().min(1).default(1),
q: z.string().optional(),
});
export async function loader(args: LoaderArgs & SearchArgs<typeof search>) {
return listProducts(args.search); // { page: number; q?: string }
}
export function Component() {
const { page, q } = useSearch("products");
return <Link route="products" search={{ page: page + 1, q }}>Next page</Link>;
}
// A query the schema rejects renders here, with status 400.
export function ErrorBoundary({ error }: ErrorBoundaryProps) {
return <ul>{error.issues?.map((issue) => <li>{issue.path?.join(".")}: {issue.message}</li>)}</ul>;
}The loader, head(), and headers() receive the parsed value as args.search,
and components read it with useSearch(). After typegen,
useSearch("products") returns the schema's output, and <Link search>,
navigate(), and href() accept only the keys its input declares. Routes
without a schema get the raw query. useSearchParams() is unaffected.
The schema receives one string per key, or an array when a key repeats
(?tag=a&tag=b). Coerce numbers and booleans (z.coerce.number()), and give
optional keys a default so the bare URL stays valid. A key that may repeat
arrives as a single string when it appears once:
tag: z.array(z.string()).or(z.string().transform((tag) => [tag])).default([]),A rejected query never reaches the loader. The route's ErrorBoundary renders
instead, with error.status 400 and the validation issues on error.issues,
on the first request and on client navigation.
On prerendered routes
SSG and ISG pages are built without a query, so their loader and head() see
the schema's defaults, and a schema that rejects an empty query fails to
prerender. After hydration, useSearch() reads the visitor's query while
loader data stays build-time, and a rejected query swaps in the ErrorBoundary
on a page served with 200. Keep query-dependent data on SSR or SPA routes.
Typed routes and links
Run pracht typegen to generate a type-safe route map:
pracht typegenIt writes src/pracht.d.ts (route ids and param types) and
src/pracht-routes.ts (an adapter-agnostic href() helper):
import { Link, useNavigate } from "@pracht/core";
import { href } from "../pracht-routes";
export function ProductActions({ id }: { id: string }) {
const navigate = useNavigate();
return (
<>
<Link route="product" params={{ id }} search={{ ref: "home" }}>
View product
</Link>
<button onClick={() => void navigate({ route: "product", params: { id } })}>
Open product
</button>
<a href={href("product", { params: { id }, search: { tab: "details" } })}>
Details
</a>
</>
);
}Run pracht typegen --check in CI to catch stale generated files. A route with
a search schema gets its search option typed from the
schema's input, required when the schema has a required key.
<Link> props
<Link> accepts every anchor attribute (target, rel, download, ping,
referrerpolicy, hreflang, class, event handlers) plus:
| Prop | Type | Description |
|---|---|---|
route |
RouteId | Required. The route id to navigate to |
params |
Record<string, unknown> | Values for the route's dynamic segments |
search |
object | string | Query string to append, typed by the route's search schema |
hash |
string | Fragment to append |
prefetch |
"intent" | "hover" | "viewport" | "render" | "none" |
Override the route's prefetch strategy for this link |
speculate |
boolean | Opt this link out of or back into speculation rules |
preserveScroll |
boolean | Keep the current scroll position and focus instead of starting at the top |
viewTransition |
boolean | Wrap this navigation in document.startViewTransition() where supported |
href is not a <Link> prop
<Link> builds its own href from route and params, so passing one is a
compile error:
<Link href="/blog/hello">Read</Link> // ✗ does not typecheck
<Link route="blog-post" params={{ slug: "hello" }}>Read</Link> // ✓Use a plain <a href> for external and user-provided URLs. A wrapper that
spreads anchor props onto <Link> must omit href from its props type:
type ButtonLinkProps = Omit<JSX.IntrinsicElements["a"], "href"> & {
route: RouteId;
};
function ButtonLink({ route, ...rest }: ButtonLinkProps) {
return <Link route={route} {...rest} />;
}Shells
A shell is a layout component that wraps route content. Shells are independent
of URL structure: /settings can use the app shell without living under
/app.
import type { ShellProps } from "@pracht/core";
export function Shell({ children }: ShellProps) {
return (
<div class="app-layout">
<Sidebar />
<main>{children}</main>
</div>
);
}See Shells for shell data, head(),
headers(), and error boundaries.
Middleware
Middleware wraps the request through next() and can redirect, add to the
context, or return its own response:
import { redirect, type MiddlewareFn } from "@pracht/core";
export const middleware: MiddlewareFn = async ({ request }, next) => {
const session = await getSession(request);
if (!session) return redirect("/login", { request });
return next();
};Group middleware runs first, then route middleware, then the loader; see Middleware.
Path prefix groups
Set pathPrefix on a group to prefix every child path:
group({ pathPrefix: "/admin", shell: "admin", middleware: ["auth"] }, [
route("/", "./routes/admin/index.tsx"), // → /admin
route("/users", "./routes/admin/users.tsx"), // → /admin/users
route("/settings", "./routes/admin/settings.tsx"), // → /admin/settings
]);Trailing slashes
Set trailingSlash on the Vite plugin to make one spelling canonical:
export default defineConfig({
plugins: [pracht({ trailingSlash: "always" })], // or "never"
});| Setting | /about |
/about/ |
|---|---|---|
| unset (default) | Renders the page | Renders the page |
"always" |
308 to /about/ |
Renders the page |
"never" |
Renders the page | 308 to /about |
Redirects keep the query string. Links, href(), redirect(), llms.txt, and
speculation rules emit the canonical spelling (/about when unset).
The root (/, or the deploy base) always
keeps its slash, and a last segment with a dot, such as /feed.xml, never gets
one. API routes, static files, and Markdown requests answer either spelling.
Every adapter applies the policy, including to prerendered pages. On
Cloudflare, set the assets binding's html_handling to match
(Adapters). A static export writes
about/index.html, which most hosts serve at /about/, so pair it with
"always".