An application is a folder
The route table is the file tree, and the plan that places everything on a page is generated from it.
params: { category: [’pantry’, ’household’] } is one document per value, each proved on its own — so a passing check for one says nothing about the other.
Files for some URLs of a route and a live render for the rest is the one outcome nobody could debug.
In plain terms
Where a file sits is its URL. A name in square brackets is a parameter, three dots is a wildcard, and a .data.ts beside a page is that page’s declaration. A layout.tsx in a directory wraps every route beneath it.
A convention is only worth having if it is the single source of the route table, so nothing downstream of the file tree may add a route. A page that is not in app/routes/ does not exist.
app/
layout.tsx the document. Its <slot> holes are what a route fills
routes/index.tsx /
routes/about.tsx /about
routes/blog/[slug].tsx /blog/:slug
routes/docs/[...].tsx /docs/*
routes/docs/layout.tsx wraps every route at or under /docs
routes/x.data.ts x.tsx's head, cache policy, loader, guard and slots
routes/x.css linked only by the pages that render x
layouts/<name>.tsx an alternate document, chosen with defineRoute({ layout })
slots/<name>.tsx fills the layout hole of that name on every route
fragments/<name>.tsx a component, referenced by name from a route's slots
intents/**.ts mutations. The manifest is generated from this directory
renderables/**.ts fragments a client may ask for by opaque id
styles.css appended after the framework's own
weft.config.ts what this deployment bindsEvery path in that tree, with what the framework does with it, is on the files and directories reference — parsed out of the walk that implements the convention, so a path the framework stops recognising stops being listed.
Two files, one route
A route is a .tsx, or a .data.ts that says what renders its body, or both. A page whose content is markup rather than a template needs no template file, and requiring an empty one would be ceremony rather than convention.
The .data.ts is where placement lives — which fragment fills which hole, what streams, what is cached and for how long. It is read at build time, so what it says becomes part of the generated plan rather than a branch taken per request.
Specificity decides, never file order
Static beats a param, a param beats a wildcard, segment by segment. /product/new wins over /product/:sku whether or not anybody remembered to write them in the right sequence — a table whose behaviour depends on the order somebody happened to write it in is a table nobody can safely refactor.
A param is data, and so is a wildcard
A [slug] segment is a parameter and a [...] segment is the rest of the path. Both arrive as values, which means what a route renders from them is an ordinary list hole rather than a component that walks something at runtime:
What a wildcard route renders
examples/crumbsThe file is routes/docs/[...].tsx and the path it matched is data — so a breadcrumb is a list hole, and nothing in it knows how deep the URL was.
app/fragments/examples/crumbs.tsximport { fragment } from '@weftjs/core'
interface Crumb {
href: string
label: string
}
/**
* What a wildcard route renders: the segments it matched, as one row template. The `<ol>` is not
* decoration — a list must be the only child of its element, so the trail gets its own element and
* the current page sits outside it (`E_LIST_NOT_SOLE_CHILD`). See `spec/compiler/supported-subset.md`.
*/
export default fragment(({ trail, here }: { trail: Crumb[]; here: string }) => (
<nav class="crumbs" aria-label="Breadcrumb">
<ol>
{trail.map((crumb) => (
<li>
<a href={crumb.href}>{crumb.label}</a>
</li>
))}
</ol>
<span aria-current="page">{here}</span>
</nav>
))
What the compiler knows
Holes
| Binding | Hole | Escape |
|---|---|---|
trail | list | trusted-raw |
here | text | escape |
What the client wires on adoption
No wiring: nothing on this template changes after it is painted, so the client attaches nothing to it.
- Sealed templates
- 2
- Version
614ac66035a0ffc69ffa3546997aecf7
See what it produced
Two commands answer "what did the convention decide", and neither needs a running server:
weft routes # the route table, and each route's slots
weft why /blog/:slug # the generated plan for one route, as JSON