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:

wf

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 Cart in a page says the page reads the store. The page then reads members as Cart.items and Cart.count, and calls actions as Cart.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:

wf

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:

wf

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
Store scope
Scope Lives Use it for

.app (the default)

as long as the page is open the cart, the signed-in user

.session

as long as the tab; what it keeps goes in the tab's own storage, gone when the tab is state for one tab

.route

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:

wf

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.

wf

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:

wf

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)) } } }
Options
Option Meaning

in:

Where the value lives: .local (the default, kept across visits), .session (this tab), or .app (see Storage the project provides)

version:

The version of the value's shape that this build writes

sync:

false stops this page taking a value another tab or window wrote

key:

Keeps one stored value per key (see One stored value per instance)

migrate n -> m { … }

Brings a value written at version n forward to m

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 P01 warning: an older value would be discarded.
  • A step above the declared version is a P02 warning: 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:

wf

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:

wf

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) }.

  • get answers 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.
  • set receives 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: false turns 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:

js

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

wf

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:

wf

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:

wf

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:

Looking at one while it runs
Call What it does

WF.storeSnapshot()

Returns what every built store holds

WF.storeSnapshot("Cart")

Returns what one store holds

WF.restoreStore("Cart", values)

Puts a store back to values

WF.watchStores(fn)

Calls fn for every action, and returns the function that stops it

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:

wf

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:

When to use a store
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

store X(scope: .route)

read by one page and its components

the page's state, passed down as props

read by one component

the component's own state

Quick reference

Quick reference
Syntax Meaning

store Name { … }

Declare a store, built on first read

store Name(scope: .route)

How long it lives: .app (the default), .session or .route

store Name(eager: true)

Build it at boot

use Name

Say a page or component reads it

Name.member · Name.action(…)

Read a member, call an action

Name.action.pending

true while an async action runs

persist x = v

Keep a member across visits

persist x = v { in: …, version: n, sync: false, key: k }

Where and how it is kept

migrate n -> m { … old … }

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:

wf · draws T06

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:

wf · draws X05

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:

wf · draws X01

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