Pubblicato il 6 min di lettura
Portfolio animato ma veloce: scena 3D caricata a riposo
Come è costruito questo portfolio: scena WebGL caricata a riposo, guardia FPS, livelli di movimento con reduced motion, GSAP lazy e budget del bundle in CI.
Il portfolio di uno sviluppatore frontend ha un problema di credibilità. Se è lento o inaccessibile, la prima impressione è già sbagliata; se è piatto, non dimostra nulla. Ho voluto un sito con una scena 3D e animazioni vere, che però si carichi come una pagina statica e funzioni con il movimento ridotto e senza WebGL. Ecco come l'ho costruito, con i limiti che il progetto stesso si impone.
La scena parte quando il browser è libero
La scena usa React Three Fiber, e la sua libreria non deve competere con il primo paint. CosmicBackground carica il componente con lazy(() => import("./CosmicCanvas")) e lo monta solo quando il browser è libero:
useEffect(() => {
if (idle || level === "reduced") return;
if (rememberedSlow() || saveDataRequested()) return;
return whenIdle(() => setIdle(true), FALLBACK_MS, IDLE_TIMEOUT_MS);
}, [level, idle]);
whenIdle usa requestIdleCallback con un tetto di 600 ms. Dove la funzione manca (il commento nel codice indica Safari), usa un setTimeout di 1200 ms. Il timeout garantisce l'avvio anche sui browser che non concedono mai una finestra libera. Nel frattempo StaticFallback resta visibile finché il contesto WebGL non segnala di essere pronto, quindi non c'è un lampo nero all'apertura. Con il risparmio dati attivo (navigator.connection.saveData) la scena non viene nemmeno richiesta. Il canvas sta nel layout condiviso del sito, quindi non si rimonta a ogni pagina: cambiare percorso aggiorna solo la modalità della scena nello store.
Guardia FPS: il 3D si spegne da solo
Caricare la scena in ritardo non basta: un telefono vecchio può restare a 15 fps. createFpsGuard misura i frame di requestAnimationFrame. Scarta i primi 30 frame, cioè la compilazione degli shader, raccoglie tre secondi di frame e confronta la mediana dei delta con la soglia:
deltas.push(delta);
elapsed += delta;
if (elapsed >= windowMs) {
const fps = 1000 / median(deltas);
verdict = fps < minFps ? "slow" : "ok";
}
La mediana ignora gli scatti isolati, come una garbage collection o un caricamento, che una media non ignorerebbe. Sotto 40 fps il verdetto è slow. Un intervallo di più di cinque secondi è una sospensione del sistema e non un frame lento, quindi azzera la misura, come fa il tab quando è nascosto. Quando il verdetto è slow, la scena si disattiva e viene scritto off in sessionStorage: nelle visite successive dello stesso tab il chunk 3D non viene nemmeno scaricato. Il verdetto vale per la sessione del tab, non per sempre.
Tre livelli di movimento
computeMotionLevel sceglie tra tre livelli:
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 se l'utente ha chiesto prefers-reduced-motion; lite con un puntatore grossolano o una finestra sotto 768 px; full altrove. Tra 768 e 799 px c'è un'isteresi: il livello non cambia, così un resize di pochi pixel non rilancia Lenis e i trigger. Il livello lite riduce i dettagli: il canvas arriva al pixel ratio massimo di 1 (contro 1,5 del livello full) e la nebulosa usa meno ottave.
Il provider parte da reduced, così il primo render, quello prerenderizzato, non contiene animazioni. Il livello vero si calcola al montaggio. Con reduced Lenis e ScrollTrigger non vengono nemmeno scaricati.
GSAP e Lenis caricati su richiesta
Lenis e i plugin GSAP restano fuori dal bundle d'ingresso. lazyPlugin tiene una sola Promise: le chiamate successive ricevono la stessa. Se l'import fallisce, la cache si svuota, così un tentativo successivo può riuscire. whenReady crea un tween solo quando il plugin è pronto, subito se è già caricato.
Lo scroll orizzontale della home è il caso più interessante. Il binario delle card si sposta con uno scrub di ScrollTrigger, dentro un blocco alto come il viewport più la distanza da percorrere. Un riquadro position: sticky resta fermo mentre la pagina scorre. Ho evitato il pin di GSAP: fissava la larghezza del blocco al contenitore e tagliava il binario sugli schermi larghi. Con la tastiera il focus può atterrare su una card ancora fuori campo, quindi un listener focusin riporta la pagina alla posizione giusta. Lo scroll orizzontale è attivo solo al livello full.
HTML pronto e budget del bundle
Il sito è una SPA con React Router e ssr: false, ma react-router.config.ts prerenderizza ogni pagina: i percorsi dei progetti, /cv e /en/cv, con le varianti bilingui. Ogni URL ha già il suo HTML, con contenuto, titolo e metadati, e il crawler lo trova senza dover eseguire il JavaScript.
Il budget è uno script, scripts/bundle-size.mjs. Legge l'HTML prerenderizzato, trova gli script d'ingresso (type="module" e modulepreload), ne somma la dimensione gzip e fallisce sopra 180 KB. La specifica del progetto fissava 200 KB; i 20 KB di margine servono per gli aggiornamenti delle dipendenze. Il workflow di deploy esegue lo script a ogni build. Lo script conta solo il JavaScript che il browser scarica prima di mostrare la pagina, non le immagini né i font. Non riporto il valore attuale, perché non l'ho misurato per questo articolo: lo stampa lo script.
Test: il movimento ridotto si verifica
I test unitari (Vitest) coprono la logica di movimento: il guardia FPS, i livelli e il provider. I test end-to-end (Playwright) verificano che con prefers-reduced-motion non compaia nessun canvas; che senza WebGL resti lo sfondo statico e il sito sia navigabile; che su mobile la scena parta senza alcun gesto. Un test con axe, sulle pagine prerenderizzate, fallisce su violazioni critiche o serie dei criteri WCAG 2 A e AA. Uno script di privacy controlla il build e i contenuti alla ricerca di pattern che non devono comparire pubblicamente.
Cosa farei diversamente
Il verdetto FPS è definitivo: una scena che va bene per tre secondi e poi si blocca non viene mai spenta. Vorrei un controllo continuo a bassa frequenza, che disattivi la scena anche durante lo scroll. Il budget copre solo il JavaScript d'ingresso: il peso dei font e delle immagini non è sotto controllo automatico, e dovrei aggiungerlo.
Il sito che stai leggendo è costruito con queste regole.
- React
- React Three Fiber
- accessibilità
- prestazioni
- GSAP
Hai un progetto simile? Parliamone
Se stai affrontando una sfida simile, scrivimi: ti dico come la affronterei.
Parliamone