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.
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| Path | What it is |
|---|---|
app/layout.tsx | the document. Its `<slot>` holes are what a route fills |
app/routes/<dir>/layout.tsx | a 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.ts | x.tsx's declaration: head, cache, load, guard, slots |
app/routes/x.css | x.tsx's own stylesheet, linked only by the pages that use it |
app/routes/x.scoped.css | the same, narrowed to the elements x.tsx declares. See `scoped.ts` |
app/client.ts | the application's own client code, loaded after adoption |
app/layouts/error.tsx | the 404 and the 500. Absent means the framework's own |
app/layouts/<name>.tsx | an alternate document, chosen with defineRoute({ layout }) |
app/slots/<name>.tsx | fills the layout hole of that name on every route |
app/fragments/<name>.tsx | reusable, referenced by name from a route's slots |
app/intents/**.ts | intents. The manifest is generated from this directory |
app/renderables/**.ts | fragments a client may ask for by opaque id. Same derivation |
app/styles.css | appended 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.
| Path | What it is |
|---|---|
app/layout.tsx | the document. Its `<slot>` holes are what a route fills |
app/client.ts | the application's own client code, loaded after adoption |
app/styles.css | appended 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.
| Path | What it is |
|---|---|
app/routes/<dir>/layout.tsx | a 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.ts | x.tsx's declaration: head, cache, load, guard, slots |
app/routes/x.css | x.tsx's own stylesheet, linked only by the pages that use it |
app/routes/x.scoped.css | the 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.
| Path | What it is |
|---|---|
app/layouts/error.tsx | the 404 and the 500. Absent means the framework's own |
app/layouts/<name>.tsx | an 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.
| Path | What it is |
|---|---|
app/slots/<name>.tsx | fills 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.
| Path | What it is |
|---|---|
app/fragments/<name>.tsx | reusable, 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.
| Path | What it is |
|---|---|
app/intents/**.ts | intents. 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.
| Path | What it is |
|---|---|
app/renderables/**.ts | fragments 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.