Summary
stx's client data layer has no hook between the composable and fetch. __stxFetch (packages/stx/src/signals.ts:161-172) calls fetch(url, opts) directly, and useFetch/useQuery/useMutation accept headers only as a plain object captured when the composable is created. There is no way to attach a per-call bearer token, and no way to observe or act on a response before the composable throws. All three implementations throw new Error('HTTP ' + status) before reading the body, so the server's own error message is unreachable and a 401 cannot be turned into a token refresh + retry.
The practical result is that an app with authenticated endpoints cannot use the framework's data layer at all.
Impact (real app)
analyticshq is an analytics SaaS; every data endpoint is bearer-authenticated. We wrote our own client:
resources/stores/session.ts:215-240—authFetch(input, init): attaches the header, detects 401, renews, retries once.resources/stores/session.ts:124-127—bearer()builds the header object.- 10 call sites go through it:
resources/views/dashboard.stx:859, 883, 908, 926, 1031, 1049;resources/views/account.stx:54;resources/views/sites/new.stx:45;resources/views/pricing.stx:35.
grep -rn 'useFetch(\|useQuery(\|useMutation(' resources/ app/ returns zero hits across the whole app.
The store documents why it had to exist (resources/stores/session.ts:206-213):
Every authenticated call on this page goes through session.authFetch, which attaches the bearer header, renews an expired access token and retries once (#32). The local authHeaders() helper that used to live here only attached the header, so an hour into a session this whole page 401'd: goals could not be added or deleted, share links […]
Because authFetch can only return a raw Response, every consumer re-implements status handling and JSON parsing:
// resources/views/dashboard.stx:1031-1034
session.authFetch('/api/me')
.then(r => r.ok ? r.json() : null)
.then(d => { if (d && d.pro) isPro.set(true) })
.catch(() => {})That shape is repeated at all 10 call sites. None of them gets { data, loading, error }.
Evidence in stx
packages/stx/src/signals.ts:161-172 — the single choke point, with no hook:
async function __stxFetch(source, url, opts) {
var t0 = __stxDevtoolsNow();
var method = (opts && opts.method) || 'GET';
try {
var r = await fetch(url, opts); // ← no onRequest / onResponse
__stxDevtoolsRecordQuery({ ... });
return r;
} catch (e) { ... }
}packages/stx/src/signals.ts:955-961 (useFetch), :1243 (useQuery), :1319-1323 (useMutation) each build headers from a static options object:
var fetchOpts = { method: 'GET', headers: { 'Content-Type': 'application/json', ...(options.headers || {}) } };packages/stx/src/signals.ts:1325 (useMutation) — body unreachable on failure:
if (!response.ok) throw new Error('HTTP ' + response.status + ': ' + response.statusText);
var result = await response.json();Same at :971-973 (useFetch) and :1245 (useQuery).
packages/stx/src/runtime-globals.ts:43-58 — STX_RUNTIME_GLOBALS exposes no fetch-configuration or interceptor name, so there is nothing an app could reach for even out-of-band.
Prior art
- Angular:
HTTP_INTERCEPTORSmulti-provider +HttpClient; every request passes through the chain. - axios:
instance.interceptors.request.use(fn)/interceptors.response.use(ok, err). - Nuxt/ofetch:
$fetch.create({ onRequest, onRequestError, onResponse, onResponseError }), anduseFetchruns through it. - TanStack Query:
new QueryClient({ defaultOptions: { queries: { queryFn } } })— one shared fetcher for every query.
Ask
- Add a configurable fetch instance that
__stxFetchroutes through, e.g.createFetch({ baseURL, onRequest, onResponse, onResponseError }), exposed as a runtime global and settable once per app (setDefaultFetch(instance)). - Accept
headersasRecord<string,string> | (() => Record<string,string>)inuseFetch/useQuery/useMutation, resolved per request rather than at creation. - Stop throwing before the body is read: attach the parsed body to the error (
err.data,err.status,err.response) so{message}/{error}payloads are reachable by consumers. - Give
onResponseErrorthe ability to return a replacement response, so a 401 → refresh → retry can be expressed once in framework code instead of per app.
Related: #1843 (adoption report — this is the concrete reason the data layer went unused in a second app), #1726 (the two useFetch impls).