Tutorial
The language
Stores
A store is state shared by every page and component that uses it, built the first time something reads it.
This chapter covers stores. A store holds state that more than one page or component shares: the cart, the signed-in user, the theme, a cache of what was fetched. It holds state, derived values and actions, and every page that reads it sees the same values.
The one thing to remember: a store is built the first time something reads it. Declaring a store does nothing. The first Cart.items, Cart.count or Cart.add(…) builds it, and every later read uses that same instance. As a result, the order you declare stores in does not matter — a derived value may read a store declared below it — and a store nothing reads costs nothing, in time or in bytes.
In this chapter
- Declaring a store and reading it from pages
- How long a store lives: its scope
- Actions, including async actions
- Keeping a value across visits with
persist, and changing its shape later - Connections and data a store owns
- Inspecting and testing a store
- When to use a store, and when a page's own state
A first store
This program declares a Cart store and reads it from two pages:
type Item { id: String, name: String, price: Number, qty: Number = 1 }
store Cart {
state items: [Item] = []
derived count = items.length
derived total = items.reduce((sum, i) => sum + i.price * i.qty, 0)
action add(item: Item) { items.push(item) }
action remove(id: String) { items = items.filter(i => i.id != id) }
}
page Shop(path: "/", title: "Shop", description: "Things to buy.") {
use Cart
Heading("Shop").h1
Button("Add a pen").primary { on click { Cart.add(Item(id: "pen", name: "Pen", price: 2.5)) } }
Text("Cart: {Cart.count}, {format(Cart.total, .currency)}")
}
page CartPage(path: "/cart", title: "Cart", description: "What you are buying.") {
use Cart
Heading("Cart").h1
for item in Cart.items by item.id {
Row(justify: .between) {
Text("{item.name} × {item.qty}")
Button("Remove").sm { on click { Cart.remove(item.id) } }
}
}
if Cart.count == 0 { Text("Your cart is empty.").muted }
}
Clicking Add a pen changes Cart: 0, $0.00 to Cart: 1, $2.50, and the /cart page lists the pen.
store Cart { … }declares the store and its members.use Cartin a page says the page reads the store. The page then reads members asCart.itemsandCart.count, and calls actions asCart.add(…).- Everything that reads
Cart.count, on any page, updates when it changes.
The checker knows every member and its type. Cart.cont is an error (T06, with the nearest member it does have), and Cart.add("pen") is an error because add takes an Item (T01).
Note
Coming from React? There is no context provider to wrap the tree in, and no selector to write. Declare the store once and read Cart.count anywhere; only what reads count updates when it changes. See Coming from React.
Store members
A store holds the same members a page does: state, persist, derived values and actions. This fuller Cart adds a coupon kept across visits and an action that raises the quantity of an item already in the cart:
type Item { id: String, name: String, price: Number, qty: Number = 1 }
store Cart {
state items: [Item] = []
persist coupon = ""
derived count = items.reduce((n, i) => n + i.qty, 0)
derived subtotal = items.reduce((sum, i) => sum + i.price * i.qty, 0)
derived discount = if coupon == "SAVE10" { subtotal * 0.1 } else { 0 }
derived total = subtotal - discount
action add(item: Item) {
if items.some(i => i.id == item.id) {
items = items.map(i => if i.id == item.id { { ...i, qty: i.qty + 1 } } else { i })
} else {
items.push(item)
}
}
action remove(id: String) { items = items.filter(i => i.id != id) }
action clear() { items = [] }
}
add changes items itself: it assigns a new list with that one item's quantity raised. Writing let found = items.find(…) and then found.qty = found.qty + 1 would change only the local copy that let made (chapter 7), and the cart would stay as it was.
Inside the store you read its members by their bare names: items, count. Outside it, a page or component reads them through the store's name: Cart.items, Cart.count.
Note
Coming from Vue or Svelte? use Cart is not Pinia's useCartStore() and makes no copy; there is no $cart prefix either. Every reader gets the one instance, by the store's name. See Coming from Vue and Coming from Svelte.
You may declare a store in any .wf file the build reads. By convention it goes in src/stores/, and wf generate store Cart writes it there. A page reaches a store by name from anywhere. use says which stores a page reads, for the person reading the code and for the editor; it does not limit what the page can reach, and a page that reads Cart.count without it reads the same store.
Store scope
A store's scope says how long it lives. You set it in the declaration; these three stores live for the page, the tab and the route:
store Cart(scope: .app) { state items: [String] = [] } // the default: as long as the page is open
store Session(scope: .session) { state step = 1 } // this tab's
store Filters(scope: .route) { state search = "" } // this route's
| Scope | Lives | Use it for |
|---|---|---|
|
|
as long as the page is open | the cart, the signed-in user |
|
|
as long as the tab; what it keeps goes in the tab's own storage, gone when the tab is | state for one tab |
|
|
until the route changes | the filters on a list, a wizard's step |
When the route changes, a .route store drops what it holds. The next read builds it again from its initial values.
store X(eager: true) builds the store at boot instead of on first read. Use it for the rare store whose set-up must run whether or not a page reads it. If a derived value of yours has a side effect that used to run when the page loaded, eager: true keeps it running then.
Actions
A store's actions are its interface: pages change the store by calling them. An action may be asynchronous — it uses await — and an async action exposes pending, which is true while a call of it runs:
type Account { name: String }
type SignedIn { user: Account }
type SignIn { email: String, password: String }
store Session {
state user: Account? = null
state error = ""
derived loggedIn = user != null
action login(email: String, password: String) {
error = ""
let answer: SignedIn! = await http.post("/api/login", body: SignIn(email: email, password: password))
match answer {
.ok(r) { user = r.user }
.err(e) { error = "Could not sign in: {e.message}" }
}
}
action logout() {
user = null
navigate("/")
}
}
page Login(path: "/login", title: "Sign in", description: "Sign in.") {
use Session
state email = ""
state password = ""
Heading("Sign in").h1
Form {
on submit { Session.login(email, password) }
Input(bind: email, label: "Email").email.required
Input(bind: password, label: "Password").password.required
Button("Sign in", type: .submit, disabled: Session.login.pending).primary
}
if Session.error != "" { Alert(Session.error).danger }
}
The Sign in button is disabled while Session.login runs.
Inside an action, a bare name is the store's own member — items, error — unless something nearer declares it. A let, a parameter, a for binding, a lambda's parameter or a caught error belongs to the action until its block ends. So let items = … in an action reads and writes that local variable and leaves the store's items alone.
An action may read other stores through their names. Stores are global, so a store needs no use. A derived value may call one of the store's own actions to compute a value, but not one that assigns state: that is X04, because the derived value would change state every time it is read.
Keeping a value across visits
persist declares a member whose value is kept in the browser's storage and read back on the next visit. It is stored under the store's name and the member's name, so a page and a store may each persist a theme. persist works the same way at the top of a page or a component.
store Prefs {
persist scheme = "system"
persist density = "comfortable"
persist recent: [String] = []
action visited(path: String) {
recent = [path, ...recent.filter(p => p != path)].take(5)
}
}
By default the value goes in localStorage, and a write in another tab of the same site arrives in this one. localStorage is shared between tabs, and two tabs that disagree about the theme would be a bug.
Options
A block after the declaration changes where and how the value is kept:
type Item { id: String, qty: Number = 1 }
store Cart {
persist items: [Item] = [] {
in: .local // .local (default, across visits) · .session (this tab) · .app (the project's own)
version: 2 // the version of the shape this build writes
sync: false // don't take what another tab wrote
migrate 1 -> 2 { old.map(i => Item(id: i.id, qty: i.count)) }
}
}
| Option | Meaning |
|---|---|
|
|
Where the value lives: |
|
|
The version of the value's shape that this build writes |
|
|
|
|
|
Keeps one stored value per key (see One stored value per instance) |
|
|
Brings a value written at version |
Versions and migrations
A version is a promise to returning readers. Once you declare a shape with version:, the page brings a value written by an older build forward one step at a time. Each migrate n -> n+1 step reads the old value as old and returns the new one. A reader who last visited two deploys ago keeps their cart instead of finding it empty.
The build checks the chain:
- A gap in the chain is a
P01warning: an older value would be discarded. - A step above the declared version is a
P02warning: it never runs. - A value written by a newer build is left alone, and the page uses the initial value. This build cannot know what a later shape means.
What storage hands back is held to the value's type as it is read — its declared type, or what a plain first value says it is. A value that does not fit (a record missing a field, text where a number is kept, something typed into the devtools) is not this value: the page uses the initial value instead, and a development build says so in the console. A reader's storage never stops a page from loading.
The build also remembers the shape of every persisted value, in .wf-cache/persist.json. When a shape changes and version: was not raised, it warns (D04): a returning reader's browser still holds the old shape, which the page would read as the new one.
Warning
A persist inside a store(scope: .route) does not reset with the route. The route change drops the store, and the next read builds it again — from storage, so the value comes straight back. The build reports this as P03. Use state for what the route owns, and a wider scope for what outlives it.
One stored value per instance
A persist in a component uses one stored value for every place the component is drawn. Three Panels that each persist open share one value, so opening one opens them all. key: names what tells the instances apart, and each key gets its own stored value:
component Panel(_ title: String) {
persist open = false { key: title }
Button(title) { on click { open = !open } }
if open { children }
}
The build warns (D03) about a component that persists a value with no key: and is placed more than once, or in a loop.
A key that follows state
key: is read as state. When what it reads changes, the member takes the value kept under the new key, and writes go there. A desktop app keeps its layout per project this way. A store's key may read the store itself, or another store:
store Layout {
state project = "halyard"
persist side = 240 {
key: project
in: .app
}
}
Storage the project provides
in: .app keeps the value somewhere other than the browser's two storages: a desktop app's store reached through its native bridge, or an extension's storage. It reads window.wfStorage.app, which a script of the project's under src/ defines. The object has this shape: { get(name), set(name, text), remove?(name), watch?(name, fn) }.
getanswers at once or with a promise, so an IPC call is fine. Until it answers, the value is its declared initial value. A write made before the answer is not undone by it, and an answer for a key that has since changed is ignored.setreceives the JSON text to keep.watch(name, fn), when present, hears another writer, such as another window, and returns a function that stops it.sync: falseturns it off.
If no window.wfStorage.app is defined, the value is kept in localStorage, and wf serve says so on the console.
This script connects .app to Tauri's IPC:
// src/app-store.js — Tauri's IPC, reached when a value is read or written
const call = (command, args) => window.__TAURI__.core.invoke(command, args);
window.wfStorage = {
app: {
get: (name) => call("store_get", { name }),
set: (name, text) => call("store_set", { name, text }),
},
};
See Make a desktop or phone app with Tauri for the rest of a desktop project.
Secrets are never persisted
persist token: Secret = "" is an error (T12). The point of the Secret type is that its value never reaches a place any script can read, and the browser's storage is such a place. Keep a session in an httpOnly cookie instead (see Security).
A connection a store holds
A store may hold a connection — a socket, a stream, a channel, a peer or a worker (see Open a socket) — for every page at once. The connection opens when the store is first read and closes with the store; a .route store's connection closes when its route leaves. The store's actions and handlers name the connection as it is declared, and a page reads it through the store:
type Line { text: String }
store Live {
state last = ""
socket feed = ws("wss://example.com/feed") {
send Line
receive Line
on message(m) { last = m.text }
}
action say(text: String) { feed.send(Line(text: text)) }
}
page Feed(path: "/", title: "Feed", description: "One line for every page.") {
Heading("Feed").h1
match Live.feed {
open { Text(Live.last) }
else { Text("Reconnecting…") }
}
Button("Wave") { on click { Live.say("hello") } }
}
Loading data into a store
A store can own a resource (see Data and APIs). It is asked for the first time something reads the store, and lives as long as the store does — not as long as the page that happened to read it first — so another page that reads the store finds what has already arrived, and nothing is asked for again. It is abandoned with the store: a .route store's when its route leaves, to be asked for afresh when the route comes back.
Inside the store it is rows, anywhere else Deploys.rows, and its value, isLoading, isRefreshing, error and pending follow it in both, and match Deploys.rows { .loading … .failed(e) … .loaded(rows) … } draws it. Its address and options read the store's own state, so an action that moves one asks again:
type Deploy { id: String, status: String }
store Deploys {
state page = 1
resource rows: [Deploy] = http.get("/api/deploys?page={page}")
derived failing = (rows.value ?? []).filter(d => d.status == "failed").length
action next() { page = page + 1 }
action refresh() { rows.reload() }
}
page DeploysPage(path: "/deploys", title: "Deploys", description: "Every deploy.") {
Heading("Deploys").h1
Text("{Deploys.failing} failing")
match Deploys.rows {
.loading { Spinner }
.failed(e) { Text(e.message) }
.loaded(rows) {
for d in rows by d.id { Text("{d.id}: {d.status}") }
}
}
Button("Refresh", disabled: Deploys.rows.pending) { on click { Deploys.refresh() } }
Button("Next page") { on click { Deploys.next() } }
}
A resource over a service's endpoint is owned the same way — resource list = Catalog.items() — and when the endpoint says how it pages (Load results a page at a time), Shelf.list.loadMore() asks for the next page from any page that reads it. The resource is the store's to replace: Deploys.rows = … is an X01, as it is inside the store.
When an action decides what is kept — a reply merged into rows already held, a list built from several calls — fill the store's state from a request instead, and call the action where the data is first wanted:
type Post { id: String, title: String }
type Page { items: [Post] }
store Feed {
state items: [Post] = []
action more() -> ! {
let next: Page = try await http.get("/api/feed?after={items.length}")
items = [...items, ...next.items]
}
}
Stores in the pre-rendered page
A static build pre-renders each page to HTML — the static paint. The static paint seeds each store's state from its initial values, so Cart.count is painted as 0, and a store seeded with rows paints the rows. A value an action changes at run time is corrected once the page is live.
Looking at one while it runs
wf serve puts a stores button in the corner of the page. It opens on what every store that has been built is holding, and a log of every action that has run: the arguments it was given, and the state before and after it. Clicking an entry puts the store back to what it held before that action, which is usually enough to find a bug.
The same tools are on window.WF, for a console or a script:
| Call | What it does |
|---|---|
|
|
Returns what every built store holds |
|
|
Returns what one store holds |
|
|
Puts a store back to |
|
|
Calls |
Nothing is recorded while nothing is watching, so a deployed site pays nothing for any of it. See Runtime API.
Testing a store
wf test renders a test with the project's stores at hand, and a test's data seeds a store by its name. This test seeds a cart with two of one item and reads what CartSummary shows:
type Item { id: String, qty: Number = 1 }
store Cart {
state items: [Item] = []
derived count = items.map(i => i.qty).sum()
}
component CartSummary {
use Cart
Text("{Cart.count} items")
}
test "the cart shows what is in it"(data: { Cart: { items: [{ id: "a", qty: 2 }] } }) {
CartSummary
expect "2 items"
}
In a project the store and the component live under src/ and the test under tests/.
A test that clicks a button runs the store's actions in a real browser. See Testing.
When to use a store
Put a value where the code that reads it can reach it, and no wider:
| The value is… | Keep it in |
|---|---|
| read by more than one page, or must outlive a navigation | a store |
| owned by one screen, and should go when the screen does |
|
| read by one page and its components |
the page's |
| read by one component |
the component's own |
Quick reference
| Syntax | Meaning |
|---|---|
|
|
Declare a store, built on first read |
|
|
How long it lives: |
|
|
Build it at boot |
|
|
Say a page or component reads it |
|
|
Read a member, call an action |
|
|
|
|
|
Keep a member across visits |
|
|
Where and how it is kept |
|
|
Bring an older stored value forward |
Quiz
Check your understanding
A program declares a Cart store, and nothing has read it yet. When is the store built?
Check your understanding
A page reads Cart.count but has no use Cart line. What happens?
Check your understanding
store Filters(scope: .route) { persist search = "" }. The reader types a search, leaves the route and comes back. What is search?
Common mistakes
A member the store does not have. A name guessed from what the store ought to hold, rather than read from what it declares:
store Cart {
state items: [String] = []
derived count = items.length
}
page P(path: "/", title: "T", description: "D") {
use Cart
Heading("Cart").h1
Text("{Cart.total} items")
}
Read a member the store declares, Cart.count, or declare the one you need. See T06.
use with the store's name misspelled. A store's name is capitalised, and use must name it exactly:
store Cart { state items: [String] = [] }
page P(path: "/", title: "T", description: "D") {
use cart
Heading("{Cart.items.length} in the cart").h1
}
Write use Cart. See X05.
Assigning a store's derived value. A derived value is worked out from the state it reads, so nothing may set it:
store Cart {
state items: [String] = []
derived count = items.length
}
page P(path: "/", title: "T", description: "D") {
use Cart
Heading("{Cart.count} items").h1
Button("Empty") { on click { Cart.count = 0 } }
}
Change the state it reads, through an action: action clear() { items = [] }, called as Cart.clear(). See X01.
What you learned
-
Declare a store and read it from any page as
Store.member -
Choose how long a store lives with
scope: -
Change a store through its actions, async ones included
-
Keep a value across visits with
persist, and migrate its shape -
Decide between a store and a page's own
state