frontend-components-advanced

Advanced Component Patterns

Thesis: Browser-only components need Suspense and static DOM wrappers; production components must never ship demo behavior; two raw-<input> cases are intentional.

Lazy Loading (Browser-Only Components)

Components that use browser APIs (Three.js, WebRTC, canvas) must be lazy-loaded with <Suspense>:

// In the CONSUMER file (e.g., a section or page):
import { lazy, Suspense } from "solid-js";
const Canvas3D = lazy(() => import("~/components/molecules/Canvas3D/Canvas3D")
  .then(m => ({ default: m.Canvas3D })));

// Usage — Suspense is REQUIRED or the component silently renders nothing:
<Suspense>
  <Canvas3D />
</Suspense>

Inside the lazy component, if onMount appends DOM nodes (e.g., containerRef.appendChild(canvas)), the return JSX must include a static wrapper div — not just a Switch/Match. Without a static element, onMount may not fire:

// GOOD — static div always in DOM, conditional content inside
<div ref={containerRef} class="relative w-full h-full">
  <div class="absolute inset-0 pointer-events-none"
    style={{ display: loading() || error() ? undefined : "none" }}>
    <Switch>
      <Match when={loading()}><Spinner /></Match>
      <Match when={error()}><ErrorText /></Match>
    </Switch>
  </div>
</div>

// BAD — Switch as only child can prevent onMount from firing
<div ref={containerRef}>
  <Switch>
    <Match when={loading()}>...</Match>
  </Switch>
</div>

Never call onCleanup() after an await — use mutable refs cleaned up in the synchronous onCleanup registered during component creation.

Do NOT

• Import from other atoms inside an atom (that makes it a molecule)
• Use createSignal for internal state unless the component is interactive (forms, toggles)
• Use inline styles — use Tailwind classes
• Create a raw HTML element when a component exists (<select> → use <Select>, confirm() → use <DestructiveModal>)
• Use lazy() without a <Suspense> boundary — it silently renders nothing
• Build "demo state" (random failures, fake delays, mocked data, simulateX helpers) directly into a component that is also used in production. If a component needs a showcase variant, gate the demo behavior on the absence of an integration prop (Show when={hasFiles() && !props.onFilesSelected}) so the demo UI only renders when no callback is wired. The Dropzone bug (9a68b1e) shipped fake "Upload failed" badges on top of real uploads to real users for weeks because simulateUpload() rendered alongside the real upload state. Mock data on dedicated showcase routes (e.g. (private)/components/sections/, the /components showcase) is fine — those routes are the showcase, not consumers of one.