Fixing GSAP SSR Runtime Error on Astro + Vercel
Engineering Case Study: Fixing GSAP SSR Runtime Error on Astro + Vercel
Author: Muchamad Ghufron Vaqih
Category: Engineering Case Study / Production Troubleshooting
Stack: Astro 7 · React 19 · GSAP · Tailwind CSS · Vercel · Node.js 22
Project Overview
This case study documents a real production incident that occurred after integrating GSAP animations into an Astro SSR portfolio deployed on Vercel.
Although local development and build pipelines completed successfully, the production deployment consistently returned HTTP 500 Internal Server Error.
The objective was not only to restore production availability, but also to identify the true root cause and implement a permanent mitigation.
Architecture
Developer
│
▼
GitHub Repository
│
▼
Vercel Build
│
▼
Astro SSR
│
▼
React Components
│
▼
GSAP Animation
Technology Stack
- Astro 7
- React 19
- GSAP
- Tailwind CSS
- Vercel
- Node.js 22
- Git & GitHub
Initial Symptoms
Local Environment
- ✅
npm run dev - ✅
npm run build
Vercel
- ✅ Deployment finished
- ❌ Website returned HTTP 500
Investigation Timeline
Step 1 --- Verify Local Build
npm run build
Result:
- Build completed successfully.
Step 2 --- Verify Vercel Build
npx vercel build
Result:
- Build completed successfully.
Step 3 --- Inspect Runtime Logs
npx vercel logs <project> --follow
Runtime revealed:
Named export 'ScrollTrigger' not found.
Step 4 --- First Refactor
Updated GSAP imports.
New runtime error appeared:
Cannot use import statement outside a module
This proved the first fix was incomplete.
Step 5 --- Root Cause Analysis
The issue was not:
- Astro
- Vercel
- Environment Variables
- Database
The issue was:
GSAP plugins were imported during Server Side Rendering.
Node.js attempted to evaluate browser-only animation modules before the browser existed.
Why Local Worked
Vite development server transforms modules differently and provides a more permissive development environment.
Production SSR on Vercel executes Node.js directly, making module compatibility much stricter.
Final Mitigation
Instead of importing GSAP plugins at the top of React components:
import gsap from "gsap";
import ScrollTrigger from "gsap/ScrollTrigger";
the animation modules were loaded only in the browser using dynamic imports.
This prevented Node.js from executing browser-only modules during SSR.
Validation
Build
npm run build
✅ Success
Vercel Build
npx vercel build
✅ Success
Production Deployment
npx vercel --prod
✅ Success
Runtime
Website loads correctly.
Animations execute correctly.
HTTP 500 resolved.
Lessons Learned
- Build success does not guarantee runtime success.
- Runtime logs are often more valuable than build logs.
- Browser-only libraries must be SSR compatible.
- Root Cause Analysis is more effective than repeated trial-and-error.
- Production debugging requires systematic elimination of hypotheses.
Skills Demonstrated
- Production Troubleshooting
- Root Cause Analysis
- Astro SSR
- Vercel Deployment
- JavaScript Module Systems
- Dynamic Imports
- GSAP Integration
- Incident Mitigation
- Deployment Validation
Suggested Screenshots
Place screenshots in:
docs/engineering/astro-vercel-gsap-ssr/images/
Recommended filenames:
- 01-http-500.png
- 02-vercel-runtime-log.png
- 03-scrolltrigger-error.png
- 04-import-error.png
- 05-build-success.png
- 06-vercel-build-success.png
- 07-production-success.png
Then reference them:
Conclusion
This incident demonstrated the importance of production-focused debugging. The failure was not caused by the deployment platform itself, but by the interaction between SSR and browser-only animation libraries.
The final solution was to refactor the animation loading strategy so that GSAP executes only in the browser, restoring full production functionality while preserving all animations.