Scrollcraft
Capitolul 11 din 15EN

Arhitectură: o structură care rezistă când site-ul crește.

Un site de o pagină poate trăi în trei fișiere. Când are multe secțiuni, rute sau oameni care lucrează la el, câteva decizii de structură îl păstrează rapid și ușor de schimbat.

Capitolul 11 din 154 min de citit

Ce vei învăța

La finalul capitolului
  1. 01Alegi tehnologiile după problemă: fișiere simple, GSAP, Next.js sau un backend.
  2. 02Organizezi fișierele astfel încât conținutul, secțiunile, mișcarea și bucla să stea fiecare într-un singur loc.
  3. 03Rulezi fiecare efect dintr-o singură buclă de animație, care se oprește când tab-ul e ascuns.
  4. 04Faci pagina să meargă complet fără JavaScript și cureți fiecare efect în React.

01 · Cum alegi tehnologiile

Simplu, GSAP, Next.js, Flask

Pentru un site cu scroll, tehnologiile contează mai puțin decât disciplina. Începe simplu. Adaugă o bibliotecă atunci când o problemă anume o cere.

OpțiuneFolosește-o cândCost
HTML, CSS, JS simpleO pagină sau câteva, un portofoliu, o pagină de prezentare, proiectul din acest tutorialGestionezi singur structura fișierelor și markupul repetat
JavaScript simplu plus GSAPMulte timeline-uri legate de scroll sau fixate, care trebuie să rămână sincronizateÎncă o bibliotecă de încărcat și de învățat
Next.js cu ReactMulte rute, componente comune, un CMS, randare pe server pentru motoarele de căutareUn pas de build, un server sau o găzduire care îl suportă și efecte care trebuie curățate la demontare
FlaskAi nevoie de backend: un formular de contact, o bază de date, un APINu animă nimic. Servește pagina și se ocupă de date

02 · Structura folderelor

Simplu și Next.js
a

Împarte după ce se schimbă împreună

Secțiunile se schimbă odată cu conținutul, componentele de mișcare odată cu designul, iar bucla aproape niciodată. Ține-le pe fiecare la locul ei.

Structură
Site simplu
  index.html
  style.css            întâi tokenurile, apoi secțiunile în ordinea paginii
  app.js               o buclă, o funcție pentru fiecare efect
  assets/              imagini, video, fonturi

Next.js
  app/                 rute și layout-uri (componente de server)
  components/
    sections/          un fișier pentru fiecare secțiune a paginii
    motion/            Reveal, Pin, Parallax: componente mici de client
  lib/
    ticker.ts          singura buclă de animație
  content/             text și date, ținute în afara componentelor
  public/              imagini, video, fonturi
b

Ține conținutul în afara componentelor

Textul, căile imaginilor și listele de funcții stau în fișiere de date sau într-un CMS. Componentele decid doar cum arată și cum se mișcă, iar site-ul poate primi o a doua limbă fără să le atingi.

03 · O buclă pentru tot site-ul

requestAnimationFrame
a

De ce una singură

Zece efecte cu zece bucle citesc fiecare poziția scrollului și scriu fiecare stiluri, într-o ordine pe care n-o controlează nimeni. O singură buclă citește o dată și actualizează totul în același cadru, și se poate opri când tab-ul e ascuns.

ticker.js
// ticker.js: o singură buclă requestAnimationFrame pentru tot site-ul
const jobs = new Set();
let raf = 0;

function frame(time) {
  for (const job of jobs) job(time);
  raf = jobs.size ? requestAnimationFrame(frame) : 0;
}

/** Rulează fn la fiecare cadru. Întoarce o funcție care o oprește. */
export function onFrame(fn) {
  jobs.add(fn);
  if (!raf && !document.hidden) raf = requestAnimationFrame(frame);
  return () => jobs.delete(fn);
}

// nu desena cât tab-ul e ascuns, pornește din nou când revine
document.addEventListener('visibilitychange', () => {
  if (document.hidden) { cancelAnimationFrame(raf); raf = 0; }
  else if (jobs.size && !raf) raf = requestAnimationFrame(frame);
});
b

Lenis și GSAP o împart

Dacă site-ul folosește GSAP, ticker-ul lui e bucla: condu Lenis din gsap.ticker ca în capitolul GSAP și adaugă-ți efectele în același ticker.

04 · Next.js și React

Aceleași efecte, cu curățenie

În React, efectele se mută în useEffect, iar tot ce pornești trebuie oprit la demontare. În App Router-ul Next.js, componenta are nevoie de ‘use client’, pentru că folosește browserul. Schița de mai jos nu a fost rulată aici; instalează lenis și gsap cu npm și testeaz-o în proiectul tău.

tsx
// components/Cinematic.tsx
'use client';
import { useEffect, useRef, type ReactNode } from 'react';
import Lenis from 'lenis';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

export default function Cinematic({ children }: { children: ReactNode }) {
  const root = useRef<HTMLDivElement>(null);

  useEffect(() => {
    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
    if (reduced) return;

    const lenis = new Lenis({ lerp: 0.1 });
    const tick = (time: number) => lenis.raf(time * 1000);
    lenis.on('scroll', ScrollTrigger.update);
    gsap.ticker.add(tick);
    gsap.ticker.lagSmoothing(0);

    const ctx = gsap.context(() => {
      gsap.utils.toArray<HTMLElement>('.reveal').forEach((el) => {
        gsap.from(el, {
          y: 28, opacity: 0, duration: 0.9, ease: 'power3.out',
          scrollTrigger: { trigger: el, start: 'top 85%', once: true }
        });
      });
    }, root);

    return () => {
      ctx.revert();
      gsap.ticker.remove(tick);
      lenis.destroy();
    };
  }, []);

  return <div ref={root}>{children}</div>;
}

05 · Îmbunătățire progresivă

Merge și fără efecte
a

Întâi conținutul

Pagina trebuie să se citească întreagă cu JavaScript oprit, cu un script blocat sau cu animațiile dezactivate de sistem. Efectele se adaugă deasupra; nu țin niciodată conținutul ostatic.

index.html
<!-- clasa se adaugă înainte să se deseneze pagina, doar când rulează JavaScript -->
<script>document.documentElement.classList.add('js');</script>

<style>
  /* conținutul se ascunde doar când există un script care să-l arate */
  .js .reveal { opacity: 0; transform: translateY(24px); }
  .js .reveal.in { opacity: 1; transform: none; transition: opacity .6s, transform .6s; }
</style>
b

Întâi serverul, în Next.js

Păstrează secțiunile ca componente de server și învelește doar părțile care se mișcă în componente mici de client, precum <Reveal>. Ajunge mai puțin JavaScript pe telefon, iar textul e în HTML pentru motoarele de căutare.

c

Curăță

Fiecare listener, observer, buclă și ScrollTrigger pe care îl creezi se elimină când componenta lui părăsește pagina. În React, asta face funcția întoarsă din useEffect, sau useGSAP, care o face în locul tău.

Practică · Lucrul cu AI

Aceeași sarcină, în unealta ta

La refactorizare AI-ul economisește cel mai mult timp și face cele mai mari stricăciuni. Cere un plan, păstrează comportamentul identic și verifică după fiecare mutare.

Deschide un terminal în folderul proiectului și rulează claude. Apasă Shift+Tab până se pornește modul plan, lipește promptul, citește planul, apoi aprobă-l. Regulile proiectului stau în CLAUDE.md.

O singură buclă

Prompt
Citește CLAUDE.md și app.js. Refactorizează fiecare efect de scroll și de animație din site-ul pentru [subiect] ca să ruleze dintr-o singură buclă requestAnimationFrame în ticker.js, cu o funcție onFrame(fn) care întoarce o funcție de oprire și face pauză cât tab-ul e ascuns. Comportamentul trebuie să rămână identic. Dă-mi întâi planul, apoi mută câte un efect o dată.

Fără JavaScript

Prompt
Listează tot ce e ascuns, poziționat sau creat de JavaScript în pagină. Pentru fiecare, spune-mi ce vede un vizitator cu JavaScript oprit și cea mai mică schimbare care îl face lizibil.

Practică · Exerciții

Încearcă, apoi compară
1

Alege tehnologiile

Alege tehnologiile pentru fiecare: un site de lansare de o pagină; un site de studio cu patruzeci de proiecte și un CMS; o pagină de prezentare cu un formular de contact care salvează mesajele.

Indiciu: tabelul din secțiunea 01 are câte un rând pentru fiecare.

Arată soluția

HTML, CSS și JS simplu pentru lansare; Next.js pentru patruzeci de proiecte și un CMS; fișiere simple plus un backend mic (Flask sau un serviciu de formulare) pentru formularul de contact.

2

Numără buclele

Caută în app.js după requestAnimationFrame și addEventListener('scroll'. Câte bucle și câți listeneri separați ai?

Indiciu: fiecare efect scris separat adaugă de obicei câte unul din fiecare.

Arată soluția

Mai mult de unul din oricare înseamnă că efectele citesc scrollul în momente diferite ale cadrului. Mută-le într-o singură buclă: citești scrollul o dată, apoi actualizezi fiecare efect.

3

Oprește JavaScript

În Chrome DevTools, deschide meniul de comenzi, rulează „Disable JavaScript” și reîncarcă pagina.

Indiciu: meniul de comenzi se deschide cu Cmd+Shift+P sau Ctrl+Shift+P.

Arată soluția

Totul ar trebui să se citească în continuare: stările ascunse se aplică doar sub clasa .js, iar secțiunile fixate sau orizontale revin la fluxul normal. Tot ce lipsește arată o regulă care ascunde conținut fără acea clasă.

Practică · Proiectul cursului

Un site, construit pe tot parcursul

Fă site-ul pentru [subiect] ușor de schimbat: o buclă, fișiere clare și conținut care rezistă fără scripturi.

  1. Rulează „O singură buclă” și mută efectele pe rând, verificând pagina după fiecare.
  2. Împarte app.js în buclă și câte o funcție pentru fiecare efect, ca în secțiunea 02.
  3. Rulează „Fără JavaScript” și repară ce găsește.
  4. Fă commit separat pentru fiecare pas.

Practică · Testează

Verifici rezultatul
  • requestAnimationFrame apare într-un singur loc: în buclă.
  • Dacă treci pe alt tab și revii, efectele fac pauză și pornesc din nou.
  • Cu JavaScript oprit, fiecare secțiune se poate citi.
  • Pagina arată și se poartă exact ca înainte de refactorizare.

Practică · Evaluare

Criterii de acceptare

0 din 4 criterii îndeplinite

Urmează Performanță

Core Web Vitals, un buget pentru imagini, video și fonturi, regulile care păstrează scrollul fluid și cum măsori.

Scurtături de tastatură: [ capitolul anterior · ] capitolul următor