Architecture: structure that holds as the site grows.
A one-page site can live in three files. Once it has many sections, routes or people working on it, a few structural decisions keep it fast and easy to change.
What you will learn
By the end of this chapter- 01Choose a stack by the problem: plain files, GSAP, Next.js or a backend.
- 02Organise files so content, sections, motion and the loop each live in one place.
- 03Run every effect from one animation loop that stops when the tab is hidden.
- 04Make the page work in full without JavaScript, and clean up every effect in React.
01 · Choosing a stack
Plain, GSAP, Next.js, FlaskFor a scroll site the stack matters less than the discipline. Start plain. Add a library when a specific problem asks for it.
| Option | Use it when | Cost |
|---|---|---|
| Plain HTML, CSS, JS | One page or a few pages, a portfolio, a landing page, this tutorial’s project | You manage the file structure and repeated markup yourself |
| Vanilla plus GSAP | Many scrubbed or pinned timelines that must stay in sync | One more library to load and learn |
| Next.js with React | Many routes, shared components, a CMS, server rendering for search | A build step, a server or host that supports it, and effects that must clean up on unmount |
| Flask | You need a backend: a contact form, a database, an API | It does not animate anything. It serves the page and handles data |
02 · Folder structure
Plain and Next.jsSplit by what changes together
Sections change with the content, motion components change with the design, and the loop almost never changes. Keep each in its own place.
Plain site
index.html
style.css tokens first, then sections in page order
app.js one loop, one function per effect
assets/ images, video, fonts
Next.js
app/ routes and layouts (server components)
components/
sections/ one file per section of the page
motion/ Reveal, Pin, Parallax: small client components
lib/
ticker.ts the single animation loop
content/ text and data, kept out of the components
public/ images, video, fontsKeep content out of components
Text, image paths and lists of features live in data files or a CMS. The components only decide how they look and move, and the site can gain a second language without touching them.
03 · One loop for the whole site
requestAnimationFrameWhy one
Ten effects with ten loops each read the scroll position and each write styles, in an order nobody controls. One loop reads once and updates everything in the same frame, and it can stop when the tab is hidden.
// ticker.js: one requestAnimationFrame loop for the whole site
const jobs = new Set();
let raf = 0;
function frame(time) {
for (const job of jobs) job(time);
raf = jobs.size ? requestAnimationFrame(frame) : 0;
}
/** Run fn every frame. Returns a function that stops it. */
export function onFrame(fn) {
jobs.add(fn);
if (!raf && !document.hidden) raf = requestAnimationFrame(frame);
return () => jobs.delete(fn);
}
// stop drawing while the tab is hidden, start again when it comes back
document.addEventListener('visibilitychange', () => {
if (document.hidden) { cancelAnimationFrame(raf); raf = 0; }
else if (jobs.size && !raf) raf = requestAnimationFrame(frame);
});04 · Next.js and React
Same effects, with cleanupIn React the effects move into useEffect, and everything you start has to be stopped on unmount. In the Next.js App Router the component needs ‘use client’ because it touches the browser. This sketch was not run here; install lenis and gsap with npm and test it in your project.
// 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 · Progressive enhancement
Works without the effectsContent first
The page must read in full with JavaScript off, a script blocked, or animations disabled by the system. Effects are added on top; they never hold content hostage.
<!-- the class is added before the page paints, only when JavaScript runs -->
<script>document.documentElement.classList.add('js');</script>
<style>
/* content is hidden only when a script is there to reveal it */
.js .reveal { opacity: 0; transform: translateY(24px); }
.js .reveal.in { opacity: 1; transform: none; transition: opacity .6s, transform .6s; }
</style>Server first in Next.js
Keep sections as server components and wrap only the moving parts in small client components such as <Reveal>. Less JavaScript reaches the phone, and the text is in the HTML for search engines.
Clean up
Every listener, observer, loop and ScrollTrigger you create is removed when its component leaves the page. In React that is the function returned from useEffect, or useGSAP which does it for you.
Practice · Work with AI
The same task in your toolRefactoring is where the AI saves the most time and does the most damage. Ask for a plan, keep behaviour identical, and check after each move.
Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.
One loop
Read CLAUDE.md and app.js. Refactor every scroll and animation effect in the site for [subject] to run from one requestAnimationFrame loop in ticker.js, with an onFrame(fn) function that returns a stop function and pauses while the tab is hidden. Behaviour must stay identical. Give me the plan first, then move one effect at a time.Without JavaScript
List everything on the page that is hidden, positioned or created by JavaScript. For each, tell me what a visitor sees with JavaScript turned off, and the smallest change that makes it readable.Open a terminal in the project folder and run gemini; the first time, it asks whether you trust the folder, so say yes for your project. Paste the prompt. Gemini CLI asks before it edits a file or runs a command: read each request before you accept it. Project rules go in GEMINI.md.
One loop
Read GEMINI.md and app.js. Refactor every scroll and animation effect in the site for [subject] to run from one requestAnimationFrame loop in ticker.js, with an onFrame(fn) function that returns a stop function and pauses while the tab is hidden. Behaviour must stay identical. Give me the plan first, then move one effect at a time.Without JavaScript
List everything on the page that is hidden, positioned or created by JavaScript. For each, tell me what a visitor sees with JavaScript turned off, and the smallest change that makes it readable.Open a terminal in the project folder and run codex, then paste the prompt and approve each change. In the ChatGPT app without Codex, attach the files, paste the prompt and copy the changes back yourself. Project rules go in AGENTS.md.
One loop
Read AGENTS.md and app.js. Refactor every scroll and animation effect in the site for [subject] to run from one requestAnimationFrame loop in ticker.js, with an onFrame(fn) function that returns a stop function and pauses while the tab is hidden. Behaviour must stay identical. Give me the plan first, then move one effect at a time.Without JavaScript
List everything on the page that is hidden, positioned or created by JavaScript. For each, tell me what a visitor sees with JavaScript turned off, and the smallest change that makes it readable.Practice · Exercises
Try first, then comparePick the stack
Choose a stack for each: a one-page launch site; a studio site with forty projects and a CMS; a landing page with a contact form that stores messages.
Hint: the table in section 01 has a row for each.
Show the solution
Plain HTML, CSS and JS for the launch; Next.js for forty projects and a CMS; plain files plus a small backend (Flask or a form service) for the contact form.
Count the loops
Search your app.js for requestAnimationFrame and addEventListener('scroll'. How many separate loops and listeners do you have?
Hint: each effect written separately usually adds one of each.
Show the solution
More than one of either means effects read the scroll at different moments in the frame. Move them to one loop: read the scroll once, then update every effect.
Turn JavaScript off
In Chrome DevTools, open the command menu, run “Disable JavaScript” and reload your page.
Hint: the command menu opens with Cmd+Shift+P or Ctrl+Shift+P.
Show the solution
Everything should still be readable: hidden states only apply under the .js class, and pinned or horizontal sections fall back to normal flow. Anything missing reveals a rule that hides content without that class.
Practice · Course project
One site, built across the courseMake the site for [subject] easy to change: one loop, clear files, and content that survives without scripts.
- Run “One loop” and move the effects one at a time, checking the page after each.
- Split
app.jsinto the loop and one function per effect, as in section 02. - Run “Without JavaScript” and fix what it finds.
- Commit each step separately.
Practice · Test it
Check the resultrequestAnimationFrameappears in one place only: the loop.- Switching to another tab and back pauses and resumes the effects.
- With JavaScript disabled, every section is readable.
- The page looks and behaves exactly as before the refactor.
Practice · Assessment
Acceptance criteria0 of 4 criteria met