Appearance
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 arePages 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 }])
}Links
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).