weft
ir 2.6.0 · warp 1.8.0

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.

app/routes/index.tsx[slug].tsxdocs/[...].tsxx.data.ts//:slug/docs/*head · policy · slots
The route table is the file tree, and the plan that places everything on a page is generated from the same walk. Nothing is registered anywhere.
✓ Valid A parameter set, fully declared

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.

✕ Refused half the values enumerated
what you wrote→a route’s params must cover every value or none→refused

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.

sketch — not compiled
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 binds

Every 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:

The 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.

output
app/fragments/examples/crumbs.tsx
import { 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
Holes2
Escape elided0
Effect setnone — static
Wire formshtml · bundle · split · patch · delta

Holes

BindingHoleEscape
traillisttrusted-raw
heretextescape

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:

sketch — not compiled
weft routes          # the route table, and each route's slots
weft why /blog/:slug # the generated plan for one route, as JSON