weft
ir 2.6.0 · warp 1.8.0
generatedread out of the source that implements it

Files and directories

Every path the framework gives a meaning to, read out of the convention the discovery walks.

A weft application is a folder. The route table is the file tree, and nothing downstream of it may add a route — weft build generates plans from what the discovery found, and a page that is not in app/routes/ does not exist.

The rules are the ones Nuxt, Remix and SvelteKit converged on, because somebody arriving here should not have to learn a third vocabulary for the same idea. What is different is what a file may say, and that is the rest of this section.

The table below is parsed out of the doc comment the discovery keeps beside the walk itself, so a path the framework stops recognising stops appearing here.

the whole convention, as a tree
app/
  layout.tsx              the document. Its <slot> holes are what a route fills
  layouts/error.tsx       the 404 and the 500. Absent means the framework's own
  layouts/<name>.tsx      an alternate document, chosen with defineRoute({ layout })
  client.ts               the application's own client code, loaded after adoption
  styles.css              appended after the framework's own
  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
  routes/x.scoped.css     the same, narrowed to the elements x.tsx declares
  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
weft.config.ts            what this deployment binds
PathWhat it is
app/layout.tsxthe document. Its `<slot>` holes are what a route fills
app/routes/<dir>/layout.tsxa nested layout, wrapping every route at or under <dir>
app/routes/index.tsx/
app/routes/about.tsx/about
app/routes/blog/[slug].tsx/blog/:slug
app/routes/docs/[...].tsx/docs/*
app/routes/x.data.tsx.tsx's declaration: head, cache, load, guard, slots
app/routes/x.cssx.tsx's own stylesheet, linked only by the pages that use it
app/routes/x.scoped.cssthe same, narrowed to the elements x.tsx declares. See `scoped.ts`
app/client.tsthe application's own client code, loaded after adoption
app/layouts/error.tsxthe 404 and the 500. Absent means the framework's own
app/layouts/<name>.tsxan alternate document, chosen with defineRoute({ layout })
app/slots/<name>.tsxfills the layout hole of that name on every route
app/fragments/<name>.tsxreusable, referenced by name from a route's slots
app/intents/**.tsintents. The manifest is generated from this directory
app/renderables/**.tsfragments a client may ask for by opaque id. Same derivation
app/styles.cssappended after the framework's stylesheet

A route is a .tsx, or a .data.ts that says what renders its body — 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 application. Everything the framework discovers is under here, and the directory itself is named by srcDir if it should not be app.

PathWhat it is
app/layout.tsxthe document. Its `<slot>` holes are what a route fills
app/client.tsthe application's own client code, loaded after adoption
app/styles.cssappended after the framework's stylesheet

The route table. The file tree is the routes, and nothing downstream of this directory may add one — there is no router to register with. What a route may declare is defineRoute.

PathWhat it is
app/routes/<dir>/layout.tsxa nested layout, wrapping every route at or under <dir>
app/routes/index.tsx/
app/routes/about.tsx/about
app/routes/blog/[slug].tsx/blog/:slug
app/routes/docs/[...].tsx/docs/*
app/routes/x.data.tsx.tsx's declaration: head, cache, load, guard, slots
app/routes/x.cssx.tsx's own stylesheet, linked only by the pages that use it
app/routes/x.scoped.cssthe same, narrowed to the elements x.tsx declares. See `scoped.ts`

Alternate documents, chosen per route with layout. error.tsx is the reserved one: it is the 404 and the 500, and without it the framework serves its own.

PathWhat it is
app/layouts/error.tsxthe 404 and the 500. Absent means the framework's own
app/layouts/<name>.tsxan alternate document, chosen with defineRoute({ layout })

A fragment that fills the layout hole of its own name on every route, so a header or a footer is written once. A route that declares the same slot name wins for that route.

PathWhat it is
app/slots/<name>.tsxfills the layout hole of that name on every route

Components. Referenced by name from a route’s slots, and by name from another fragment. Being here does not make one reachable by a browser — that is the next directory.

PathWhat it is
app/fragments/<name>.tsxreusable, referenced by name from a route's slots

Mutations, and the only thing in the framework allowed to write. The manifest is generated from this directory, so an intent’s id is its module path and its export name and nothing else. See defineIntent.

PathWhat it is
app/intents/**.tsintents. The manifest is generated from this directory

The catalogue: fragments a browser may ask for, by opaque id. A separate directory from fragments/ because the set of things a client can name is a security boundary and it should be visible in the file tree. See defineRenderable.

PathWhat it is
app/renderables/**.tsfragments a client may ask for by opaque id. Same derivation

The tree above says where a file goes. What it may declare is the rest of this section: defineRoute for a .data.ts, defineIntent for a module under app/intents/, defineRenderable for one under app/renderables/, and weft.config.ts for the deployment around all of it.