Tutorial
The language
Language basics
The shape of every .wf file: the fifteen kinds of declaration, naming, comments, the two kinds of body, the two layouts and how strings are written.
This chapter covers the shape of every .wf file. A WebFluent program is a set of declarations: pages, components, stores and the rest, each a keyword followed by a name and a body. Learn the fifteen kinds and the two kinds of body, and you can read any .wf file.
In this chapter:
- the fifteen declarations, and the chapter that covers each
- how names are written
- comments, including the doc comments the editor shows
- render blocks and imperative blocks, and what goes in each
- the braced
.wflayout and the indented.wfxlayout - the three ways to write a string, and how a string splices in values
Declarations
A .wf file holds top-level declarations and nothing else. You cannot put an element or a statement loose in a file; it belongs in the body of a declaration. This file uses all fifteen kinds:
page Home(path: "/", title: "Home", description: "The front page.") { Heading("Welcome").h1 }
component Pill(_ label: String, tone: Tone = .calm) { Badge(label) }
store Cart { state items: [String] = [] derived count = items.length }
theme Brand { color-primary: #0F766E radius-md: 14px }
app { Navbar { Text("Shop").heading } Router }
type Todo { id: String, title: String, done: Bool = false }
enum Tone { calm, loud }
api Backend(base: "/api/v1") { get todos() at "todos" -> [Todo]! }
middleware timed(req, next) { return await next(req) }
const API = "/api/v1"
data posts = "posts.json"
image hero = "hero.jpg"
animation Pulse { from { opacity: 1 } to { opacity: 0.5 } }
test "pill shows its label" { Pill("Beta") expect "Beta" }
fake NoTodos for Backend { todos() { .ok([]) } }
(data and image read their files when the project builds, so this one needs a posts.json and a hero.jpg beside it to build.)
Each keyword declares one kind of thing:
| Declaration | What it is | Read more |
|---|---|---|
|
|
A route and what it shows | |
|
|
A reusable element with typed props, events, slots and parts | |
|
|
State shared across pages | |
|
|
Design tokens: colours, spacing, radii, fonts | |
|
|
The shell every page renders inside, with the |
|
|
|
Records and enumerations the type checker enforces | |
|
|
An HTTP service: its address, its endpoints and what they return | |
|
|
A step every request of a service passes through, named in its |
|
|
|
A value read everywhere | |
|
|
A JSON file read at build time, as a constant | |
|
|
A picture the build resizes and hands to |
|
|
|
Keyframes | |
|
|
A render held to expectations and a snapshot | |
|
|
What answers a service's endpoints in a test, in place of the network | |
|
|
One way to use a component, which |
Two other kinds of file under src/ join the program. A .css file is a stylesheet the build bundles. A .js file is a plain browser script, and its top-level functions are in scope by name in your .wf code (Call your own JavaScript).
Inside a body you write statements: state, derived, effect, action, persist, resource, validate, socket, if, for, match and more. The grammar lists every keyword and where it may appear.
One program from many files
All the files under src/ merge into one program. A component declared in components/Pill.wf is usable from every page without an import. The compiler reads App.wf (or App.wfx) first, then the other files in name order, so a build is the same on every machine.
Note
Coming from React? There is no import or export between .wf files. A component, a store or a type declared in any file under src/ is in scope in every other one. See Coming from React.
Naming
Names follow fixed conventions, so you can tell what a word is from how it is written:
- Declaration keywords are lowercase:
page,component,store. - The names they declare, and every element, are PascalCase:
Home,UserCard,Button,Table.Row. - State, props, actions, variables and flags are camelCase:
count,isOpen,save,.primary. - Enum cases start with a dot:
.calm,.md. - Design tokens start with a dollar sign:
$primary,$spacing-md.
The compiler resolves every name. A name it does not know — a misspelled element, a flag the element does not take, a case the enum does not have — is an error with a hint, never a silent no-op.
Comments
WebFluent has three kinds of comment. A // comment runs to the end of the line, a /* … */ comment may span lines, and a /// comment documents the declaration that follows it:
// A line comment.
/* A block
comment. */
/// A person's initials, in a circle.
component Avatar(_ initials: String) { Text(initials).bold }
A /// comment above a declaration, a prop or an event is its documentation. The editor shows it on hover, and wf docs writes it on the component's page. Above a state, persist, derived or action, it documents that member, and the editor shows it wherever the member is used.
Bodies
A body is one of two kinds of block, and each holds different statements:
- A render block is the body of a page, a component or
app. It holds elements, and the statements that shape them:state,derived,if,forand the like. - An imperative block is the body of a handler or an action. It holds statements that do something: assignments, calls,
let,if,for,try.
The two blocks have separate grammars. In this page, the Text is an element in the render block, and the assignment sits inside an on click handler:
page Counter(path: "/", title: "Counter", description: "A number that goes up.") {
state clicks = 0
Heading("Counter").h1
Text("Clicked {clicks} times")
Button("Add one") {
on click { clicks = clicks + 1 }
}
}
Warning
An assignment written loose in a page body, such as clicks = clicks + 1 next to the Text, is error E105. Its hint says where the line belongs: "Code that does something goes in on click { … }, an action or an effect".
Separating statements
Statements need no separator. You usually put one per line. To put two on one line, separate them with ; or with whitespace. Two spaces is the house style, because it reads well:
page Score(path: "/", title: "Score", description: "Two teams, two numbers.") {
state home = 1 state away = 2
Heading("Score").h1
Text("{home} – {away}")
Button("Both score") { on click { home = home + 1; away = away + 1 } }
}
Two layouts: .wf and .wfx
You can write the same grammar with braces or with indentation. A .wf file opens a block with { and closes it with }. A .wfx file opens a block with a line indented deeper than the one before it, and closes it when the indentation returns.
This page is written in the braced layout:
page Home(path: "/", title: "Home", description: "A panel that opens and closes.") {
state open = true
Heading("Home").h1
Row(gap: .sm) {
style {
padding: 6px 0
&:hover { background: $surface }
}
on click { open = !open }
Text("Details").bold
}
if open {
Spinner
} else {
Text("Closed")
}
}
The same page in the indented layout:
page Home(path: "/", title: "Home", description: "A panel that opens and closes.")
state open = true
Heading("Home").h1
Row(gap: .sm)
style
padding: 6px 0
&:hover
background: $surface
on click { open = !open }
Text("Details").bold
if open
Spinner
else
Text("Closed")
The indented layout follows these rules:
- A line indented deeper than the line before it opens a block. Indent with the same spaces or tabs as the lines around it; four spaces per level is the house style, and what
wf fmtwrites. - A line whose indentation lines up with no enclosing block is error
E003. The first line of a file is not indented. - You may still write braces yourself, and everything inside them is laid out freely:
on click { open = !open }on one line, or a map literal or an argument list across several lines. Inside parentheses and brackets, layout is free too. - An empty block is written
{ }. - Blank lines and comment lines do not count.
Both layouts compile to the same output and every tool reads both, so a project may mix them. wf fmt --to wfx converts a project to the indented layout and wf fmt --to wf converts it back, without changing what any file says. This guide writes .wf; every example has a .wfx spelling.
Strings
A string is written in double quotes and splices in a value with {expr}:
page Greeting(path: "/", title: "Greeting", description: "A greeting that knows your age.") {
state user = { name: "Sam", age: 41 }
Heading("Hello, {user.name}!").h1
Text("You are {user.age * 12} months old.")
Text("A literal brace: \{ and \}")
Text("A literal dollar: ${user.age}") // `$` alone is plain text: "$41"
}
Spliced text is live: when user changes, the text changes with it. A splice opens with a name, a ( or a [, and closes on the same line; anything else, such as {key: value} in prose, is plain text.
A splice may also say how to show its value: {total:.currency}, {when:.date(long)}. This is formatting, written where the value is read.
Three ways to write one
A plain "…" string reads the escapes \n, \t, \r, \", \\, \{ and \}, and splices {…}. For text that a plain string makes you escape over and over, there are two other forms:
// Raw: no escapes, no splices. The text is what is written.
const SAMPLE = #"page Home(path: "/") { state n = 0 }"#
// As many # as the text needs, when it holds a `"#` of its own.
const TRICKY = ##"a raw string ends with "# — like that"##
// Block: over as many lines as it likes, escapes and splices on, and
// the indentation the source gave it removed.
const name = "Ada"
const LETTER = """
Dear {name},
thank you.
""" // "Dear Ada,\n thank you."
Use each form for a different kind of text:
- A raw string (
#"…"#) suits a sample of code, a regular expression or a Windows path: anything full of quotes, braces or backslashes. - A block string (
"""…""") suits a paragraph, a template or a query. The closing"""sets how far the text was indented, and the compiler removes that much from every line.
Quick reference
| Syntax | Meaning |
|---|---|
|
|
A declaration: keyword, name, arguments, body |
|
|
Comments |
|
|
Documentation for the declaration, prop, event or member below |
|
|
Declared names and elements; state, props, actions and flags |
|
|
An enum case; a design token |
|
|
Imperative blocks, where assignments go |
|
|
Two statements on one line |
|
|
Braced layout; indented layout (grammar) |
|
|
A string with a live splice |
|
|
A splice with a format |
|
|
A raw string; a block string |
Common mistakes
An assignment loose in a page body. A render block holds elements; code that changes something belongs in a handler, an action or an effect:
page Counter(path: "/", title: "Counter", description: "A number that goes up.") {
state clicks = 0
Heading("Counter").h1
clicks = clicks + 1
Text("Clicked {clicks} times")
}
Move the line into Button("Add one") { on click { clicks = clicks + 1 } } (E105).
A comma between two statements. Commas separate arguments, never statements:
page Score(path: "/", title: "Score", description: "Two teams, two numbers.") {
state home = 1, away = 2
Heading("Score").h1
Text("{home} – {away}")
}
Write each statement on its own line, or separate them with ; or two spaces: state home = 1 state away = 2 (E002).
A name the language already has. query, env, format, now and the other built-in names cannot be a program's own:
page Search(path: "/", title: "Search", description: "Find a book.") {
state query = ""
Heading("Search").h1
Input(bind: query, label: "Search")
}
Choose another name, such as term (E118).
What you learned
-
Name the fifteen declarations a
.wffile may hold -
Tell a render block from an imperative block, and put an assignment where it belongs
-
Write two statements on one line, with
;or two spaces -
Switch a file between the braced
.wfand the indented.wfxlayout -
Splice values into a string, and write raw and block strings