Appearance
Modules and projects
Projects and ids
text
weft.toml the project's root
lib/dates.weft id lib/dates
lib/server/db.weft id lib/server/db
server/main.weft id server/mainA project is a directory tree of .weft files. Its root holds a weft.toml, or is the directory the tool runs in. weft.toml holds only what tools need before code runs, every key optional (an empty file is fine):
toml
main = "server/main.weft" # the program `weft run` runs; an app (routes/) serves without one
component = "Counter" # what a window opens
[db] # the schema and database `weft db` works on (Data)
schema = "db/schema"
url = "$DATABASE_URL"
[test.replace] # modules `weft test` swaps (Tests)
"lib/server/db" = "lib/server/db.test"Each file has an id: its path from the root without .weft, such as lib/dates or server/main.
Imports name a file by its id, relative to the importing file, or from the standard library:
| import | what it brings in |
|---|---|
import { plural, round as r } from "lib/text" | names a module exports, by the file's id |
import Row from "./Row" | a component (its default export), relative to this file |
import type { Todo } from "../lib/todos" | types only (a type's variants come with it) |
import * as dates from "std/time" | a whole module, here from the standard library |
Imports are static and can't form a cycle.
Every free function comes from a module, the standard library's included: ceil from std/math, parse from std/json, log from std/log, now and setTimeout from std/time, plural from std/format, uuid from std/random (the prelude). Using one without its import is an error, and the compiler offers to add the import. Only the types and their methods need none: xs.map(…), s.trim(), Task.all(…), Bytes.fromUtf8(…).
weft
import { ceil } from "std/math"
import { plural } from "std/format"
export fn pages(items: number, perPage: number): string {
return plural(ceil(items / perPage), "page")
}A module
A module holds import, export, type, fn, query fn, mutation fn, action fn, let, let mut, global and context declarations, and its top level may run statements and await.
lib/todos.weft
weft
export type Todo = { id: number, title: string, done: boolean }
export type AddError = TooMany { max: number }
export let MAX = 100
export fn open(todos: Todo[]): Todo[] {
return todos.filter(t => !t.done)
}
export fn add(mut todos: Todo[], title: string): void ! AddError {
if todos.length >= MAX { fail TooMany { max: MAX } }
todos.push(Todo { id: todos.length + 1, title, done: false })
}lib/report.weft
weft
import { open, add } from "lib/todos"
import type { Todo } from "lib/todos"
export fn summary(todos: Todo[]): string {
return `${open(todos).length} of ${todos.length} open`
}
export fn example(): string {
let mut todos: Todo[] = []
try add(&todos, "Write the guide")
return summary(todos)
}import type imports only types: AddError here, which example doesn't need to name, since it only passes the error on.
Runs once per process
A module runs once per process, when it is first imported. Its lets are computed then, and every importer sees the same values. A let that literals alone decide, like MAX, is computed at compile time.
A module's top level may await, and an importer waits for it. So a resource such as a database connection is made once, in a module, and imported wherever it's needed. Nothing has to pass it around:
db/schema.weft
weft
import { table, schema, primary, index, flag } from "std/db"
export type User = { @primary id: string, name: string }
export type Todo = { @primary id: number, title: string, done: boolean, @index shared: boolean }
export let todos = table<Todo, User>("todos", { read: flag("shared") })
export let app = schema({ tables: { todos } })lib/server/db.weft
weft
import { postgres } from "std/db"
import { env } from "std/process"
import { app } from "db/schema"
export let db = try await postgres(app, env("DATABASE_URL")!)env(name) gives a string?: null when the variable isn't set, so the ! panics then. Connecting can fail with a DbError, and the top-level try passes it on: the module fails to load, and so does every module that imports it. weft run prints the error and exits with code 1. Tests can replace a module by its id (an in-memory SQLite for lib/server/db), so code that imports a resource stays testable.
Module state
A module let mut is process state: one value per running program (a server process, a browser tab), shared by every function in the module, and not reactive. It suits caches and counters in a backend. It can't be exported; export functions that use it instead. A query fn can't read it, and a mutation fn can't change it (The server).
lib/ids.weft
weft
let mut last = 0
export fn nextId(): number {
last += 1
return last
}Globals
A global is shared, reactive state for the components of an app. Every instance that imports it reads and writes the one value, and writing it updates every screen that shows it:
lib/theme.weft
weft
export global theme: "light" | "dark" = "light"ThemeToggle.weft
weft
import { theme } from "lib/theme"
---
<Pressable onpress={theme = theme == "light" ? "dark" : "light"}>
<Text>Theme: {theme}</Text>
</Pressable>Context
A context is a value a component provides to the instances below it. A reader gets the nearest provider's value, or the default when nothing above provides one. Readers can't write it; a provider that wants them to change it puts functions in it.
lib/density.weft
weft
export context density: "compact" | "normal" = "normal"Settings.weft
weft
import { density } from "lib/density"
import Row from "./Row"
prop compact = false
provide density = if compact { "compact" } else { "normal" }
---
<Row label="Notifications" />
<Row label="Privacy" />Row.weft
weft
import { density } from "lib/density"
prop label: string
---
<Box class={density == "compact" ? "py-1" : "py-3"}>
<Text>{label}</Text>
</Box>Globals and contexts belong to components. Server code has neither; per-request values such as the signed-in user are std/http's.
A program
A program is a file whose top level does the work. weft run tools/count.weft runs it: arguments, the environment and the exit code come from std/process.
tools/count.weft
weft
import { args, exit } from "std/process"
import { log, error } from "std/log"
let words = args()
if words.length == 0 {
error("usage: count <words…>")
exit(2)
}
log(`${words.length} words, ${words.join("").length} letters`)weft run on a whole project runs the entry its weft.toml names (main = "server/main.weft"), or the app framework when the project has routes/. weft dev runs the same and, for an app, swaps each edit into the open pages keeping their state. Programs run on the VM today; an app's pages open in a desktop window until the server comes. The server shows a backend written this way.