gsap-performance

GSAP 성능 최적화 공식 스킬 — 변형(transform) 우선, 레이아웃 쓰레싱 방지, will-change, 배칭. GSAP 애니메이션 최적화, 버벅임 감소, 또는 사용자가 애니메이션 성능, FPS, 부드러운 60fps에 대해 물을 때 사용합니다.

gsap-performance란 무엇인가요?

이 스킬은 GSAP 애니메이션을 부드러운 60fps로 유지하기 위해 레이아웃/페인트 비용을 줄이는 방법을 제공합니다. 변형(transform)과 불투명도(opacity)를 우선 사용하고, 레이아웃을 유발하는 속성(width, height, top, left 등)은 피하도록 안내합니다. 또한 will-change CSS 힌트 사용, 읽기/쓰기 배칭, 많은 요소 처리 시 stagger 활용, 자주 업데이트되는 속성에 gsap.quickTo() 사용 등 구체적인 최적화 기법을 제시합니다. ScrollTrigger 성능 관련 조언(pin 최소화, scrub 값 조정, refresh 호출 최적화)과 화면 밖 애니메이션 정리 등 모범 사례를 종합적으로 다룹니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 어시스턴트에서 GSAP 성능 관련 질문이나 코드 최적화 요청 시 활성화됩니다.

지원 대상~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/greensock/gsap-skills/tree/main/skills/gsap-performance

문서

GSAP 성능

이 스킬을 사용해야 할 때

GSAP 애니메이션을 부드러운 60fps로 최적화하거나, 레이아웃/페인트 비용을 줄일 때, 또는 사용자가 성능, 버벅임, 빠른 애니메이션을 위한 모범 사례에 대해 물을 때 적용하세요.

관련 스킬: gsap-core (transforms, autoAlpha)와 gsap-timeline으로 애니메이션 제작; ScrollTrigger 성능은 gsap-scrolltrigger 참고.

Transform과 Opacity 우선

transform (x, y, scaleX, scaleY, rotation, rotationX, rotationY, skewX, skewY) 및 opacity 애니메이션은 합성기(compositor)에서 처리되어 레이아웃과 대부분의 페인트를 피합니다. transform으로 동일한 효과를 낼 수 있다면 레이아웃 비용이 큰 속성은 애니메이션하지 마세요.

✅ 권장: x, y, scale, rotation, opacity.
❌ 가능하면 피할 것: width, height, top, left, margin, padding (레이아웃을 유발하여 버벅임을 일으킬 수 있음).

GSAP의 x와 y는 기본적으로 transform(translate)을 사용하므로 움직임에 left/top 대신 사용하세요.

will-change

애니메이션할 요소에 CSS로 will-change를 사용하세요. 브라우저에 레이어를 승격하도록 힌트를 줍니다.

will-change: transform;

읽기와 쓰기 배칭

GSAP은 내부적으로 업데이트를 배칭합니다. GSAP을 직접 DOM 읽기/쓰기나 레이아웃 종속 코드와 혼합할 때는 읽기와 쓰기를 번갈아 수행하여 반복적인 레이아웃 쓰레싱을 유발하지 않도록 주의하세요. 모든 읽기를 먼저 수행한 후 모든 쓰기를 수행하거나(또는 GSAP이 쓰기를 한 번에 처리하도록 두세요).

많은 요소 (Stagger, 리스트)

동일한 애니메이션의 경우 수동 지연이 있는 여러 개별 트윈 대신 stagger를 사용하세요. 더 효율적입니다.
긴 리스트의 경우 가상화(virtualization) 또는 보이는 항목만 애니메이션하는 것을 고려하세요. 버벅임을 유발할 수 있으므로 수백 개의 동시 트윈을 생성하지 마세요.
가능하면 타임라인을 재사용하고, 매 프레임마다 새 타임라인을 만들지 마세요.

자주 업데이트되는 속성 (예: 마우스 따라다니기)

자주 업데이트되는 속성(예: 마우스 따라다니기의 x/y)에는 gsap.quickTo() 를 사용하세요. 업데이트할 때마다 새 트윈을 생성하는 대신 단일 트윈을 재사용합니다.

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
    yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });

document.querySelector("#container").addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

ScrollTrigger와 성능

pin: true는 고정된 요소를 승격합니다. 필요한 부분만 pin하세요.
scrub을 작은 값(예: scrub: 1)으로 설정하면 스크롤 중 작업량을 줄일 수 있습니다. 저사양 기기에서 테스트하세요.
ScrollTrigger.refresh() 는 레이아웃이 실제로 변경될 때만 호출하고(예: 콘텐츠 로드 후), 모든 리사이즈마다 호출하지 마세요. 가능하면 디바운스하세요.

동시 작업 줄이기

화면 밖이거나 비활성화된 애니메이션은 사용자가 다른 곳으로 이동할 때 일시 중지하거나 제거하세요.
한 번에 많은 요소의 많은 속성을 애니메이션하지 마세요. 필요한 경우 단순화하거나 순차적으로 처리하세요.

모범 사례

✅ transform과 opacity를 애니메이션하고, 애니메이션하는 요소에만 CSS will-change를 사용하세요.
✅ 동일한 애니메이션의 경우 수동 지연이 있는 여러 개별 트윈 대신 stagger를 사용하세요.
✅ 자주 업데이트되는 속성(예: 마우스 따라다니기)에는 gsap.quickTo() 를 사용하세요.
✅ 화면 밖 애니메이션을 정리하거나 제거하고, 레이아웃이 변경될 때 ScrollTrigger.refresh() 를 호출하되 가능하면 디바운스하세요.

하지 말아야 할 것

❌ x/y/scale로 동일한 모양을 낼 수 있는데 width/height/top/left를 애니메이션하지 마세요.
❌ "만약을 대비해" 모든 요소에 will-change나 force3D를 설정하지 마세요. 실제로 애니메이션하는 요소에만 사용하세요.
❌ 저사양 기기에서 테스트하지 않고 수백 개의 중첩 트윈이나 ScrollTrigger를 생성하지 마세요.
❌ 정리를 무시하지 마세요. 방치된 트윈과 ScrollTrigger는 계속 실행되어 성능과 정확성을 해칠 수 있습니다.

gsap-performance