Scrollcraft
Chapter 11 of 15RO

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.

Chapter 11 of 154 min read

What you will learn

By the end of this chapter
  1. 01Choose a stack by the problem: plain files, GSAP, Next.js or a backend.
  2. 02Organise files so content, sections, motion and the loop each live in one place.
  3. 03Run every effect from one animation loop that stops when the tab is hidden.
  4. 04Make the page work in full without JavaScript, and clean up every effect in React.

01 · Choosing a stack

Plain, GSAP, Next.js, Flask

For a scroll site the stack matters less than the discipline. Start plain. Add a library when a specific problem asks for it.

OptionUse it whenCost
Plain HTML, CSS, JSOne page or a few pages, a portfolio, a landing page, this tutorial’s projectYou manage the file structure and repeated markup yourself
Vanilla plus GSAPMany scrubbed or pinned timelines that must stay in syncOne more library to load and learn
Next.js with ReactMany routes, shared components, a CMS, server rendering for searchA build step, a server or host that supports it, and effects that must clean up on unmount
FlaskYou need a backend: a contact form, a database, an APIIt does not animate anything. It serves the page and handles data

02 · Folder structure

Plain and Next.js
a

Split 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.

Structure
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, fonts
b

Keep 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

requestAnimationFrame
a

Why 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
// 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);
});
b

Lenis and GSAP share it

If the site uses GSAP, its ticker is the loop: drive Lenis from gsap.ticker as shown in the GSAP chapter, and add your own effects to the same ticker.

04 · Next.js and React

Same effects, with cleanup

In 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.

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 · Progressive enhancement

Works without the effects
a

Content 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.

index.html
<!-- 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>
b

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.

c

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 tool

Refactoring 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

Prompt
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

Prompt
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 compare
1

Pick 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.

2

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.

3

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 course

Make the site for [subject] easy to change: one loop, clear files, and content that survives without scripts.

  1. Run “One loop” and move the effects one at a time, checking the page after each.
  2. Split app.js into the loop and one function per effect, as in section 02.
  3. Run “Without JavaScript” and fix what it finds.
  4. Commit each step separately.

Practice · Test it

Check the result
  • requestAnimationFrame appears 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 criteria

0 of 4 criteria met

Next Performance

Core Web Vitals, a budget for images, video and fonts, the rules that keep scrolling smooth, and how to measure.

Keyboard shortcuts: [ previous chapter · ] next chapter