Guide › Interactivity
On this page
Fetching data
A page's load() gives it data on the server. For data an island fetches itself in the browser (on demand, after a click, by polling, or data that changes after the page was built) use clarusjs/fetch.
This dashboard is three kinds of islands. The stat cards share one batch, so the three of them make one request. The user panel and the activity feed share the signed-in user. The feed waits for it, and the demo server fails its first request so you can see the retry. Reload the page to watch it again.
Visits
Loading visits…
Signups
Loading signups…
Revenue
Loading revenue…
Loading the user…
Waiting for the user, then loading the activity…
A resource #
resource() runs a fetcher and gives an island its answer: value, loading and error. They update the island's template on their own.
<script>
import { json, resource } from 'clarusjs/fetch'
const users = resource(({ signal }) => json('/api/users', { signal }))
</script>
@if (users.value) {
<ul>@for (u of users.value; track u.id) { <li>{{ u.name }}</li> }</ul>
} @else if (users.error) {
<p>Couldn't load the users. <button (click)="users.refetch()">Try again</button></p>
} @else {
<p>Loading…</p>
}Pass the signal on to fetch (as json() does). When a newer request starts, or the island goes away, the old one is cancelled.
Requests in parallel and in a chain #
Resources start together, in parallel. A resource whose fetcher reads another one's value waits for it. Until the value is there, the fetcher returns undefined (or null, or false), which means "not ready" and sends no request. When the value changes, the resource runs again, so a chain is just a fetcher reading a signal:
const team = resource(({ signal }) => json('/api/team', { signal }))
const members = resource(({ signal }) => team.value && json(`/api/teams/${team.value.id}/members`, { signal }))The same goes for any state: change a page number, and a resource that reads it fetches that page.
Fetchers can be async. Read the signals it depends on before its first await: those are the ones it follows. To wait, return nothing (return), which an async fetcher resolves to undefined, meaning "not ready". (For a chain, the team.value && … form above is smoother: an async fetcher shows loading for a moment even when it isn't ready.)
const members = resource(async ({ signal }) => {
const id = team.value?.id // read before awaiting: followed
if (id === undefined) return // not ready yet
const res = await fetch(`/api/teams/${id}/members`, { signal })
if (!res.ok) throw new Error(`members: ${res.status}`)
return res.json()
})One request for many islands #
When several islands ask the same endpoint for different keys, batch() sends the keys asked at the same moment (the islands attaching as the page loads) as one request. Share it from a module:
// src/stores/stats.ts
import { batch, json } from 'clarusjs/fetch'
export const stats = batch((keys, { signal }) => json(`/api/stats?keys=${keys.join(',')}`, { signal }))@input key: string
<script>
import { resource } from 'clarusjs/fetch'
import { stats } from '../stores/stats.ts'
const stat = resource(() => stats.get(key))
</script>
<p>{{ stat.value ?? '…' }}</p>The endpoint answers with one value per key ({ "visits": 12400, "signups": 318 }). A key missing from the answer fails that card only.
Retry and refetch #
const feed = resource(load, {
retry: 2, // two more attempts: after 500 ms, then 1 s
refetch: { interval: 30_000, focus: true }, // every 30 s while the page is visible, and when it's shown again
})refetch() runs it now, for a Refresh button or after you've saved something. In code that needs the data itself, await items.ready() waits for the first answer (in a handler or an async function; a script's top level can't await). mutate(value) shows a value right away (an optimistic update); the next run replaces it.
Caching #
Give a resource a key, and its answers are cached by it: a key seen before comes back without a request. This list has 20,000 records, 10 per page. Go forward and back: pages you've seen don't ask the server again, the next page is fetched ahead, and the previous page stays on screen while a new one loads. Rename the first row changes a record, then invalidates every cached page.
Loading…
Loading records…
<script>
import { invalidate, json, prefetch, resource } from 'clarusjs/fetch'
let page = state(1)
let q = state('')
const list = resource(({ signal }) => json(`/api/records?page=${page}&q=${encodeURIComponent(q)}`, { signal }), {
key: () => ['records', { page: page, q: q }], // one cache entry per page and filter
})
async function rename(id, name) {
await fetch(`/api/records/${id}`, { method: 'PATCH', body: JSON.stringify({ name }) })
invalidate(['records']) // every cached page: the visible one refetches now
}
</script>- Fresh until invalidated. A cached answer is used until
invalidate()matches its key. For data other people change often, addstale: 30_000: an answer older than that is fetched again when used. - The key is the cache's name for the request. Put in it everything the request depends on (the page, the filter), and keep it to plain values:
{ page, q }and{ q, page }are the same key. - Shared. Resources with the same key, in any island on the page, share one entry and one request.
invalidate(prefix)matches keys element by element:invalidate(['records'])matches['records', { page: 2 }], not['recordsArchive'].setData(key, fn)changes a cached answer right away (an optimistic edit);prefetch(key, fetcher)fetches one ahead.- Memory. An answer nothing shows is dropped after 5 minutes (
keep). The cache lives in the page: it survives fragment navigation, not a full reload.
On the server #
Nothing is fetched while the server renders the page. A resource there is in its loading state, so the HTML shows your loading text and the browser fills it in. If the page's load() already has the data, pass it as initial: the server HTML shows it, and the browser fetches again to bring it up to date.
const stats = resource(load, { initial: props.stats })To skip that first browser fetch, set refetch: { onStart: false }. The resource then waits for a refetch(), its interval or a refocus, and until one of them runs it doesn't follow the signals its fetcher reads.
What it doesn't do #
- Keep answers across full page loads: the cache (with
key) lives in the page; a reload starts it empty. - Merge different endpoints into one request: write a server route that combines them, and batch that.
- Mutations: send them with
fetch(or a form, see Form validation), thenrefetch()ormutate().
Every option and its exact behaviour is in the clarusjs/fetch reference.