# Routing > File-based routing, layouts, template syntax, and client reactivity Package: Koze Canonical: https://kuratchi.dev/docs/koze/routing Markdown: https://kuratchi.dev/docs/koze/routing.md ## Route conventions Place `.koze` files inside `src/routes/`. File paths become URL patterns. ```text src/app.koze -> document shell (, , ) src/routes/layout.koze -> shared fragment wrapping every page src/routes/index.koze -> / src/routes/about/index.koze -> /about src/routes/items/index.koze -> /items src/routes/blog/[slug]/index.koze -> /blog/:slug ``` API endpoints use a separate convention: place `.ts` or `.js` modules under `src/routes/api/`. For example, `src/routes/api/v1/status.ts` maps to `/api/v1/status`, and `src/routes/api/v1/health/index.ts` maps to `/api/v1/health`. See [API Routes](/docs/koze/api-routes) for handler exports, dynamic segments, and middleware boundaries. Three file roles, one template syntax: - **`app.koze`** — the document shell. Lives at `src/app.koze` (not inside `routes/`). Optional; the framework provides a default when absent. - **`layout.koze`** — a fragment that wraps every page. Nest `/layout.koze` for section-specific chrome. - **`index.koze`** — the page for a segment. Dynamic segments use `[brackets]`. All three use the same shape: top ` ``` What runs where: - `await $server/*` functions execute on the server at render time. The resolved values are serialized into the HTML response and hydrated into the browser copy of the script — no second round-trip for SSR data. - Non-awaited `$server/*` calls return async values exposing `.pending`, `.error`, and `.success`. On the server they participate in streaming boundaries; in the browser the same shape is preserved by RPC stubs. - Helper functions (`function onDelete(id)`) and synchronous top-level code stay in the browser copy of the script. The framework wraps DOM listeners automatically via the [`on={fn(args)}` directive](/docs/koze/client-interactivity#event-handler-directive). - Top-level statements whose bodies contain `await` are stripped from the browser bundle after hydration wiring is in place — they already ran server-side. Use `src/server/*` for private modules and backend logic. `$server/*` functions called from the browser become RPC stubs that POST to a framework-managed endpoint. For the full hydration model, dispatch rules, and `__kozeReadData` escape hatch, see [Client interactivity](/docs/koze/client-interactivity). ## Browser-only code Routes allow one ` ``` If a third-party module touches `window` during import, wrap the import in a lazy `$lib/*` helper and call that helper from a browser event. ## Layouts `src/routes/layout.koze` is a **fragment** that wraps every page. Not a document — no ``, no ``, no ``. Those live in `app.koze`. ```html
Home Items
``` ### Nested layouts Drop a `layout.koze` at any directory depth. It wraps every route under that directory, composed with the root layout outside and the page inside. ```text src/routes/ ├─ layout.koze ← wraps every page ├─ index.koze ← / └─ admin/ ├─ layout.koze ← wraps /admin/* ├─ users/ │ └─ index.koze ← /admin/users (root + admin layouts) └─ settings/ ├─ layout.koze ← wraps /admin/settings/* └─ index.koze ← /admin/settings (root + admin + settings) ``` Composition at render time goes **innermost first**: the route's HTML is wrapped by its nearest layout, the result is wrapped by the next layout up, and so on until the root layout hands its output to the app shell. That means an author writing `` in a nested layout receives the already-wrapped child markup — the inner layout is closer to the content it's decorating than the outer one. Each layout is a self-contained fragment: its top ` ``` Template text and attributes that read reactive state are also live: ```html

{selectOptions.length} available cells

``` Loop locals stay available to client bindings: ```html for (const item of rows) { } ``` ### Components ```html

Live

 ``` Package components like `kuzan/*` are optional. Local `.koze` components and package components are first-class. ### Component Props Components receive props via `koze:component`. Destructure in the component's `
if (title) {

{title}

}
``` **Props patterns:** - Import and destructure with defaults: `const { title, size = 'md' } = props<{ title?: string; size?: string }>();` - Access directly in template: `{props.title}` or `data-variant={props.variant}` - Use `class:` for className (reserved word): `const { class: className = '' } = props<{ class?: string }>();` - Children go in `` ## Client reactivity Use `$:` inside the top ` ``` Rules: - The top `