⚡ spark-html-query

Declarative async data for spark-html — a self-fetching reactive store. One dependency (spark-html), built entirely on its store().

A query runs an async function and exposes the result as reactive store state. Any component reads it with the same useStore it already knows, and re-renders as the request settles — no onMount, no manual loading flags, no fetch boilerplate.

import { query } from 'spark-html-query';

query('user', () => fetch('/api/user').then((r) => r.json()));

<!-- any component -->
<script>const user = useStore('user');</script>

<p :hidden="!user.loading">Loading…</p>
<p :hidden="!user.error">Failed: {user.error.message}</p>
<h1 :hidden="user.loading">{user.data?.name}</h1>
<button onclick="{user.refetch}">Reload</button>

Install

bun add spark-html-query

State

useStore(name) returns a reactive object:

| Key | Meaning | |-----|---------| | data | The latest resolved value (or initialData / null before the first). | | error | The last rejection, or null. | | loading | true until the first successful result (no data yet). | | fetching | true during any in-flight fetch, including a refetch over existing data. | | refetch() | Re-run the fetcher. A newer call supersedes an older in-flight one. | | mutate(next) | Set data directly without fetching (optimistic update). Value or (prev) => next. | | stop() | Stop the refetchInterval poller, if any. |

Options

query('feed', fetchFeed, {
  initialData: [],          // seed data; skips the initial `loading` state
  refetchInterval: 30000,   // poll every 30s
  lazy: true,               // with initialData: wait for the first refetch()
});

Pairs with derived

Shape a query into exactly what a component needs, memoized — the view updates as the request settles:

import { query } from 'spark-html-query';
import { derived } from 'spark-html';

query('todos', fetchTodos);
derived('todoStats', ['todos'], (q) => ({
  total: q.data?.length ?? 0,
  done: q.data?.filter((t) => t.done).length ?? 0,
  loading: q.loading,
}));

loading vs fetching: show a skeleton on loading (first load, no data yet) and a subtle spinner on fetching (background refresh that keeps the stale data visible). That's the stale-while-revalidate pattern, declaratively.

The Spark family

Small, single-purpose packages that share one philosophy: no compiler, no virtual DOM, no build step required — built for humans who love hand-writing their web apps. Add only what you use.

| Package | What it does | |---|---| | spark-html | The runtime — components, reactivity, stores, forms, scoped styles. ~14.4 kB gzip, 0 deps. | | spark-html-bun | Dev server, bundler & preview on Bun — scoped HMR, no-build dev, post-build pipeline. | | spark-html-router | <template route> routing — nested routes/layouts, route.query, active links. | | spark-html-theme | Dark/light/system theming in one line — persisted, no flash. | | spark-html-head | Reactive <title>/<meta> per route + a head store. | | spark-html-motion | Enter/leave transitions on if/each blocks — transition="fade|slide|scale". | | spark-html-devtools | In-page devtools — live stores, component tree, patch activity. | | spark-html-query | Declarative async data — a self-fetching store (loading/error/data/refetch). | | spark-html-persist | Persist stores to localStorage/sessionStorage in one line. | | spark-html-websocket | A WebSocket as a reactive store — auto-reconnect, JSON, send(). | | spark-prerender | Build-time SEO prerender + sitemap/robots — no SSR server. | | spark-ssr | Full-stack SSR on Bun — the template is the backend: inferred DB, REST CRUD, auth, live updates. Precompiled + response-cached: fast by default. | | spark-html-image | Build-time image optimization — webp/avif + responsive srcset, zero config. | | spark-html-font | Font loading optimizer — preload + size-adjusted fallbacks, no FOUT. | | spark-html-manifest | PWA manifest + icons + head tags (and optional service worker) from one config. | | spark-html-offline | Offline URL imports — a service worker that caches CDN components. | | spark-html-sri | Subresource Integrity — hash + verify assets and remote components. | | create-spark-html-app | Scaffold a spark-html app in one command. | | prettier-plugin-spark | Prettier for components — formats <script>/<style>, markup stays byte-for-byte. | | spark-html-language-server | LSP — diagnostics, go-to-definition, prop autocomplete, hover docs. |