Skip to content

The app framework ​

Weft has an app framework built in. It is optional: a project with a routes/ directory is an app, and where a file sits says what it is, as in SvelteKit or Next. A project without routes/ is plain Weft.

The tree ​

text
app.weft                     the app: its name, permissions, globals (optional)
routes/                      pages, by URL path
  layout.weft                wraps every page below it
  page.weft                  /
  error.weft                 shown when a page below it fails
  todos/page.weft            /todos
  todos/[id]/page.weft       /todos/:id
  (account)/settings/page.weft   /settings: a group adds no path segment
  docs/[...path]/page.weft   /docs/a/b/c
  api/todos/server.weft      an HTTP endpoint
components/                  components, found by file name
lib/                         modules
lib/server/                  modules only the server runs (the client imports their server functions and types)
static/                      files served as they are

Pages and parameters ​

A page is a page.weft under routes/. Its URL comes from its folders. [id] is a parameter, and the page reads it with prop params, typed from the path. page({…}) holds only what the path can't say, such as the label:

routes/todos/[id]/page.weft
weft
import { findTodo } from "lib/todos"

page({ label: "Todo" })

prop params: { id: string }

derived todo = findTodo(params.id)
---
@if todo == null {
  <Text>No todo {params.id}.</Text>
} @else {
  <TodoCard {todo} />
}
lib/todos.weft
weft
export type Todo = { id: string, title: string, done: boolean }

let all: Todo[] = [
  Todo { id: "1", title: "Write the guide", done: true },
  Todo { id: "2", title: "Ship the site", done: false },
]

export fn findTodo(id: string): Todo? {
  return all.find(t => t.id == id)
}
components/TodoCard.weft
weft
import type { Todo } from "lib/todos"

prop todo: Todo
---
<Box class="rounded border p-3">
  <Text class="font-medium">{todo.title}</Text>
  <Text>{todo.done ? "Done" : "Open"}</Text>
</Box>

<TodoCard> needs no import: a tag names the component in components/ with that file name. A prop params that doesn't match the path, such as { slug: string } here, is an error.

A [...path] parameter takes the rest of the URL as a string[], possibly empty.

The head and the sitemap ​

page({…}) also says what goes into the page's <head>: title (else the label), description, image (for link previews), canonical and robots.

routes/about/page.weft
weft
page({
  label: "About",
  title: "About us · Todos",
  description: "Who makes Todos, and why.",
  image: "https://example.com/about.png",
  canonical: "https://example.com/about",
})
---
<Text>About us.</Text>

The server writes the description, the canonical link and Open Graph and Twitter cards from them, and serves /sitemap.xml (every page without parameters, except robots: "noindex" ones) and /robots.txt, unless static/ has its own. Set site = "https://example.com" in weft.toml for the sitemap's addresses.

page({…}) holds literals. When the head depends on the page's data, draw a <Head>:

routes/posts/[id]/page.weft
weft
page({ label: "Post" })

prop params: { id: string }

derived title = `Post ${params.id}`
---
<Head title={title} description="One post of the blog." />
<Text>{title}</Text>

Each field overrides page({…})'s, and the deepest component's wins, so a layout can set the site's image while each page sets its own title. It updates as the data changes, and on the desktop it is the window's title.

Layouts ​

A layout.weft wraps every page below it. The compiler gives it a children snippet, the page, which it shows with @render children(). A layout's state lasts as long as navigation stays below it.

routes/layout.weft
weft
---
<Box class="flex flex-col">
  <Box class="border-b p-3">
    <Text class="font-semibold">Todos</Text>
  </Box>
  <Box class="p-4">
    @render children()
  </Box>
</Box>

Errors ​

A page or layout can't fail with an error: like any component, it handles its errors where they occur (Errors). When one panics while loading or drawing, which is a bug, the nearest error.weft above it is shown in its place, inside the layouts above that error.weft. It gets the panic as a prop, { name, message }:

routes/error.weft
weft
prop error: Panic
---
<Box class="p-4">
  <Text class="font-semibold">Something went wrong</Text>
  <Text>{error.message}</Text>
</Box>

Components and modules ​

components/ui/Avatar.weft
weft
prop name: string
---
<Box class="flex size-8 items-center justify-center rounded-full bg-muted">
  <Text class="text-sm font-medium">{name[..1]}</Text>
</Box>
routes/page.weft
weft
import { greeting } from "lib/server/hello"
let mut text = ""
text = try await greeting("Ada") else ""
---
<Avatar name="Ada" />
<Text>{text}</Text>
lib/server/hello.weft
weft
export action fn greeting(name: string): string {
  return `Hello, ${name}`
}

Files under components/ are found by their file name, with no import; subfolders are only for order. Two components with one name are an error. A component in a route folder is private to that folder and the ones below it.

Modules under lib/ are imported as in any project. From lib/server/ or a server.weft, client code imports only server functions and types: the functions run on the server, and the client calls them over the network.

Endpoints and routes in code ​

A server.weft under routes/ is an HTTP endpoint: it exports a function per method, GET, POST and so on. An app can also export a router from app.weft, served beside the file routes; a path both define is an error. Both use std/http (its reference).

routes/api/todos/server.weft
weft
import { json } from "std/http"
import type { Request, Response } from "std/http"

export async fn GET(req: Request): Response {
  return json([{ id: 1, title: "Write the guide", done: true }])
}

routes is generated from the tree: every page is a function of its parameters returning a Route, so a link to a page that doesn't exist, or one missing a parameter, is a compile error. A page's query parameters are the ones it declares with prop query. Link is the framework's component for links.

routes/page.weft
weft
---
<Link to={routes.todos.id({ id: "a1" })}>The first todo</Link>
<Link to={routes.search({ q: "milk", page: 2 })}>Search</Link>
routes/todos/[id]/page.weft
weft
prop params: { id: string }
---
<Text>Todo {params.id}</Text>
routes/search/page.weft
weft
prop query: { q?: string, page?: number }
---
<Text>Results for {query.q ?? ""}</Text>

A Route is data: { path, params, query, href }, and route.isActive says whether the current page is it or below it. Renaming a page's folder makes every link to it an error until it is updated. Route.url("https://…") is a Route to another site.

Running an app ​

weft run on an app's project runs the framework: it serves the pages, the endpoints and the exported router. weft dev does the same and swaps each edit into the open pages keeping their state (hot swap); Alt+Shift+E shows the editor's overlay, which points out the source of any element. A program that wants to set the framework up itself uses std/app:

server/main.weft
weft
import { app } from "std/app"

try await app.serve("./routes", { port: 8080 })

User trees ​

main.weft
weft
import { app } from "std/app"
import { session } from "std/http"
import type { Request } from "std/http"
import { dir } from "std/sandbox"

let trees = dir("trees")

try await app.serve(async (req: Request) => {
  let user = try await session(req).user()
  return [user != null ? trees.tree(user.id) : null, "./routes"]
})

The compiler and the runtime read an app's files through a source: a directory, a built bundle, or a database table or S3 prefix. app.serve takes the trees to serve for each request, first one first: here a signed-in user's own pages, then the app's routes/. A user tree sees only itself and what the app hands it, and runs through std/sandbox, so it imports no I/O module. This is how an app lets its users edit their part of it (User-editable apps).

Weft is in development. The reference is the spec as it stands today.