Stores
A store is lib/state/<name>.js written like a component script: top-level let is state, functions are actions and derived values. Every page and component reaches it as shared.<name>, and it can persist to localStorage.
One store, two components
p-shelf and p-basket never talk to each other: both read and change shared.cart.
lib/state/cart.js
const money = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })let lines = []const count = () => lines.reduce((sum, line) => sum + line.quantity, 0)const total = () => lines.reduce((sum, line) => sum + line.quantity * line.price, 0)const totalLabel = () => money.format(total())const empty = () => lines.length === 0function add(product) { const line = lines.find(entry => entry.id === product.id) if (line) line.quantity += 1 else lines.push({ id: product.id, name: product.name, price: product.price, quantity: 1 })}function remove(line) { lines = lines.filter(entry => entry.id !== line.id)}function clear() { lines = []}
routes/examples/stores/_snippets/cart/usage.html
<div class="grid w-full gap-4"> <p-shelf></p-shelf> <p-basket></p-basket></div>
routes/examples/stores/_components/shelf/shelf.html
<script> const products = [ { id: 'mug', name: 'Mug', price: 14 }, { id: 'tee', name: 'T-shirt', price: 28 }, { id: 'cap', name: 'Cap', price: 22 }, ]</script><section aria-label="Shelf"> <header class="store-panel-head"> <span class="font-mono text-xs text-faint">p-shelf</span> <span class="font-mono text-xs text-muted">in cart: <span class="text-accent tabular-nums">{shared.cart.count}</span></span> </header> <ul class="grid"> <for product in $products key=product.id> <li class="store-row"> <span class="text-sm">{product.name}</span> <span class="flex items-center gap-3"> <span class="font-mono text-xs text-faint tabular-nums">${product.price}</span> <button type="button" class="btn btn-small" aria-label="Add {product.name}" @click="shared.cart.add(product)">Add</button> </span> </li> </for> </ul></section><style> [data-c="shelf"] { width: 100%; border: 1px solid var(--color-line); background: var(--color-surface); } .store-panel-head { display: flex; align-items: center; justify-content: space-between; gap: 1rem; min-height: 2.75rem; padding: 0 0.75rem; border-bottom: 1px solid var(--color-line); } .store-row { display: flex; align-items: center; justify-content: space-between; gap: 1rem; min-height: 3rem; padding: 0.375rem 0.75rem; } .store-row + .store-row { border-top: 1px solid var(--color-line); }</style>
routes/examples/stores/_components/basket/basket.html
<section aria-label="Cart"> <header class="store-panel-head"> <span class="font-mono text-xs text-faint">p-basket</span> <button type="button" class="font-mono text-xs text-muted underline hover:text-accent" @click="shared.cart.clear()" :disabled="shared.cart.empty">Clear</button> </header> <ul class="grid"> <for line in shared.cart.lines key=line.id> <li class="store-row"> <span class="text-sm">{line.name} <span class="font-mono text-xs text-faint">× {line.quantity}</span></span> <button type="button" class="font-mono text-xs text-muted hover:text-accent" aria-label="Remove {line.name}" @click="shared.cart.remove(line)">Remove</button> </li> </for> <empty> <li class="store-row text-sm text-faint">Nothing yet. Add from the shelf.</li> </empty> </ul> <p class="store-row font-mono text-sm"><span class="text-faint">total</span><span class="tabular-nums">{shared.cart.totalLabel}</span></p></section><style> [data-c="basket"] { width: 100%; border: 1px solid var(--color-line); background: var(--color-surface); } .store-panel-head { display: flex; align-items: center; justify-content: space-between; gap: 1rem; min-height: 2.75rem; padding: 0 0.75rem; border-bottom: 1px solid var(--color-line); } .store-row { display: flex; align-items: center; justify-content: space-between; gap: 1rem; min-height: 3rem; padding: 0.375rem 0.75rem; } .store-row + .store-row { border-top: 1px solid var(--color-line); } button:disabled { opacity: 0.4; cursor: default; }</style>
Live result
- Mug $14
- T-shirt $28
- Cap $22
- Nothing yet. Add from the shelf.
total
lib/state/cart.js has no imports and no exports: let lines is the state, count and totalLabel are derived, add and remove change it. HTML reads it as {shared.cart.count} and <for line in shared.cart.lines>, and calls its functions straight from an event: @click="shared.cart.add(product)", with no wrapper in the component, so p-basket has no script at all. A script imports shared from 'pragma' and calls shared.cart.add(product). Importing the store file itself fails check with js/store-import.
Without persist a store lives in memory: it survives client navigation between pages (try another section and come back) but not a reload. Any page or component can read it, including _layout.html, which has no script of its own.
persist: drafts that survive reloads, synced across pages
export const persist = ['draft', 'pinned'] keeps those two lets in localStorage['pragma:scratchpad'].
lib/state/scratchpad.js
let draft = ''let pinned = falseexport const persist = ['draft', 'pinned']const pinText = () => pinned ? 'Unpin' : 'Pin'function togglePin() { pinned = !pinned}function wipe() { draft = ''}
routes/examples/stores/_components/draft-pad/draft-pad.html
<section aria-label="Scratchpad on this page"> <header class="store-panel-head"> <span class="label">this page</span> <span class="font-mono text-xs text-accent" :show="shared.scratchpad.pinned">pinned</span> </header> <div class="grid gap-3 p-3"> <textarea class="store-textarea" rows="4" maxlength="280" aria-label="Draft" placeholder="Type here, then reload the page" :model="shared.scratchpad.draft"></textarea> <div class="flex items-center justify-between gap-3"> <span class="font-mono text-xs text-faint tabular-nums">{shared.scratchpad.draft.length} / 280</span> <span class="flex gap-2"> <button type="button" class="btn btn-small" @click="shared.scratchpad.togglePin()">{shared.scratchpad.pinText}</button> <button type="button" class="btn btn-small" @click="shared.scratchpad.wipe()">Wipe</button> </span> </div> </div></section><style> [data-c="draft-pad"] { width: 100%; border: 1px solid var(--color-line); background: var(--color-surface); } .store-panel-head { display: flex; align-items: center; justify-content: space-between; gap: 1rem; min-height: 2.75rem; padding: 0 0.75rem; border-bottom: 1px solid var(--color-line); } .store-textarea { width: 100%; padding: 0.625rem 0.75rem; border: 1px solid var(--color-line-strong); background: var(--color-sunken); color: var(--color-ink); font-size: 0.9375rem; line-height: 1.5; resize: vertical; caret-color: var(--color-accent); } .store-textarea::placeholder { color: var(--color-faint); } .store-textarea:focus-visible { outline-offset: 0; border-color: var(--color-accent); }</style>
routes/examples/stores/demo/scratchpad.html
<title>Scratchpad, second page · pragma examples</title><meta name="robots" content="noindex"><c-demo-page> <p class="flex items-center justify-between gap-3 font-mono text-xs text-faint"> <span>Second page, same store</span> <span class="text-accent" :show="shared.scratchpad.pinned">pinned</span> </p> <textarea class="w-full border border-line-strong bg-sunken px-3 py-2.5 text-base" rows="4" maxlength="280" aria-label="Draft on the second page" :model="shared.scratchpad.draft"></textarea> <p class="font-mono text-xs text-faint tabular-nums">{shared.scratchpad.draft.length} / 280</p></c-demo-page>
Live result
The store restores the listed values when its module loads and writes them back after each render. It also listens to the storage event, so every other tab of the same origin follows live: type in either textarea, then reload the page. Persist preferences, drafts and local-only data, never anything the server owns. persist is the only export a store may have.
A store read only from a script
A derived function can read a store, and it runs again on every render.
routes/examples/stores/_components/shipping/shipping.html
<script> import { shared } from 'pragma' const freeShippingFrom = 50 const remaining = () => Math.max(freeShippingFrom - shared.cart.total(), 0) const qualifies = () => remaining() === 0 const message = () => qualifies() ? 'Free shipping unlocked.' : `Add $${remaining()} more for free shipping.`</script><p .is-free="$qualifies" role="status">{$message}</p><style> [data-c="shipping"] { padding: 0.75rem 1rem; border: 1px dashed var(--color-line-strong); color: var(--color-muted); font-family: var(--font-mono); font-size: 0.75rem; } .is-free { border-style: solid; border-color: var(--color-accent); color: var(--color-accent); }</style>
Live result
p-shipping never mentions the cart in its HTML: remaining() calls shared.cart.total() and the HTML shows {$message}. In a script, a store's derived values are functions you call; in HTML they are paths. The build ships a store to every page that reaches it, from HTML or from a script, and a shared.x with no lib/state/x.js fails check.