WebFluent is a language for websites. A file describes what a page shows — its elements, the state behind them, what happens when the reader acts — and the compiler turns it into a static site, a single-page app, a PDF or a slide deck, with the accessibility, search and performance work done for you.
This guide is the documentation: it takes you from installing wf to a
deployed application, and it is the reference once you are there. The same
chapters are published at
webfluent.monzeromer.dev.
Every wf code block in it is parsed, type-checked and compiled by the test
suite, so what you read is what the compiler accepts.
- New to WebFluent: Introduction, then Getting started and the tutorial.
- Coming from a framework: Coming from React, Vue or Svelte.
- Looking something up: the Reference part — components, CLI, configuration, diagnostics.
- Something is wrong: Troubleshooting.
| # | Chapter | What it covers |
|---|---|---|
| Get started | ||
| 1 | Introduction | What WebFluent is, what it does for you, where it fits and where it does not, and how to find your way around this guide. |
| 2 | Getting started | Install the compiler, make a project, run it, change it and see the change — then set up your editor, or WebFluent Studio, and see what a build writes. |
| 3 | Tutorial: Shelf | Build a small, complete site — data, components, a store, a form, a theme, a test — and put it on the web. |
| 4 | Coming from React, Vue or Svelte | What you already know, mapped to what is here — and the few places WebFluent works differently. |
| Tutorials and recipes | ||
| 5 | Tutorial: Todos | Build a todo list kept in the reader's browser — types, a store that remembers, a component, a filter in the address and tests that click. |
| 6 | Tutorial: Field Notes | Build a statically generated notebook: typed data files, a page per note, Markdown pages, search and tags, and what a pre-rendered page can know. |
| 7 | Tutorial: Pocket | Build a budget tracker: money and dates, derived totals, a storage migration, validated forms, a dialog and shortcuts, two languages and offline. |
| 8 | Recipes | Small, complete pages for the jobs most projects meet: debounced search, paging, optimistic updates, a confirm dialog, dark mode and more. |
| Concepts | ||
| 9 | Language basics | The shape of every .wf file: the thirteen kinds of declaration, naming, comments, the two kinds of body, the two layouts and how strings are written. |
| 10 | Pages and routing | A page is a route and what it shows. Each page names its own path, the app shell frames every page, and a layout frames a section. |
| 11 | Elements | Everything on screen is an element, and every element is written the same way: a name, one positional value, named props, flags and a block. |
| 12 | State and reactivity | A state is a signal, and only what reads it updates: no tree re-renders, no subscriptions to manage. |
| 13 | Events | Handlers on elements, keyboard shortcuts, the events components fire, the overlays a page opens, and drag and drop. |
| 14 | Control flow | Five statements decide what a page shows: if, if let, for, show and match. Each adds and removes elements as its condition changes. |
| 15 | Components | A component is a reusable element you declare: typed props, events, slots, parts and a body, checked like a built-in. |
| 16 | Stores | A store is state shared by every page and component that uses it, built the first time something reads it. |
| 17 | Types | A gradual, structural type checker that changes no output and names every mistake where you wrote it. |
| 18 | Expressions | The expression language: literals, interpolation, operators, values that choose, calls, methods, formatting, regexes, tokens and await. |
| Guides: interface | ||
| 19 | Styling | Restyle the whole site with a theme, one element with a style block, and many elements with your own stylesheet — and make the layout responsive. |
| 20 | Motion | Declare how an element enters and leaves, how a list staggers and how pages change — the runtime plays it, or skips it for readers who asked for less. |
| 21 | Media | Add pictures the build resizes for every screen, video with captions, audio with a transcript, icons, carousels and frames. |
| 22 | Accessibility | Build pages that work with a keyboard, a screen reader or voice control: what the built-ins do, what the compiler checks, and what is still yours to do. |
| Guides: data | ||
| 23 | Forms and validation | Bind controls to state, validate what the reader types, upload files, and show what the server said. |
| 24 | Fetching data | Get data onto a page: describe a service once, show a request's states, fetch on demand, and read files at build time. |
| 25 | Real-time | Hold a connection open — a socket, server-sent events, a channel every tab hears, a line to another reader's page, a worker — and read the network itself. |
| 26 | Offline | Turn on a service worker the build writes for you: the site works with no network, writes wait for the connection, and new versions are offered, not forced. |
| Guides: content | ||
| 27 | Content | Markdown, pages written as .md files, code on the page, and what the build writes for search engines and link previews. |
| 28 | Internationalisation | Keep one JSON file per locale, read it with t(), and switch the whole site's language — and its direction — at once. |
| Guides: quality | ||
| 29 | Testing | Tests written in WebFluent: render a component and read what it shows, or click through it in a real browser — then check every page in one. |
| 30 | Security | What the compiler guarantees, what it cannot, and the decisions left to you: markup, secrets, storage, headers and a deployment checklist. |
| 31 | Performance | Learn what a build already does to be fast, see what it weighs, set budgets that warn, time pages in a browser, and avoid what makes a site slow. |
| Guides: shipping | ||
| 32 | Project structure | Where files go, how the compiler reads them, how names work across a project, and how a project grows without getting lost. |
| 33 | Static or single-page | The same source builds as pre-rendered pages or as one app shell. What each gives you, what the pre-rendered page holds, and how dynamic routes are rendered. |
| 34 | Deploying | The build is a folder of static files. Put it on GitHub Pages, Netlify, Vercel, Cloudflare Pages, a server of your own, or a container. |
| 35 | Environments | Set values that change per build (an API address, a feature switch, a public key) from the config, a .env file or the shell, and choose which a page may read. |
| 36 | Desktop apps | Turn a WebFluent project into a Tauri or Electron desktop app, call the native side from a page, and package it. |
| Other outputs | ||
| 37 | PDF and slides | Compile the same language to a paginated PDF document or a slide deck — invoices, reports and talks, laid out with CSS as on the web. |
| 38 | Server rendering | Render a .wf template with JSON on a server — an email, an invoice, a report, an HTML fragment — from the CLI, Rust or Node. |
| 39 | JavaScript interop | Write plain JavaScript beside your pages and call it by name; load a library from a CDN; hand an element to a script; place custom elements; publish your components. |
| Reference | ||
| 40 | Components reference | Every built-in with its props, cases, flags, events, slots and parts — generated from the compiler's own registry. |
| 41 | Command line and editors | Every wf command and flag, the dev server, and the language server in each editor. |
| 42 | Configuration | Every key of webfluent.app.json, its default, and what it changes. |
| 43 | Diagnostics | Every error and warning the compiler reports — what it means, a program that draws it, the message, and the fix. |
| 44 | Built-ins | Every function, browser value, method and global the language gives a program, in one place. |
| 45 | Design tokens | Every token of the baseline theme, with its value: the colours, type, spacing, radii, shadows, motion and breakpoints every built-in is drawn with. |
| 46 | Runtime API | window.WF — the runtime every compiled page calls, usable from a script of your own, the console or a library's callback. |
| 47 | Grammar | Every keyword and where it may appear, the shapes of declarations, statements and expressions, operators and precedence, and the literals. |
| 48 | Browser support | Which browsers a WebFluent site targets, and what each newer platform feature falls back to where a browser lacks it. |
| 49 | Glossary | The words this guide uses, each in a sentence, with where to read more. |
| Help | ||
| 50 | Troubleshooting | The problems people meet, what causes each, and the fix — from installing to deploying, plus the questions that come up most. |
| 51 | Upgrading | What changed in each release, what to do when you upgrade, and how wf migrate carries an older project forward. |
| 52 | Contributing | How the compiler is put together, how to build and test it, and how to change the language, a built-in or this guide. |