Imported from Wayn-Git/vault (agents/skills/gsap-setup/SKILL.md). Install upstream with npx skills add Wayn-Git/vault --skill gsap-setup. Copyright stays with the author.

GSAP Setup and Best Practices

Proper GSAP setup ensures smooth development, optimal performance, and maintainable code. Learn installation, plugin registration, configuration, and industry best practices.

Installation

NPM Installation

# Core GSAP
npm install gsap

# React integration
npm install @gsap/react

# All plugins are included in gsap package
# No separate installation needed

CDN Installation

<!-- GSAP Core -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/gsap.min.js"></script>

<!-- ScrollTrigger -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/ScrollTrigger.min.js"></script>

<!-- Other plugins as needed -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/Draggable.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3.13.0/dist/Flip.min.js"></script>

ES Modules (CDN)

<script type="module">
  import gsap from 'https://cdn.jsdelivr.net/npm/gsap@3.13.0/index.js'
  import { ScrollTrigger } from 'https://cdn.jsdelivr.net/npm/gsap@3.13.0/ScrollTrigger.js'

  gsap.registerPlugin(ScrollTrigger)
</script>

Project Setup

Basic Setup

// gsap.js - Central GSAP configuration
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import { Draggable } from 'gsap/Draggable'

// Register all plugins once
gsap.registerPlugin(ScrollTrigger, Draggable)

// Set global defaults
gsap.defaults({
  ease: 'power2.out',
  duration: 1
})

// Configure ScrollTrigger
ScrollTrigger.config({
  ignoreMobileResize: true,
  autoRefreshEvents: 'visibilitychange,DOMContentLoaded,load'
})

export { gsap }

Advanced Setup

// gsap.js
import gsap from 'gsap'

// Plugins (all shipped in the public `gsap` npm package; some were formerly members-only)
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import { Observer } from 'gsap/Observer'
import { Draggable } from 'gsap/Draggable'
import { Flip } from 'gsap/Flip'
import { ScrollToPlugin } from 'gsap/ScrollToPlugin'

// Formerly members-only / bonus plugins
import { SplitText } from 'gsap/SplitText'
import { MorphSVGPlugin } from 'gsap/MorphSVGPlugin'
import { MotionPathPlugin } from 'gsap/MotionPathPlugin'
import { DrawSVGPlugin } from 'gsap/DrawSVGPlugin'
import { ScrambleTextPlugin } from 'gsap/ScrambleTextPlugin'
import { CustomEase } from 'gsap/CustomEase'
import { MotionPathHelper } from 'gsap/MotionPathHelper'

// Register all plugins
gsap.registerPlugin(
  ScrollTrigger,
  Observer,
  Draggable,
  Flip,
  ScrollToPlugin,
  SplitText,
  MorphSVGPlugin,
  MotionPathPlugin,
  DrawSVGPlugin,
  ScrambleTextPlugin,
  CustomEase,
  MotionPathHelper
)

// Global configuration
gsap.defaults({
  ease: 'power2.out',
  duration: 1,
  overwrite: 'auto'
})

// Ticker configuration
gsap.ticker.lagSmoothing(1000, 16)

// Custom ease definitions
CustomEase.create('smooth', 'M0,0 C0.5,0 0.5,1 1,1')

// Export configured gsap instance
export default gsap

Plugin Registration

Register Plugins

import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
import { Draggable } from 'gsap/Draggable'

// Register all plugins at once
gsap.registerPlugin(ScrollTrigger, Draggable)

// Or register individually
gsap.registerPlugin(ScrollTrigger)
gsap.registerPlugin(Draggable)

Register with React Hook

import gsap from 'gsap'
import { useGSAP } from '@gsap/react'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

// Register hook and plugins
gsap.registerPlugin(useGSAP, ScrollTrigger)

Conditional Registration

import gsap from 'gsap'

// Only register needed plugins
const useScrollTrigger = true
const useDraggable = false

if (useScrollTrigger) {
  import('gsap/ScrollTrigger').then(({ ScrollTrigger }) => {
    gsap.registerPlugin(ScrollTrigger)
  })
}

if (useDraggable) {
  import('gsap/Draggable').then(({ Draggable }) => {
    gsap.registerPlugin(Draggable)
  })
}

Global Configuration

Defaults

// Set global defaults
gsap.defaults({
  ease: 'power2.out',
  duration: 1,
  delay: 0,
  overwrite: 'auto',
  lazy: true
})

// Override defaults in individual tweens
gsap.to('.box', {
  x: 200,
  duration: 2,  // Overrides default
  ease: 'back.out(1.7)'  // Overrides default
})

Timeline Defaults

const tl = gsap.timeline({
  defaults: {
    ease: 'power2.out',
    duration: 1
  },
  paused: true,
  repeat: -1,
  yoyo: true
})

// All tweens in timeline inherit defaults
tl.to('.box1', { x: 100 })  // Uses defaults
  .to('.box2', { x: 200, ease: 'back.out' })  // Overrides ease

ScrollTrigger Config

ScrollTrigger.config({
  // Ignore mobile resize events (improves performance)
  ignoreMobileResize: true,

  // Custom auto-refresh events
  autoRefreshEvents: 'visibilitychange,DOMContentLoaded,load',

  // Default markers (development only)
  defaultMarkers: false,

  // Normalize scroll
  normalizeScroll: true
})

Development Setup

Development Configuration

// gsap.dev.js
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

// Enable markers in development
if (process.env.NODE_ENV === 'development') {
  ScrollTrigger.config({
    defaultMarkers: true
  })

  // Log all tweens
  gsap.registerEffect({
    name: 'debugTween',
    effect: (targets, config) => {
      return gsap.to(targets, config)
    },
    extendTimeline: true
  })
}

export { gsap }

Production Configuration

// gsap.prod.js
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)

// Production optimizations
ScrollTrigger.config({
  ignoreMobileResize: true,
  autoRefreshEvents: 'visibilitychange,DOMContentLoaded,load'
})

// Disable markers
ScrollTrigger.config({
  defaultMarkers: false
})

export { gsap }

Project Structure

Feature-Based Structure

src/
├── gsap/
│   ├── gsap.js           # Central configuration
│   ├── animations.js     # Reusable animations
│   └── constants.js      # Eases, durations, etc.
├── components/
│   ├── Hero/
│   │   ├── Hero.jsx
│   │   └── heroAnimations.js
│   └── About/
│       ├── About.jsx
│       └── aboutAnimations.js

Animation Modules

// gsap/animations.js
import { gsap } from './gsap'

// Reusable entrance animation
export const entranceAnimation = (elements, options = {}) => {
  return gsap.from(elements, {
    opacity: 0,
    y: 30,
    stagger: 0.1,
    duration: 0.8,
    ease: 'power2.out',
    ...options
  })
}

// Reusable hover animation
export const hoverAnimation = (element, options = {}) => {
  const tl = gsap.timeline({ paused: true })

  tl.to(element, {
      scale: 1.1,
      duration: 0.3,
      ease: 'power2.out'
    })
    .to(element, {
      scale: 1,
      duration: 0.3,
      ease: 'power2.out'
    }, '+=0.5')

  return tl
}

Environment Configuration

Development vs Production

// gsap/config.js
const isDevelopment = process.env.NODE_ENV === 'development'

export const config = {
  // Enable debug tools in development
  debug: isDevelopment,

  // Performance optimizations
  performance: !isDevelopment,

  // Animation speed multiplier (for testing)
  speedMultiplier: isDevelopment ? 0.5 : 1,

  // Easing presets
  eases: {
    ui: 'power2.out',
    entrance: 'back.out(1.7)',
    exit: 'power2.in',
    playful: 'elastic.out(1, 0.3)'
  },

  // Duration presets
  durations: {
    fast: 0.3,
    normal: 0.8,
    slow: 1.5
  }
}

export default config

Best Practices

1. Register Plugins Once

// ✅ Register all plugins in one place
gsap.registerPlugin(ScrollTrigger, Draggable, Flip)

// ❌ Don't register multiple times
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)  // In one file

import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)  // In another file - redundant!

2. Use Named Exports

// ✅ Use named exports for tree-shaking
import { gsap } from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

// ❌ Avoid default imports when possible
import gsap from 'gsap'  // Can't be tree-shaken as effectively

3. Centralize Configuration

// ✅ Central GSAP configuration
// gsap.js
import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'

gsap.registerPlugin(ScrollTrigger)
gsap.defaults({ ease: 'power2.out', duration: 1 })

export default gsap

// Import configured gsap
import gsap from './gsap'

// ❌ Scattered configuration
import gsap from 'gsap'
gsap.defaults({ ease: 'power2.out' })  // In one file

import gsap from 'gsap'
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)  // In another file

4. Set Global Defaults

// ✅ Use defaults for consistency
gsap.defaults({
  ease: 'power2.out',
  duration: 1
})

// All tweens inherit these defaults
gsap.to('.box', { x: 200 })
gsap.from('.modal', { opacity: 0 })

// ❌ Repeating values
gsap.to('.box', { x: 200, ease: 'power2.out', duration: 1 })
gsap.from('.modal', { opacity: 0, ease: 'power2.out', duration: 1 })

5. Use Timelines for Sequences

// ✅ Use timeline for sequences
const tl = gsap.timeline()
tl.to('.box1', { x: 100 })
  .to('.box2', { x: 100 })
  .to('.box3', { x: 100 })

// Easy to control
tl.play()
tl.reverse()
tl.kill()

// ❌ Separate tweens
gsap.to('.box1', { x: 100, delay: 0 })
gsap.to('.box2', { x: 100, delay: 1 })
gsap.to('.box3', { x: 100, delay: 2 })

6. Clean Up Animations

// ✅ Clean up when component unmounts
function MyComponent() {
  useGSAP(() => {
    const tl = gsap.timeline()
    tl.to('.box', { x: 200 })

    // Automatically cleaned up
  })

  return <div className="box"></div>
}

// ❌ Memory leaks
function MyComponent() {
  useEffect(() => {
    const tl = gsap.timeline()
    tl.to('.box', { x: 200 })
    // Never cleaned up!
  }, [])

  return <div className="box"></div>
}

7. Test on Low-End Devices

// ✅ Performance considerations
gsap.to('.many-boxes', {
  x: 100,
  duration: 1,
  ease: 'power2.out',  // Simpler ease, better performance
  stagger: 0.05,           // Distribute load
  onComplete: () => {
    // Clean up when done
    gsap.killTweensOf('.many-boxes')
  }
})

// ❌ Too complex for low-end devices
gsap.to('.many-boxes', {
  x: 100,
  duration: 1,
  ease: 'elastic.out(1, 0.3)',  // Complex, slow
  stagger: 0.01  // Too many tweens
})

8. Use Appropriate Eases

// ✅ Match ease to use case
gsap.from('.modal', {
  opacity: 0,
  scale: 0.8,
  ease: 'back.out(1.7)',  // Attention-grabbing entrance
  duration: 0.5
})

// ❌ Wrong ease for context
gsap.from('.modal', {
  opacity: 0,
  scale: 0.8,
  ease: 'elastic.out(1, 0.3)',  // Too much for modal
  duration: 0.5
})

9. Implement Responsive Animations

// ✅ Responsive with matchMedia
const mm = gsap.matchMedia()

mm.add('(min-width: 768px)', () => {
  gsap.to('.box', { x: 200, duration: 1 })
})

mm.add('(max-width: 767px)', () => {
  gsap.to('.box', { x: 100, duration: 1 })
})

// ❌ Not responsive
gsap.to('.box', { x: 200, duration: 1 })  // Same for all screens

10. Use Selectors Wisely

// ✅ Scoped selectors
const q = gsap.utils.selector('.container')
gsap.to(q('.box'), { x: 200 })

// Or in React
useGSAP(() => {
  gsap.to('.box', { x: 200 })
}, { scope: container })

// ❌ Global selectors
gsap.to('.box', { x: 200 })  // Affects ALL .box elements

Common Mistakes

1. Not Registering Plugins

// ❌ Plugin won't work
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.to('.box', {
  scrollTrigger: { trigger: '.box' }
})

// ✅ Register plugin first
import { ScrollTrigger } from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)
gsap.to('.box', {
  scrollTrigger: { trigger: '.box' }
})

2. Using Wrong Import Style

// ❌ Can't be tree-shaken
import gsap from 'gsap'

// ✅ Use named imports
import { gsap } from 'gsap'

3. Conflicting Tweens

// ❌ Two tweens fighting
gsap.to('.box', { x: 100, duration: 2 })
gsap.to('.box', { x: 200, duration: 1 })

// ✅ Use overwrite or kill first
gsap.to('.box', { x: 100, duration: 2, overwrite: true })
// Or
gsap.killTweensOf('.box', 'x')
gsap.to('.box', { x: 200, duration: 1 })

4. Forgetting Cleanup

// ❌ Memory leaks
useEffect(() => {
  gsap.to('.box', { x: 200 })
}, [])

// ✅ Use useGSAP in React
useGSAP(() => {
  gsap.to('.box', { x: 200 })
}, { scope: container })

5. Not Testing Performance

// ❌ Works on dev machine, slow on others
gsap.to('.many-complex-elements', {
  filter: 'blur(10px)',
  duration: 1
})

// ✅ Test and optimize
gsap.to('.many-complex-elements', {
  opacity: 0.8,  // Simpler property
  duration: 1
})

Performance Checklist

• Register plugins once at app entry
• Use named exports for tree-shaking
• Set global defaults for consistency
• Use timelines for sequences
• Clean up animations when done
• Test on low-end devices
• Use appropriate eases
• Implement responsive animations
• Scope selectors to prevent conflicts
• Use transform properties over layout properties
• Stagger animations to distribute load
• Avoid filters on many elements
• Kill tweens before creating new ones
• Use ScrollTrigger toggleActions over scrub when possible
• Refresh ScrollTrigger after DOM changes

Quick Reference