Tutorial
The tour
Tutorial: Shelf
Build a small, complete site — data, components, a store, a form, a theme, a test — and put it on the web.
This tutorial builds Shelf, a small site that lists books worth reading and lets a reader keep the ones they want. Each step adds one piece, and ends with what you should see.
What you will build
Shelf has a home page that lists books with a search box, a page for each book, a Your shelf page with the books the reader saved, a form to suggest a book, a theme with a dark mode, a test that clicks, and a deploy to GitHub Pages.
Along the way you use most of what a real site needs: typed data read at build time, a reusable component, a page per book, a store that keeps the reader's choices, a validated form, a theme, a test and a deploy. Each step links the chapter that covers its idea in depth.
It takes about half an hour, plus the deploy.
Before you start
You need:
wfinstalled and on yourPATH(Getting started). On Windows, typewebfluentwhere this tutorial typeswf.- Chrome or Chromium on the machine, for the test that clicks (step 9) and for
wf verify(step 10). If it is installed somewhere unusual, point theWF_CHROMEenvironment variable at it. - For the deploy, a GitHub account and a repository called
shelf.
You do not need to know WebFluent yet.
Step 1: Create the project
Start from the static template, which pre-renders every page to HTML — right for a site people find through search:
$ wf init shelf -t static
$ cd shelf
You write every file yourself, so delete what the template put in src/ and its tests under tests/ (they test the starter's pages). Then replace webfluent.app.json with:
{
"name": "shelf",
"build": { "ssg": true, "csp": true },
"meta": {
"title": "Shelf",
"description": "Books worth reading, and the ones you want to.",
"lang": "en"
}
}
ssg pre-renders each page. csp ships a Content-Security-Policy and makes the build check its own output against it. Configuration lists every key.
Check it: run wf check. It prints IO Error: No .wf files found in src/ — correct, because src/ is empty until the next step.
Step 2: Describe the books
The books are data, not code. Put them in src/books.json:
[
{ "slug": "notes-on-the-analytical-engine", "title": "Notes on the Analytical Engine",
"author": "Ada Lovelace", "year": 1843, "pages": 66,
"summary": "The first published algorithm, and a view of what a machine might do beyond arithmetic.",
"tags": ["computing", "history"] },
{ "slug": "the-design-of-everyday-things", "title": "The Design of Everyday Things",
"author": "Don Norman", "year": 1988, "pages": 368,
"summary": "Why doors confuse us, and what that says about everything else we make.",
"tags": ["design"] },
{ "slug": "a-pattern-language", "title": "A Pattern Language",
"author": "Christopher Alexander", "year": 1977, "pages": 1171,
"summary": "Two hundred and fifty-three patterns for towns, buildings and rooms people want to live in.",
"tags": ["design", "architecture"] }
]
Then describe the data's shape and read the file, in src/types.wf:
/// One book on the list.
type Book {
slug: String
title: String
author: String
year: Number
pages: Number
summary: String
tags: [String] = []
}
data books: [Book] = "books.json"
type Book is a record that the type checker holds every use to: writing book.titel is an error where you write it. data books reads the file at build time and makes it a constant every page can read, so nothing is fetched when the page loads. (Types, Fetching data.)
Check it: run wf check. It prints No problems in shelf.
Step 3: Keep the reader's shelf in a store
What the reader keeps must survive a reload and be the same on every page, so it goes in a store, with its value kept by persist. Create src/stores/Shelf.wf:
/// The books the reader wants to read, kept across visits.
store Shelf {
persist saved: [String] = []
derived count = saved.length
action toggle(slug: String) {
if saved.includes(slug) {
saved = saved.filter(s => s != slug)
} else {
saved = [...saved, slug]
}
}
}
persist is a state that is kept in the browser's storage and read back on the next visit; a change made in another tab arrives here too. derived count recomputes whenever saved changes. (Stores.)
Note
Coming from React? Shared state is not a context provider wrapped around the app, and saving it is not a useEffect that writes localStorage. A store is read by name wherever it is used, and persist does the saving. See Coming from React.
Check it: run wf check. It prints two U04 warnings: ` Shelf.count is declared but never read and the same for Shelf.toggle`. Nothing uses the store yet; the next steps do, and the warnings go away.
Step 4: Show a book with a component
Every book is shown the same way, so it is a component. Create src/components/BookCard.wf:
// … reads what the other steps declare
/// A book at a glance, with the button that puts it on the shelf.
component BookCard(_ book: Book) {
use Shelf
Card.outlined {
Stack(gap: .sm) {
Link(book.title, to: "/books/{book.slug}")
Text("{book.author} · {book.year}").muted.sm
Text(book.summary)
Row(gap: .xs) {
for tag in book.tags { Tag(tag) }
}
Button(if Shelf.saved.includes(book.slug) { "On your shelf" } else { "Want to read" }).sm {
on click { Shelf.toggle(book.slug) }
}
}
}
}
_ book: Bookis the one prop a caller may pass without its name:BookCard(book).Card.outlined,Stack(gap: .sm)andText(…).muted.smare built-ins with flags. The compiler knows each one's props and refuses a flag it does not take.use Shelfreads the store from step 3. The button's label is anifused as a value, and it follows the store: when the reader clicks, the label changes and nothing else re-renders.
(Components, Elements.)
Check it: run wf check. It reports two warnings and no error: ` warning[U03]: BookCard is declared but never placed and warning[U04]: Shelf.count is declared but never read . Nothing places the card yet, and nothing shows the count; the next step does both. The card also links to /books/…`, a page that does not exist yet. The compiler checks every link against the pages you declare, but only in what the site draws, so it says nothing until the card is placed.
Step 5: Add the home page and a page per book
The home page lists the books with a search box. Create src/pages/Home.wf:
// … reads what the other steps declare
page Home(path: "/", title: "Shelf", description: "Books worth reading, and the ones you want to.") {
state q = ""
derived needle = q.trim().toLowerCase()
derived found = books.filter(b => b.title.toLowerCase().includes(needle) || b.author.toLowerCase().includes(needle))
Container {
Stack(gap: .lg) {
Heading("Books worth reading").h1
Input(bind: q, label: "Search by title or author").search
Text("{found.length} of {books.length} books").muted.sm
Grid(columns: { base: 1, md: 2 }, gap: .md) {
for book in found by book.slug { BookCard(book) }
}
if found.length == 0 { Text("Nothing matches “{q}”.").muted }
}
}
}
bind: qkeeps the input and the state in step, both ways.foundis derived fromq, so typing narrows the list as you go.for … by book.slugis a keyed loop: a card that stays in the list keeps its element instead of being rebuilt.Grid(columns: { base: 1, md: 2 })is one column on a phone and two from themdbreakpoint. The pre-rendered HTML already has this layout, so no script is needed.
Note
Coming from React? A controlled input needs no value and no onChange that copies e.target.value back: bind: q does both. See Coming from React.
Then add a page for each book, src/pages/BookPage.wf:
// … reads what the other steps declare
page BookPage(path: "/books/:slug", slug: String, title: "Book", description: "One book on the shelf.", type: "article", paths: books.map(b => b.slug)) {
derived book = books.find(b => b.slug == slug)
head {
meta(property: "og:title", content: book?.title ?? "Book")
}
Container {
if let b = book {
Breadcrumb {
Breadcrumb.Item(to: "/") { Text("Books") }
Breadcrumb.Item { Text(b.title) }
}
Heading(b.title).h1
Text("{b.author}, {b.year} · {b.pages} pages").muted
Paragraph(b.summary)
} else {
Heading("No such book").h1
Link("Back to the list", to: "/")
}
}
}
:slugin the path is a typed parameter of the page.paths:tells the static build which values to render: one HTML file per book,books/a-pattern-language/index.htmland so on.books.find(…)may find nothing, sobookis aBook?(aBookornull).if let b = bookbinds it only when it is there. Readingbook.titlewithout that check is a compile error (T04).head { … }adds tags to this page's<head>— here, the title that a shared link previews with.
Check it: run wf serve and open http://localhost:3000. You see Books worth reading, 3 of 3 books and three cards. Type norman in the search box: one card stays, and the count reads 1 of 3 books. Click Want to read on a card and its label changes to On your shelf. Click a book's title and its page opens, with a breadcrumb back to the list. wf check now reports only the U04 warning about Shelf.count; step 6 uses it.
Step 6: Add the shelf page and the site's shell
The shelf page shows the books the reader saved. Create src/pages/ShelfPage.wf:
// … reads what the other steps declare
page ShelfPage(path: "/shelf", title: "Your shelf", description: "The books you want to read.") {
use Shelf
derived mine = books.filter(b => Shelf.saved.includes(b.slug))
Container {
Stack(gap: .lg) {
Heading("Your shelf").h1
if mine.length == 0 {
Text("Nothing yet. Pick something from the list.").muted
Link("Browse the books", to: "/")
} else {
for book in mine by book.slug { BookCard(book) }
}
}
}
}
Add a page for addresses no other page claims, src/pages/NotFound.wf. path: "*" matches anything, and the static build writes it as 404.html:
page NotFound(path: "*", title: "Not found", description: "Nothing lives at this address.", noindex: true) {
Container {
Heading("Nothing lives here").h1
Link("Back to the books", to: "/")
}
}
Last, the shell every page shares, src/App.wf. Router is where the current page is drawn:
// … reads what the other steps declare
app {
Navbar {
Navbar.Brand { Link("Shelf", to: "/") }
Navbar.Links {
Link("Books", to: "/")
Link("Your shelf ({Shelf.count})", to: "/shelf")
}
}
Router
Footer { Text("Built with WebFluent").muted.sm }
}
Check it: wf check prints No problems in shelf. Every page now has a navigation bar. Put two books on your shelf: the link reads Your shelf (2). Open it, then reload the page — the two books are still there. Open http://localhost:3000/nowhere and you see Nothing lives here.
Step 7: Add a form to suggest a book
Readers can suggest books. Create src/pages/Suggest.wf:
page Suggest(path: "/suggest", title: "Suggest a book", description: "Tell us what belongs on the shelf.") {
state title = ""
state author = ""
state why = ""
state sent = false
validate title { required "Which book?" }
validate author { required "Who wrote it?" }
validate why { maxLength(280) "Keep it under 280 characters" }
Container {
Stack(gap: .lg) {
Heading("Suggest a book").h1
if sent { Alert("Thank you — we will take a look.").success }
Form(bind: form) {
on submit {
sent = true
form.reset()
}
Input(bind: title, label: "Title")
Input(bind: author, label: "Author")
Textarea(bind: why, label: "Why it belongs here", rows: 4, maxLength: 280)
Button("Send the suggestion", type: .submit).primary
}
}
}
}
A validate block sits beside the state it guards, and the control bound to that state shows its messages accessibly: the field gets aria-invalid, and the message is announced. A submit that fails moves focus to the first field with a problem and does not run on submit. (Forms.)
Then link the page from the shell. Add the third link to src/App.wf:
// … reads what the other steps declare
app {
Navbar {
Navbar.Brand { Link("Shelf", to: "/") }
Navbar.Links {
Link("Books", to: "/")
Link("Your shelf ({Shelf.count})", to: "/shelf")
Link("Suggest a book", to: "/suggest")
}
}
Router
Footer { Text("Built with WebFluent").muted.sm }
}
Check it: click Suggest a book, then Send the suggestion with the form empty. The form does not send: Which book? appears under Title, and Who wrote it? under Author. Fill in both and send again. You see Thank you — we will take a look., and the form is empty.
A real site sends the suggestion somewhere. You do not need a backend for this tutorial, so this part is for later: describe the service once, in a file of its own,
// … in src/api.wf, beside the pages
api Suggestions(base: "/api") {
post suggest(body: Json) at "suggest" -> !
}
and call it from the form's handler:
// … in src/pages/Suggest.wf; the rest of the page is as above
on submit {
try await Suggestions.suggest(body: { title: title, author: author, why: why })
sent = true
form.reset()
}
try takes the call's value, or stops the handler on a failure and reports it, so sent turns true only when the suggestion arrived.
Step 8: Give the site a theme
A theme changes the design tokens that every built-in is drawn with. Create src/theme.wf:
theme Paper {
color-primary: #6D28D9
font-family: Charter, Georgia, serif
radius-md: 10px
}
theme Ink {
color-background: #111014
color-surface: #1A1820
color-text: #ECEAF2
color-text-muted: #A8A3B5
color-border: #2B2833
}
Then name the themes in webfluent.app.json — Paper as the theme and Ink as the dark one:
{
"name": "shelf",
"build": { "ssg": true, "csp": true },
"theme": { "name": "Paper", "dark": "Ink" },
"meta": {
"title": "Shelf",
"description": "Books worth reading, and the ones you want to.",
"lang": "en"
}
}
A reader whose system is set to dark mode gets Ink, before the first paint and with no flash of the light theme. A token you do not name keeps its baseline value. (Styling.)
Check it: the links and the Send the suggestion button are purple, and the text is a serif face. Switch your system to dark mode and the page turns dark. If the build stops with `No theme Paper is declared in this project, the config names a theme that src/theme.wf` does not declare: check the file name and the spelling.
Step 9: Test the book card
Tests live in tests/. Create tests/BookCard.wf:
// … reads what the other steps declare
test "a card shows who wrote the book, and when" {
BookCard(Book(slug: "x", title: "X", author: "Ada Lovelace", year: 1843, pages: 66, summary: "Notes."))
expect "Ada Lovelace · 1843"
expect "Want to read"
}
test "a book goes on the shelf, and comes off again" {
BookCard(Book(slug: "x", title: "X", author: "Ada Lovelace", year: 1843, pages: 66, summary: "Notes."))
click "Want to read"
expect "On your shelf"
click "On your shelf"
expect "Want to read"
}
Run them:
$ wf test
The first test renders the card and reads what it shows. It also writes a snapshot that the next run compares against. The second test clicks, so it runs in a headless Chrome, with the same compiler and runtime a reader gets. Buttons are found by their text, as a reader finds them. (Testing.)
Check it: the first run ends:
new tests/BookCard.wf — a card shows who wrote the book, and when (snapshot written)
ok tests/BookCard.wf — a book goes on the shelf, and comes off again (in a browser)
2 passed, 0 failed, 1 snapshot(s) written
Run wf test again and the first line reads ok: the render matches its snapshot.
If the second test says there is no browser, install Chrome or Chromium, or set WF_CHROME to its path.
Step 10: Build and verify the site
Stop the dev server, then build the site and load every page in a real browser:
$ wf build
$ wf verify
wf build writes build/, a folder of HTML, CSS and JavaScript that any static host can serve, and prints every warning, such as a missing alt, a page without a description, or a state nothing reads. wf verify loads every page in a real browser and fails on a script error, a failed request or a blank page.
Check it: wf build ends with Build complete., and build/ holds index.html, shelf/index.html, suggest/index.html, 404.html and one books/<slug>/index.html per book. wf verify lists six routes, each ok, and ends with 6 page(s), 0 problem(s).
Step 11: Deploy to GitHub Pages
Any static host serves build/. On GitHub Pages, a project site lives under https://<you>.github.io/shelf/, so tell the build its sub-path and its address. Add these keys to webfluent.app.json, keeping the others:
{
"build": { "ssg": true, "csp": true, "base_path": "/shelf" },
"meta": { "site_url": "https://you.github.io/shelf" }
}
base_path prefixes every link and asset. site_url turns on canonical links, the sitemap and absolute Open Graph URLs.
Then add a workflow that builds and publishes the site on every push to main, .github/workflows/pages.yml:
name: Deploy
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- run: curl -sSL https://raw.githubusercontent.com/monzeromer-lab/WebFluent/master/install.sh | bash
- run: ~/.webfluent/bin/wf build
- uses: actions/upload-pages-artifact@v3
with:
path: build
- id: deployment
uses: actions/deploy-pages@v4
Push the project to your shelf repository. In the repository's Settings → Pages, choose GitHub Actions as the source.
Check it: the Actions tab shows the Deploy workflow passing, and https://<you>.github.io/shelf/ shows Books worth reading. The recipes cover Netlify, Vercel, Cloudflare Pages, nginx and other hosts.
The whole program
Every .wf file above, as one listing. This is the program the steps built, with the first of the two tests:
type Book {
slug: String
title: String
author: String
year: Number
pages: Number
summary: String
tags: [String] = []
}
data books: [Book] = "books.json"
store Shelf {
persist saved: [String] = []
derived count = saved.length
action toggle(slug: String) {
if saved.includes(slug) {
saved = saved.filter(s => s != slug)
} else {
saved = [...saved, slug]
}
}
}
component BookCard(_ book: Book) {
use Shelf
Card.outlined {
Stack(gap: .sm) {
Link(book.title, to: "/books/{book.slug}")
Text("{book.author} · {book.year}").muted.sm
Text(book.summary)
Row(gap: .xs) {
for tag in book.tags { Tag(tag) }
}
Button(if Shelf.saved.includes(book.slug) { "On your shelf" } else { "Want to read" }).sm {
on click { Shelf.toggle(book.slug) }
}
}
}
}
app {
Navbar {
Navbar.Brand { Link("Shelf", to: "/") }
Navbar.Links {
Link("Books", to: "/")
Link("Your shelf ({Shelf.count})", to: "/shelf")
Link("Suggest a book", to: "/suggest")
}
}
Router
Footer { Text("Built with WebFluent").muted.sm }
}
page Home(path: "/", title: "Shelf", description: "Books worth reading, and the ones you want to.") {
state q = ""
derived needle = q.trim().toLowerCase()
derived found = books.filter(b => b.title.toLowerCase().includes(needle) || b.author.toLowerCase().includes(needle))
Container {
Stack(gap: .lg) {
Heading("Books worth reading").h1
Input(bind: q, label: "Search by title or author").search
Text("{found.length} of {books.length} books").muted.sm
Grid(columns: { base: 1, md: 2 }, gap: .md) {
for book in found by book.slug { BookCard(book) }
}
if found.length == 0 { Text("Nothing matches “{q}”.").muted }
}
}
}
page BookPage(path: "/books/:slug", slug: String, title: "Book", description: "One book on the shelf.", type: "article", paths: books.map(b => b.slug)) {
derived book = books.find(b => b.slug == slug)
head {
meta(property: "og:title", content: book?.title ?? "Book")
}
Container {
if let b = book {
Breadcrumb {
Breadcrumb.Item(to: "/") { Text("Books") }
Breadcrumb.Item { Text(b.title) }
}
Heading(b.title).h1
Text("{b.author}, {b.year} · {b.pages} pages").muted
Paragraph(b.summary)
} else {
Heading("No such book").h1
Link("Back to the list", to: "/")
}
}
}
page ShelfPage(path: "/shelf", title: "Your shelf", description: "The books you want to read.") {
use Shelf
derived mine = books.filter(b => Shelf.saved.includes(b.slug))
Container {
Stack(gap: .lg) {
Heading("Your shelf").h1
if mine.length == 0 {
Text("Nothing yet. Pick something from the list.").muted
Link("Browse the books", to: "/")
} else {
for book in mine by book.slug { BookCard(book) }
}
}
}
}
page Suggest(path: "/suggest", title: "Suggest a book", description: "Tell us what belongs on the shelf.") {
state title = ""
state author = ""
state why = ""
state sent = false
validate title { required "Which book?" }
validate author { required "Who wrote it?" }
validate why { maxLength(280) "Keep it under 280 characters" }
Container {
Stack(gap: .lg) {
Heading("Suggest a book").h1
if sent { Alert("Thank you — we will take a look.").success }
Form(bind: form) {
on submit {
sent = true
form.reset()
}
Input(bind: title, label: "Title")
Input(bind: author, label: "Author")
Textarea(bind: why, label: "Why it belongs here", rows: 4, maxLength: 280)
Button("Send the suggestion", type: .submit).primary
}
}
}
}
page NotFound(path: "*", title: "Not found", description: "Nothing lives at this address.", noindex: true) {
Container {
Heading("Nothing lives here").h1
Link("Back to the books", to: "/")
}
}
theme Paper {
color-primary: #6D28D9
font-family: Charter, Georgia, serif
radius-md: 10px
}
theme Ink {
color-background: #111014
color-surface: #1A1820
color-text: #ECEAF2
color-text-muted: #A8A3B5
color-border: #2B2833
}
test "a card shows who wrote the book, and when" {
BookCard(Book(slug: "x", title: "X", author: "Ada Lovelace", year: 1843, pages: 66, summary: "Notes."))
expect "Ada Lovelace · 1843"
expect "Want to read"
}
What you built
Shelf is a whole site, and each part of it uses one idea of the language:
| You wrote | The idea | Read more |
|---|---|---|
|
|
Typed data read at build time | |
|
|
Shared state kept across visits | |
|
|
A reusable component with a positional prop | |
|
|
Reactivity and keyed lists | |
|
|
Route parameters, static paths and optional values | |
|
|
The shell every page shares | |
|
|
Validated forms | |
|
|
Design tokens and dark mode | |
|
|
Tests that render and click | |
|
|
Building, checking and deploying |
To go further:
- Read the language properly, starting at Language basics.
- Talk to a real server: Data and APIs.
- Make the site work offline: Make a site work offline.
- Translate it: Translate a site.
- Build another app, step by step: Tutorial: a to-do list.
Common mistakes
Reading a value that may be missing. books.find(…) finds nothing when no book has the slug, so book is a Book?:
type Book { slug: String, title: String }
const books: [Book] = [Book(slug: "a-pattern-language", title: "A Pattern Language")]
page BookPage(path: "/books/:slug", slug: String, title: "Book", description: "One book.") {
derived book = books.find(b => b.slug == slug)
Heading(book.title).h1
}
Bind it with if let b = book { Heading(b.title).h1 }, as step 5 does, or read it as book?.title ?? "Book" (T04).
A field the type does not have. type Book names every field, so a typo is an error where it is written:
type Book { slug: String, title: String }
const books: [Book] = [Book(slug: "a-pattern-language", title: "A Pattern Language")]
page Home(path: "/", title: "Shelf", description: "Books worth reading.") {
Heading("Books").h1
for book in books by book.slug {
Text(book.titel)
}
}
Use the name the message suggests, book.title (T05).
A store member the store does not declare. Shelf has saved, count and toggle, and nothing else:
store Shelf {
persist saved: [String] = []
action toggle(slug: String) {
saved = if saved.includes(slug) { saved.filter(s => s != slug) } else { [...saved, slug] }
}
}
page Home(path: "/", title: "Shelf", description: "Books worth reading.") {
use Shelf
Heading("Books").h1
Text("{Shelf.total} saved")
Button("Keep it") { on click { Shelf.toggle("a-pattern-language") } }
}
Read a member the store declares, or declare the one you need: derived count = saved.length (T06).
Going further: if you know React, Vue or Svelte, Coming from React, Vue or Svelte maps what you know onto WebFluent.
What you learned
-
Read a JSON file at build time as typed data, with
typeanddata -
Keep what a reader chooses across visits in a
storewithpersist -
Write a component and place it in a keyed
for … by -
Render one page per item with a
:slugroute andpaths: -
Validate a form, add a theme, test with clicks and deploy