ReviewOS

stacks/stx

Async components: client loader absent from emitted runtime + no SPA integration — @async/:component don't resolve on the live client

#1829
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

Summary

The async-component API (@async/@error directives + :component="() => import('./X.stx')" lazy loading) is processed at build/SSR time, but its client-side resolver is not in the emitted runtime and there is no SPA-router integration — so on a live client the loading placeholder is never swapped for the real component, and async components are never re-resolved across SPA navigation.

What exists

packages/stx/src/async-components.ts (with tests under packages/stx/test/async-components/):

  • @async(...) … @error … @endasync directive with loading / error / retry-backoff states
  • :component="() => import('./HeavyChart.stx')" lazy loading
  • processAsyncDirectives is called at build/SSR (packages/stx/src/process.ts:1363), emitting <div class="stx-async-loading" data-async-loading="…">…</div> placeholders.

What's missing (verified)

  • The emitted signals runtime does not contain the client loader or a placeholder resolver:

    const rt = generateSignalsRuntime()
    rt.includes('loadComponent')        // false
    rt.includes('data-async-loading')   // false  (no handler for the emitted placeholder)
  • packages/router/src/client.ts has zero references to async-components / data-async-loading. So the SPA _handleStxLoad path never resolves async placeholders.

Impact

@async / :component look supported (directive + passing unit tests), but in a served app the loading placeholder is never resolved on the client, and across SPA navigation async components don't re-resolve. Net effect: a silent "stuck on loading" / missing component — with the appearance of a supported feature.

Suggested fix

  1. Ship the async client loader in the emitted runtime (or inject it per-page when a page actually uses async components).
  2. Add a data-async-loading resolve pass to _handleStxLoad so async components hydrate on both initial load and SPA navigation.
  3. Until then, consider documenting async components as experimental / SSR-only so apps don't build on client resolution.

Note on confidence

Confirmed via generateSignalsRuntime() string content + a grep of router/client.ts. The existing tests pass but exercise the module outside the served-runtime path, so they don't catch the missing client/SPA wiring.

22 days ago

Closing as not a bug — this was a misdiagnosis on my part, and I want to correct the record.

The original report said the async client loader is "absent from the emitted runtime" and has "no SPA integration." That was wrong: the loader isn't in generateSignalsRuntime() because it's emitted inline per-component by generateAsyncComponentHtml — a self-contained <script> that fetches /_stx/component/…, with delay/timeout/retries, stx:navigate teardown, and a detached-container guard (the #1720 unmount race).

So @async components already work on initial load (proven by the existing tests: the fetched HTML lands in data-async-content with data-status="resolved") and on SPA nav — each render mints a fresh asyncId (async-<counter>-<ts>), so the loader body is unique per render and the router's content-hash dedup never skips it.

Added a regression test pinning the SPA-nav path (unique id per render + independent resolution on arrival/revisit): packages/stx/test/async-components/async-spa-nav.test.ts. No code change needed.

Sign in to comment on this issue.