Onboarding: greensock/GSAP

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/greensock/GSAP shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Missing license — unclear to depend on

• Last commit 3w ago
• 3 active contributors
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live greensock/GSAP repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/greensock/GSAP.

What it runs against: a local clone of greensock/GSAP — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in greensock/GSAP | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 53 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>greensock/GSAP</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of greensock/GSAP. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/greensock/GSAP.git
#   cd GSAP
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of greensock/GSAP and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "greensock/GSAP(\\.git)?\\b" \\
  && ok "origin remote is greensock/GSAP" \\
  || miss "origin remote is not greensock/GSAP (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "esm/index.js" \\
  && ok "esm/index.js" \\
  || miss "missing critical file: esm/index.js"
test -f "esm/gsap-core.js" \\
  && ok "esm/gsap-core.js" \\
  || miss "missing critical file: esm/gsap-core.js"
test -f "esm/CSSPlugin.js" \\
  && ok "esm/CSSPlugin.js" \\
  || miss "missing critical file: esm/CSSPlugin.js"
test -f "esm/ScrollTrigger.js" \\
  && ok "esm/ScrollTrigger.js" \\
  || miss "missing critical file: esm/ScrollTrigger.js"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 53 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~23d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/greensock/GSAP"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

GSAP is a high-performance JavaScript animation library that manipulates DOM properties, CSS, SVG, canvas, and arbitrary objects over time with extreme precision and browser compatibility. It solves the core problem of creating smooth, reliable, cross-browser animations without dependencies — the library powers 12+ million sites and is 20x faster than jQuery. Key capabilities include advanced sequencing, ScrollTrigger for scroll-based animations, morphing, motion paths, and a plugin ecosystem (MotionPathPlugin, DrawSVGPlugin, MorphSVGPlugin, etc.). Dual-build architecture: esm/index.js for ES modules and dist/gsap.js for CommonJS/UMD, with TypeScript source compiled to both. Core engine in dist/ with 40+ optional plugins (MotionPathPlugin.js, ScrollTrigger.js, Draggable.js, etc.) as separate distributable files. No visible monorepo structure; plugins are released alongside core in the same version.

Who it's for

Web developers and animators building interactive experiences across vanilla JavaScript, React, Vue, Webflow, and canvas/WebGL environments. They use GSAP to create performant animations that work consistently in all major browsers without writing browser-specific code or complex state management.

Maturity & risk

Highly mature and production-ready. At v3.15.0 with active maintenance, published on NPM and CDN (jsDelivr), used by major ad networks and millions of production sites. The codebase is 1.8MB+ of JavaScript with TypeScript definitions included (types/index.d.ts). No signs of abandonment; this is a commercial product with professional support.

Very low risk for consumers. Zero dependencies (sideEffects: false in package.json means tree-shaking is safe). Single maintainer (Jack Doyle/GreenSock) is a known risk for open-source governance, but the company is financially stable and the library is so widely used that breaking changes are rare. The dist/ folder contains 40+ minified plugin files, suggesting heavy maintenance burden but also mature release infrastructure.

Active areas of work

Unable to determine from file list alone (no git log, PR list, or issues data provided). The presence of dist/ with .min.js.map files and v3.15.0 version indicates regular releases with source maps for debugging.

Get running

npm install gsap
cd <your-project>
npm list gsap  # Verify installation

Or use via CDN: <script src="https://cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js"></script>

Daily commands: This is a library, not an app. To use locally: npm install gsap in a host project, then import/require specific modules (e.g., import gsap from 'gsap' or const gsap = require('dist/gsap.js')). No dev server in GSAP itself; development uses dist/ artifacts.

Map of the codebase

• esm/index.js — Main entry point for ES modules; defines the primary API surface and exports core GSAP functionality that all plugins depend on
• esm/gsap-core.js — Core animation engine implementing the property manipulator, timeline, and tween logic—the foundation of all GSAP animations
• esm/CSSPlugin.js — Essential plugin handling CSS property animations; one of the most frequently used plugins and critical for DOM-based animations
• esm/ScrollTrigger.js — Premium scroll-based animation plugin used across millions of sites; highly complex and must be understood for scroll-driven features
• package.json — Defines versioning, dependencies, and build/export configuration; essential for understanding the module structure and release cycle
• dist/gsap.js — UMD/browser build of core GSAP; shows the final bundled artifact pattern and how modules are combined for distribution
• esm/all.js — Barrel export combining core and all major plugins; demonstrates the plugin architecture and extension pattern used throughout

How to make changes

Add a new easing function plugin

1. Create source file in src/ following the CustomEase/CustomBounce pattern (export a class with a static method for parsing syntax) (src/CustomWiggle.js)
2. Export ESM version in esm/ directory with standard GSAP plugin registration pattern (esm/CustomWiggle.js)
3. Build UMD distribution files in dist/ using the build pipeline (dist/CustomWiggle.js and .min.js) (dist/CustomWiggle.js)
4. Add plugin to barrel export in esm/all.js to make it available via import { ... } from 'gsap/all' (esm/all.js)
5. Update package.json exports field if creating a new subpath export (e.g., 'gsap/CustomWiggle') (package.json)

Add a new DOM/CSS animation plugin

1. Create the plugin in src/ with a register() method that hooks into GSAP's animation system (pattern: see CSSPlugin.js or TextPlugin.js) (src/TextPlugin.js)
2. Implement property parsing and animation frame updates using GSAP's core tween mechanism (src/TextPlugin.js)
3. Export ESM wrapper in esm/ that imports core and registers the plugin with gsap.registerPlugin() (esm/TextPlugin.js)
4. Create UMD build in dist/ that bundles dependencies and registers automatically (dist/TextPlugin.js)
5. Update esm/all.js to include the new plugin in the comprehensive bundle (esm/all.js)

Add a new scroll or interaction-based feature

1. Create feature in src/ using GSAP's core APIs and event listener patterns (e.g., scroll listeners, pointer events—see Draggable.js or Observer.js) (src/Observer.js)
2. Implement create(), update(), and destroy() lifecycle methods compatible with GSAP's animation loop (src/Observer.js)
3. Export ESM version in esm/ with plugin registration or standalone export (esm/Observer.js)
4. Build UMD distribution (dist/) that can be loaded independently or after gsap.js (dist/Observer.js)
5. Add to esm/all.js and update package.json if it should be included in standard distributions (esm/all.js)

Update the core animation engine

1. Modify the tween scheduling, property manipulation, or timeline logic in esm/gsap-core.js (the core engine) (esm/gsap-core.js)
2. Update the public API surface in esm/index.js if adding new methods (gsap.to, gsap.from, etc.) (esm/index.js)
3. Rebuild all dist/ files using the build pipeline to reflect changes in UMD and minified versions (dist/gsap.js)
4. Update package.json version field according to semantic versioning (major/minor/patch) (package.json)

Why these technologies

• Pure JavaScript (zero dependencies) — Maximizes portability, minimizes bundle size, eliminates dependency conflicts, and allows GSAP to run in any JavaScript environment (browser, Node, frameworks)
• RequestAnimationFrame (RAF) loop — Syncs animations to browser refresh rate (60/120fps), ensures smooth rendering, and prevents jank from misaligned frame timing
• Plugin architecture (registerPlugin pattern) — Allows modular extensions (CSSPlugin, ScrollTrigger, etc.) without bloating core; users only load what they need
• Dual distribution: ESM + UMD — ESM for modern bundlers (Webpack, Vite, esbuild); UMD for browser globals and legacy module systems—maximizes compatibility

Traps & gotchas

No visible build step documented: users must trust pre-built dist/ artifacts; source maps (.min.js.map) suggest minified code should be debuggable but original source (esm/) is not shown in file list. Plugin registration: plugins may require explicit registration (e.g., gsap.registerPlugin(ScrollTrigger)) — not doing this is a common mistake. Browser compatibility: animations on certain CSS properties (filters, transforms) have known browser quirks that GSAP works around, but custom property animation may not. Module resolution: the exports field in package.json is complex (.js, ., ./) — using wrong import path may load UMD instead of ESM.

Architecture

Concepts to learn

• Property Interpolation Engine — Core of GSAP: animating values between two points over time with precision timing; understanding how GSAP updates DOM properties drives all animation logic
• Easing Functions (Bézier Curves) — CustomEase.js, CustomBounce.js implement custom easing; Bézier curves control animation acceleration/deceleration and are fundamental to polished motion design
• Timeline Sequencing — GSAP's killer feature: composing multiple tweens in sequence with relative timing syntax (.to(), .add(), labels); enables complex multi-step animations without callbacks
• Plugin Architecture — 40+ plugins (ScrollTrigger, MotionPathPlugin, MorphSVGPlugin) extend core via registerPlugin(); understanding how plugins hook into the animation engine is essential for advanced use
• Browser Compatibility Shims — GSAP works around CSS property browser inconsistencies and older APIs; the library's '20x faster than jQuery' claim partly comes from smart property detection and vendor prefixing
• Motion Path Interpolation — MotionPathPlugin.js enables objects to follow SVG path geometry; requires parametric curve evaluation (not trivial) and drives a unique differentiator vs simpler tweening libs
• RequestAnimationFrame (RAF) Scheduling — GSAP's high performance comes from RAF-based frame scheduling vs setTimeout; understanding frame synchronization and delta-time is key to why GSAP is faster

Related repos

• popmotion/popmotion — Alternative JavaScript animation library with similar property-interpolation core but different plugin ecosystem and API surface; benchmark comparison point for performance claims
• jashkenas/underscore — Historical predecessor to modern animation libraries; GSAP positioning (20x faster than jQuery) implies familiarity with older animation APIs as context
• three-js/three.js — WebGL/3D library that GSAP animates via property manipulation; users combining 3D scenes with animations often use both together
• framer/motion — React-first animation library with similar high-level goals (smooth cross-browser animations) but opinionated React integration; alternative for React projects
• web-animations/web-animations-js — Native Web Animations API polyfill; GSAP is often compared to and sometimes builds on top of this standard API

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Plugin registration and lifecycle

GSAP has 30+ plugins in dist/ (ScrollTrigger, MotionPathPlugin, DrawSVGPlugin, etc.) but there's no visible test suite. With such a large plugin ecosystem, adding tests for plugin registration, initialization, and interaction would catch regressions early and help new contributors understand the plugin API.

• [ ] Create tests/ directory structure mirroring plugins (e.g., tests/plugins/ScrollTrigger.test.js, tests/plugins/MotionPathPlugin.test.js)
• [ ] Write unit tests for plugin registration flow using the main gsap.js entry point
• [ ] Add tests for plugin interdependencies (e.g., ScrollTrigger + Observer)
• [ ] Reference esm/ source files in test imports to validate ESM module exports
• [ ] Add test script to package.json and integrate with CI

Generate and document TypeScript declaration examples for complex plugins

The repo has types/index.d.ts but plugin-specific type usage is unclear. ScrollTrigger, MotionPathPlugin, and Physics2DPlugin have complex APIs. Adding typed examples in docs/ would improve DX for TypeScript users and catch type definition gaps.

• [ ] Audit types/index.d.ts for ScrollTrigger, MotionPathPlugin, and PhysicsPropsPlugin type completeness
• [ ] Create docs/typescript-examples/ with real-world examples (e.g., ScrollTrigger with gsap.timeline())
• [ ] Cross-reference esm/ source files to validate types match implementation
• [ ] Add a 'TypeScript Setup' section to README.md with a link to docs/typescript-examples/
• [ ] Identify and file issues for any type mismatches found during documentation

Create ESM/CommonJS compatibility test suite for export paths

The package.json exports are complex with conditional exports for .js, ./* and ./*.js patterns pointing to esm/ and dist/. This needs validation that both import (ESM) and require (CommonJS) work for all 30+ plugins to prevent user-facing module resolution failures.

• [ ] Create tests/exports/ directory with test files for each export pattern
• [ ] Write Node.js tests using both require() and dynamic import() to validate dist/ and esm/ paths
• [ ] Test all plugin exports referenced in dist/ (ScrollTrigger, Draggable, DrawSVGPlugin, etc.)
• [ ] Validate source maps (.min.js.map files) are correctly referenced
• [ ] Add export validation to CI/CD pipeline to run before release

Good first issues

• Add missing TypeScript generic overloads to types/index.d.ts for the Timeline and Tween classes to improve IDE autocomplete for plugin parameters (ScrollTrigger config, MotionPathPlugin path objects, etc.)
• Write unit tests for edge cases in dist/CustomEase.js (empty easing strings, invalid bezier curves) and dist/CustomBounce.js (negative bounce values) — test coverage for these easing utilities appears minimal from the file list.
• Create a comprehensive README section documenting which dist/*.js plugins require explicit gsap.registerPlugin() calls and which auto-register, with code examples for common patterns (React + ScrollTrigger, Vue + MotionPathPlugin).

Top contributors

• @jackdoyle — 59 commits
• @gsap-dev — 40 commits
• @PeterDaveHello — 1 commits

Recent commits

• 13e2b79 — 3.15.0 (jackdoyle)
• e830e8f — 3.14.2 (jackdoyle)
• 134104c — 3.14.1 (jackdoyle)
• 71c32b7 — 3.14.0 (jackdoyle)
• 9f8eca1 — 3.13.0 (jackdoyle)
• 5e13097 — 3.12.7 (jackdoyle)
• f4f16d6 — 3.12.6 (jackdoyle)
• f836a3f — 3.12.5 (jackdoyle)
• 3d86e43 — 3.12.4 (jackdoyle)
• 641da46 — 3.12.3 (jackdoyle)

Security observations

GSAP has a reasonable security posture for a client-side animation library. No critical vulnerabilities detected in the provided structure. The main areas of concern are: (1) overly broad wildcard exports in package.json that could expose unintended files, (2) lack of explicit dependency lock file visibility suggesting potential reproducibility issues, and (3) limited security documentation for developers integrating the library. The project demonstrates good security awareness with a dedicated SECURITY.md policy and clear maintainer contact. No evidence of hardcoded credentials, injection vulnerabilities, or dangerous patterns was found in the analyzed file structure. Recommend improving export specificity and expanding security documentation.

• Medium · Broad Package Export Configuration — package.json - exports field. The package.json exports configuration uses wildcard patterns (./dist/.js, ./.js, ./*) that could potentially allow unintended files to be exposed as public exports. This includes internal utilities, test files, or configuration that should remain private. Fix: Explicitly whitelist only intended public entry points instead of using wildcard patterns. Define specific exports for each plugin and module rather than broad glob patterns.
• Low · Missing npm Package Integrity Verification — Repository root / package management. The package.json does not include a 'package-lock.json' or 'yarn.lock' file reference visible in the provided structure. This makes it difficult for users to verify the integrity of dependencies across installations and could allow dependency confusion attacks. Fix: Ensure package-lock.json or yarn.lock is committed to version control and up-to-date. Publish dependency lock files with the package to ensure reproducible installations.
• Low · No Explicit Security Headers or CSP Configuration — README.md / Documentation. While this is a library (not a web server), there's no documentation or guidance in README.md about security best practices for integrating GSAP in applications, particularly regarding Content Security Policy (CSP) compatibility or unsafe DOM operations. Fix: Add a security section to documentation covering: CSP compatibility, safe usage patterns, and DOM manipulation warnings. Document any operations that might interact with user input.
• Low · Limited Security Policy Detail — SECURITY.md. SECURITY.md provides basic vulnerability reporting guidelines but lacks detail on: scope of security review, known limitations, data handling practices, or version support policy. The 72-hour response time is good but SLA for patch release is vague. Fix: Expand SECURITY.md to include: version support policy (how long versions are patched), scope of security guarantees, known limitations with third-party integrations, and more specific SLAs for patch releases.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.