Dev.to WebDev 🛠 Dev 👁 0 📖 3 min read

The 4 bugs that break Astro + GSAP + Lenis in production (and how I fixed them)

If you’ve been building creative landing pages with Astro + GSAP + Lenis, you’ve probably noticed a frustrating pattern: most starters look absolutely stunning in the demo, but fall apart the moment you deploy them to pr

If you’ve been building creative landing pages with Astro + GSAP + Lenis, you’ve probably noticed a frustrating pattern: most starters look absolutely stunning in the demo, but fall apart the moment you deploy them to production.

I got tired of losing hours debugging the same issues across multiple client projects. So, I dug into the root causes and fixed the four specific bugs that usually cause this at the configuration level.

Here is the technical breakdown of what breaks, and exactly how to fix it.

Bug 1: Scroll-triggered animations silently never fire

The problem: Lenis replaces native scroll with a virtual one. If GSAP’s ScrollTrigger isn’t explicitly synced to it, it never detects scroll at all. Your animations just… don’t run. No errors, no warnings.

The fix: Initialize Lenis before registering ScrollTrigger, and explicitly sync them using the ticker:

javascript
// lenis.ts
lenis.on('scroll', ScrollTrigger.update);

gsap.ticker.add((time) => {
lenis.raf(time * 1000);
});

gsap.ticker.lagSmoothing(0);

Bug 2: Images "fade in" as blank boxes
The problem: A naive opacity animation fires before the browser finishes decoding the image. The element fades in, but it’s empty. This looks broken, especially on slower connections.
The fix: Gate the animation behind an image load check. I built a reusable image-load-gate helper in src/animations/utils/ that ensures the browser has decoded the image before GSAP touches the opacity.

Bug 3: Buttons stop working with no visible cause
The problem: Two things collide here. First, z-index conflicts from animated layers silently eat clicks. Second, React islands (if you're using Astro's partial hydration) might have click listeners that haven't attached yet due to hydration race conditions.

The fix:
Define a strict z-index scale in CSS custom properties (no magic numbers) inside tokens.css.

Add a hydration-ready check before attaching interaction listeners to the React island.

(Pro tip: I wrote a specific Playwright test for this hydration-race condition, and it actually caught a real regression during the kit's own development. Treat your failing tests as real signals!)

Bug 4: SEO/Lighthouse scores that don't hold up

The problem: Creative starters often ship with incomplete , broken heading hierarchy, images without alt, and no sitemap. Your Lighthouse scores tank in production.

The fix: Build the as a reusable Astro component (src/layouts/Layout.astro) with proper canonical links, og:image, and a sitemap. Enforce heading hierarchy directly in the base layout.

Why I built the "Landing Premium Kit"
I know that copying, pasting, and adapting these fixes for every single project gets tedious fast.

That’s why I packaged this exact setup into a production-ready Astro Starter Kit (built with TypeScript and Tailwind v4). It’s not a course, and it’s not a "masterclass". It’s the actual code, engineered around one idea: it doesn't break in production.
What's inside:

All 4 bugs fixed at the configuration level.
14 Playwright tests (covering all four bugs plus responsive layout checks).

A live demo you can test right now: https://landing-premium-kit.vercel.app/

Lighthouse Scores (Mobile): Performance 85 · Accessibility 96 · Best Practices 100 · SEO 100.
Full documentation on architecture, customization, and deployment.

I put it on Gumroad for $69 (or $99 with 14 days of email support) just in case it saves you the hours of debugging it took me to figure this out.

👉 Get the Landing Premium Kit here:https://keymelgaston.gumroad.com/l/inkukz:

The most common false alarm
Before reaching out about "the animations aren't working" after installing, check one thing first. Run this in your browser console:

matchMedia('(prefers-reduced-motion: reduce)').matches

If it returns true, the kit is working perfectly — it's just respecting your operating system's reduced-motion setting, which disables all animation on purpose.

Toggle it off in your OS accessibility settings to see the motion.

If you have any questions about the configuration, the folder structure, or the architecture, drop them in the comments below. Happy to help!

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.