gsap-nextjs
Build or review Next.js App Router animation: GSAP page transitions, component enter/exit, scroll effects, interrupted motion, and cleanup. Use even when GSAP is unnamed, including choosing React View Transitions. Also covers loading flashes, data-ready entrances, layout stability, hidden-content recovery, and first-load performance. Not for Pages Router, other routers, or isolated GSAP API questions.
How do I install this agent skill?
npx skills add https://github.com/johnpolacek/animaxxing-skills --skill gsap-nextjsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides comprehensive and safe instructions for integrating GSAP animations within Next.js App Router applications, adhering to architectural and performance best practices.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
GSAP Next.js
mount → initial state → intro → settled → outro → end state → unmount
Mount and unmount belong to React; animation owns the five phases between them. With cacheComponents, treat route hide as unmount and re-show as mount on preserved DOM.
Keep the requested look and existing project conventions. Add GSAP/plugins only as needed; do not replace the chosen animation library unless asked.
This skill decides when motion runs. For what moves, and for a feel such as premium or playful, also load the animaxxing skill when it is installed: its recipes and its guide to finding the vibe plug into this lifecycle.
Start with the project
Read repository instructions, existing animation, layouts, navigation, CSS, accessibility conventions, and checks. Then:
- Confirm the App Router. If the project uses the Pages Router, use version-matched Pages Router guidance instead of this skill.
- Read the installed Next.js version. Prefer its bundled docs in
node_modules/next/dist/docs/over memory. Version gates:onNavigateanduseLinkStatus(15.3),<ViewTransition>andtransitionTypes(16.2),<Activity>route preservation whencacheComponentsis enabled (16.0, opt-in). - Check the Next config for
cacheComponents. It changes how long routes live.
Choose the engine
Use React <ViewTransition> for shared-element morphs, page crossfades, and Suspense swaps when supported by the installed Next.js version. Use GSAP for live-DOM outros that gate navigation, interruptible sequences, split text, or scroll-linked motion. One engine per element; see combining engines.
Read only what you need
- Invisible entrances, failed initialization, indexing, and first-load performance: Initialization and recovery, plus the framework integration.
- Loading/auth flashes and shifting async sections: Data readiness, plus React data integration.
- Page intros and outros, transition-aware links, back and forward, focus, route swaps: App Router navigation.
- The five phases, GSAP setup, React lifecycle, show and hide, layout stability, scroll, text, plugins: Lifecycle implementation.
- Lenis, ScrollSmoother, or eased page scrolling across routes: Smooth scrolling, plus the App Router integration.
- Curtains, first-visit preloaders, and shared-element morphs: Transition archetypes, plus where they live in the App Router.
- Touch, viewport changes, and device budgets: Devices and input.
- Tauri, Electron, or Wails desktop shells: Desktop webviews.
- Before calling work done: Verification.
Install the official GSAP skills alongside this repository. Load gsap-core for API details and gsap-react for component setup only as needed.
Rules
- Preserve invisible intros on successful setup; recover the current incoming owner on failure. Follow the initialization contract before adding hiding rules.
- GSAP runs only on the client. Scope selectors. Clean up every tween, trigger, split, and listener.
- Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space.
- Reveal each owner when its structural data is ready; unresolved auth or queries must not masquerade as guest or empty content.
- Mount, then set initial values, then paint. Successful initialization never flashes settled content before the intro.
- Clear temporary styles at settled. Use
will-changeonly while animating; this overridesgsap-performance's static hint. - Use capability queries for device tiers. Touch states release; controls work without hover.
- Keep outgoing pages and components mounted and visible through outro and end state. Unmount, or let the router hide, only after the end callback.
- Under
cacheComponents, a page lifecycle runs again on re-show against DOM that already holds settled values. Never assume a fresh node. - Back and forward never run an outro. Give them an intro-only path.
- Keep native link behavior, focus, scroll, and no-JavaScript readability.
- Reduced motion reaches the same settled state and still fires every completion callback.
- Define interruption and rapid-click behavior; completion must release navigation waits exactly once.
- Verify in a real browser when practical. Use a production build for route, config, dependency, or release changes.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/johnpolacek/animaxxing-skills/gsap-nextjs">View gsap-nextjs on skillZs</a>