Skip to content
← All articles

Published on 6 min read

An animated portfolio that stays fast: a 3D scene loaded at rest

How this portfolio is built: a WebGL scene loaded when the browser is idle, an FPS guard, motion levels and reduced motion, lazy GSAP and a CI bundle budget.

A frontend developer's portfolio has a credibility problem. If it is slow or inaccessible, the first impression is already lost. If it is flat, it proves nothing. I wanted a site with a real 3D scene and real animation, that still loads like a static page and works with reduced motion and without WebGL. This is how I built it, within the limits the project sets for itself.

The scene starts when the browser is idle

The scene uses React Three Fiber, and its library must not compete with the first paint. CosmicBackground loads the component with lazy(() => import("./CosmicCanvas")) and mounts it only when the browser is idle:

useEffect(() => {
  if (idle || level === "reduced") return;
  if (rememberedSlow() || saveDataRequested()) return;
  return whenIdle(() => setIdle(true), FALLBACK_MS, IDLE_TIMEOUT_MS);
}, [level, idle]);

whenIdle uses requestIdleCallback with a 600 ms ceiling. Where the function is missing (the code comment points to Safari), it falls back to a setTimeout of 1200 ms. The timeout guarantees the scene starts even on browsers that never grant an idle window. Meanwhile StaticFallback stays visible until the WebGL context reports it is ready, so there is no black flash on arrival. When data saving is enabled (navigator.connection.saveData), the scene is not requested at all. The canvas lives in the site's shared layout, so it is not remounted on every page: changing route only updates the scene's mode in the store.

An FPS guard that switches 3D off by itself

Loading the scene late is not enough: an old phone can sit at 15 fps. createFpsGuard measures requestAnimationFrame frames. It discards the first 30 frames, which cover shader compilation, collects three seconds of frames and compares the median frame delta with a threshold:

deltas.push(delta);
elapsed += delta;
if (elapsed >= windowMs) {
  const fps = 1000 / median(deltas);
  verdict = fps < minFps ? "slow" : "ok";
}

The median ignores isolated spikes, such as a garbage collection or a resource load, that an average would not ignore. Below 40 fps the verdict is slow. A gap longer than five seconds is a system suspension rather than a slow frame, so it resets the measurement, as a hidden tab does. When the verdict is slow, the scene shuts down and off is written to sessionStorage: on later visits in the same tab, the 3D chunk is not even downloaded. The verdict lasts for the tab's session, not forever.

Three motion levels

computeMotionLevel picks one of three levels:

export function computeMotionLevel(env: MotionEnv, previous?: MotionLevel): MotionLevel {
  if (env.reducedMotion) return "reduced";
  if (env.coarsePointer) return "lite";
  if (env.viewportWidth < LITE_BELOW_PX) return "lite";
  if (env.viewportWidth < FULL_FROM_PX) return previous === "lite" ? "lite" : "full";
  return "full";
}

reduced when the user has asked for prefers-reduced-motion; lite with a coarse pointer or a window under 768 px; full everywhere else. Between 768 and 799 px there is hysteresis: the level does not change, so a resize of a few pixels does not restart Lenis and the triggers. lite trims detail: the canvas caps its pixel ratio at 1 (against 1.5 for full), and the nebula uses fewer octaves.

The provider starts in reduced, so the first render, the one that gets prerendered, contains no animation. The real level is computed on mount. At reduced, Lenis and ScrollTrigger are not even downloaded.

GSAP and Lenis loaded on demand

Lenis and the GSAP plugins stay out of the entry bundle. lazyPlugin keeps a single promise: later calls receive the same one. If the import fails, the cache is cleared so a later attempt can succeed. whenReady creates a tween only once the plugin is ready, and immediately if it is already loaded.

The home page's horizontal scroll is the most interesting case. The row of cards moves with a ScrollTrigger scrub, inside a block as tall as the viewport plus the distance to travel. A position: sticky panel stays in place while the page scrolls. I avoided GSAP's pin: it fixed the block's width to its container and cut the row off on wide screens. With the keyboard, focus can land on a card that is still off screen, so a focusin listener scrolls the page to the right position. Horizontal scrolling is active only at the full level.

Prerendered HTML and a bundle budget

The site is a React Router SPA with ssr: false, but react-router.config.ts prerenders every page: the project routes, /cv and /en/cv, with their bilingual variants. Each URL already has its own HTML, with content, title and metadata, so a crawler finds the text without running JavaScript.

The budget is a script, scripts/bundle-size.mjs. It reads the prerendered HTML, finds the entry scripts (type="module" and modulepreload), sums their gzip size and fails above 180 KB. The project spec set 200 KB; the 20 KB of margin is there for dependency updates. The deploy workflow runs the script on every build. The script counts only the JavaScript the browser downloads before showing the page, not images or fonts. I do not quote the current figure, because I did not measure it for this article: the script prints it.

Tests: reduced motion is something you can verify

Unit tests (Vitest) cover the motion logic: the FPS guard, the levels and the provider. End-to-end tests (Playwright) check that with prefers-reduced-motion no canvas appears, that without WebGL the static background stays and the site remains navigable, and that on mobile the scene starts without any gesture. An axe test runs on the prerendered pages and fails on critical or serious violations of WCAG 2 A and AA. A privacy script scans the build and the content for patterns that must not be published.

What I would do differently

The FPS verdict is final: a scene that runs well for three seconds and then stalls is never switched off. I would like a low-frequency check that keeps running, and that also switches the scene off during scrolling. The budget covers only the entry JavaScript: the weight of fonts and images is not checked automatically, and I should add that.

The site you are reading now is built with these rules.

  • React
  • React Three Fiber
  • accessibility
  • performance
  • GSAP

Have a similar project? Let's talk

If you're facing a similar challenge, get in touch and I'll tell you how I would approach it.

Let's talk