Skip to content

Avoid passive esbuild-wasm loads in Charts docs #1130

Description

@tannerlinsley

@tannerlinsley The new inline Charts documentation examples automatically load a browser compiler and execute as readers approach them. This needs a product/performance decision rather than an automatic behavior change.

Evidence

  • ChartsCatalogDocExample switches from its existing static SVG preview to the live client when the section enters a 320px root margin: source.
  • The live client immediately fetches the complete example workspace: source.
  • ChartsCatalogResult then calls compileExampleWorkspace without further user intent: source.
  • The compiler is the pinned esbuild-wasm@0.27.4: source.
  • A production build emits dist/client/assets/esbuild-*.wasm at 13,539,721 bytes raw / 3,614,425 bytes gzip. The shared browser compiler JS is another 74,128 bytes raw / 21,234 bytes gzip. This excludes the fetched example source and esm.sh runtime modules.
  • Current TanStack/charts main contains 89 ::chart-example directives across 29 docs pages. The largest page, docs/examples/polar-and-radar.md, contains 15. Each newly approached example recompiles and mounts even when the reader does not select Run or Edit.
  • The static ChartsCatalogPreview is already rendered before the live client loads, so a compiler-free passive state exists.
  • This is distinct from Bound Charts hero auto-rotation asset loading #1091: that issue bounded landing-page catalog rotation. This path was added later for docs examples.

Expected impact

Keeping passive docs examples static would avoid roughly 3.6 MB of first-visit compiler transfer plus WASM initialization/compile CPU and remote module requests for readers who only read or scroll the page. It would also prevent multi-example pages from progressively compiling and mounting every chart.

Proposed direction

Keep the existing static preview until the reader selects Run or Edit. That action can load the current client, fetch the workspace, initialize the shared compiler once, and preserve the current editable/runnable experience from that point onward.

Add a focused component test asserting that visibility alone does not load the live client and that explicit activation does.

Alternatives and tradeoffs

  1. Click to run/edit — lowest passive cost and reuses the current static preview; live charts no longer start automatically.
  2. Auto-run only the first example per page — preserves one immediate live demonstration but adds page-level coordination and still pays the compiler cost.
  3. Serve precompiled immutable catalog modules for passive rendering — retains automatic interactivity without shipping the browser compiler, but restores publication/build machinery that the new source-driven path deleted.
  4. Keep current behavior — simplest and maximizes immediate interactivity, but explicitly accepts the compiler transfer and progressive compile/mount work on docs pages.

Decision needed

Should Charts docs examples remain auto-running near the viewport, or should live compilation wait for Run/Edit? If auto-run is required, is restoring a precompiled passive-render path worth the added catalog publication complexity?

Validation

  • pnpm build completed and emitted the measured production assets.
  • Duplicate searches for esbuild-wasm, passive Charts docs, auto-run chart examples, and browser compiler docs found no matching open/closed issue or open PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    source-auditTracked by the automated source audit

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions