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:

  • wf installed and on your PATH (Getting started). On Windows, type webfluent where this tutorial types wf.
  • 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 the WF_CHROME environment 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:

bash

$ 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:

json

{ "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:

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:

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:

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:

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: Book is the one prop a caller may pass without its name: BookCard(book).
  • Card.outlined, Stack(gap: .sm) and Text(…).muted.sm are built-ins with flags. The compiler knows each one's props and refuses a flag it does not take.
  • use Shelf reads the store from step 3. The button's label is an if used 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:

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: q keeps the input and the state in step, both ways.
  • found is derived from q, so typing narrows the list as you go.
  • for … by book.slug is 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 the md breakpoint. 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:

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: "/") } } }
  • :slug in 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.html and so on.
  • books.find(…) may find nothing, so book is a Book? (a Book or null). if let b = book binds it only when it is there. Reading book.title without that check is a compile error (T04).
  • head { … } adds tags to this page's <head> — here, the title that a shared link previews with.

(Pages and routing.)

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:

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:

wf

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:

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") } } 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:

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:

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,

wf

// … 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:

wf

// … 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.

(Data and APIs, Environments and secrets.)

Step 8: Give the site a theme

A theme changes the design tokens that every built-in is drawn with. Create src/theme.wf:

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:

json

{ "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:

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:

bash

$ 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:

text

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:

bash

$ 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:

json

{ "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:

yaml

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:

wf

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:

What you built
You wrote The idea Read more

type Book and data books

Typed data read at build time

store Shelf with persist

Shared state kept across visits

component BookCard

A reusable component with a positional prop

state, derived, bind: and for … by on the home page

Reactivity and keyed lists

path: "/books/:slug" with paths:, and if let

Route parameters, static paths and optional values

app { … Router … }

The shell every page shares

validate and Form(bind: form)

Validated forms

theme Paper and theme Ink

Design tokens and dark mode

test "…" { … click … expect … }

Tests that render and click

wf build, wf verify and a workflow

Building, checking and deploying

To go further:

Common mistakes

Reading a value that may be missing. books.find(…) finds nothing when no book has the slug, so book is a Book?:

wf · draws T04

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:

wf · draws T05

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:

wf · draws T06

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 type and data

  • Keep what a reader chooses across visits in a store with persist

  • Write a component and place it in a keyed for … by

  • Render one page per item with a :slug route and paths:

  • Validate a form, add a theme, test with clicks and deploy