Orquestación de GSAP Context y Lenis en Vue 3 para transiciones fluidas sin memory leaks
Un análisis técnico sobre cómo integrar el scroll suave de Lenis con el ciclo de vida de Vue 3 y GSAP ScrollTrigger, evitando pérdidas de memoria y desincronizaciones del DOM al navegar.
Cuando encaré la maquetación y el desarrollo frontend de La Rúcula Gastrobar, el objetivo estuvo claro desde el primer día: la experiencia visual y la fluidez del scroll tenían que estar a la altura de la identidad gastronómica del lugar. La Rúcula es un sitio web editorial enfocado en el menú para un restaurante en Chiclana, donde las imágenes, los textos descriptivos de las entradas y las transiciones entre secciones tienen un peso estético fundamental. Para lograr esa marcha uniforme utilicé un stack compuesto por Vue 3, Vite, Tailwind CSS, GSAP con ScrollTrigger y Lenis para el scroll suave.
Sin embargo, trasladar animaciones complejas basadas en el desplazamiento vertical a una Single Page Application (SPA) presenta problemas arquitectónicos de ciclo de vida que no existen en un sitio web estático tradicional. Si no se gestiona con precisión el desmonte de componentes, los disparadores de scroll y el motor de interpolación, la aplicación empieza a acumular fugas de memoria, saltos de layout (layout shifts) y referencias nulas en el DOM a medida que la persona navega por las distintas rutas.
El problema del ciclo de vida en aplicaciones animadas
En una aplicación desarrollada en Vue 3 con Vue Router, las vistas y componentes se montan y se destruyen dinámicamente según la interacción del usuario. Cuando creamos animaciones con GSAP acopladas a la posición del scroll mediante el plugin ScrollTrigger, la librería calcula las coordenadas iniciales y finales de los elementos HTML e inyecta escuchadores de eventos (event listeners) globales en la ventana del navegador.
Si el usuario pasa de la vista del menú a otra sección sin que limpiemos explícitamente esos disparadores, ocurre un problema grave: los listeners de ScrollTrigger se mantienen vivos en memoria haciendo referencia a nodos del DOM que Vue ya eliminó del árbol virtual. Esto provoca varios fallos en cadena:
- Se generan fugas de memoria (memory leaks) que degradan progresivamente el rendimiento del cliente tras recorrer varias páginas.
- ScrollTrigger intenta recalcular las posiciones sobre elementos cuya altura y posición en pantalla pasaron a ser cero.
- El motor de animación dispara advertencias y errores en la consola al intentar manipular propiedades de elementos inexistentes.
A esto hay que sumarle la presencia de Lenis. Lenis sustituye la mecánica del scroll nativo por una interpolación matemática inercial controlada mediante su propio bucle de renderizado (requestAnimationFrame). Si Vue Router cambia la ruta activa mientras Lenis mantiene una velocidad de desplazamiento residual, la nueva página arranca en una posición de scroll arbitraria, desalineando cualquier cálculo geográfico hecho por GSAP durante el montaje del nuevo componente.
GSAP Context como mecanismo de contención en la Composition API
Para resolver la persistencia errónea de animaciones en el ciclo de vida de Vue 3, la solución estructural es empaquetar toda creación de timelines y ScrollTriggers dentro de la API gsap.context(). Esta función actúa como un contenedor de alcance (scope) que registra de forma automática cualquier animación, instancia o disparador generado en su interior.
La ventaja central de gsap.context() dentro de la Composition API es su integrabilidad con el hook onUnmounted. Al destruir el componente de la vista, se invoca el método .revert() del contexto. Esto no solo detiene los timelines activos, sino que remueve completamente los ScrollTriggers asociados y limpia cualquier estilo CSS en línea que GSAP haya escrito directamente sobre el DOM.
En el menú de La Rúcula Gastrobar implementé este patrón en las secciones clave para garantizar un ciclo de vida limpio:
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
import gsap from 'gsap'
import ScrollTrigger from 'gsap/ScrollTrigger'
gsap.registerPlugin(ScrollTrigger)
const menuContainer = ref(null)
let ctx
onMounted(() => {
ctx = gsap.context((self) => {
const items = self.selector('.menu-item')
items.forEach((item) => {
gsap.from(item, {
y: 40,
opacity: 0,
duration: 0.8,
ease: 'power2.out',
scrollTrigger: {
trigger: item,
start: 'top 85%',
toggleActions: 'play none none reverse'
}
})
})
}, menuContainer.value)
})
onUnmounted(() => {
if (ctx) {
ctx.revert()
}
})
</script>
<template>
<main ref="menuContainer" class="menu-wrapper min-h-screen bg-neutral-900 text-neutral-100 p-8">
<section class="max-w-4xl mx-auto space-y-12">
<article class="menu-item border-b border-neutral-800 pb-6">
<h2 class="text-2xl font-serif">Platos Entrantes</h2>
<p class="text-neutral-400 mt-2">Selección fresca de estación con productos locales.</p>
</article>
<article class="menu-item border-b border-neutral-800 pb-6">
<h2 class="text-2xl font-serif">Pescados y Mariscos</h2>
<p class="text-neutral-400 mt-2">Capturas del día preparadas a la plancha con aceite de oliva.</p>
</article>
</section>
</main>
</template>Pasarle menuContainer.value como segundo argumento a gsap.context() es crucial. De esta manera aislamos el selector CSS .menu-item al ámbito exclusivo del nodo raíz del componente. Si existen otros elementos con el mismo nombre de clase en el pie de página o en componentes hermanos, GSAP los pasa por alto sin intervenir sobre ellos.
Sincronización entre Lenis y ScrollTrigger sin saltos de cuadro
Una vez garantizada la limpieza individual de las vistas, el siguiente desafío técnico es sincronizar el bucle de renderizado de Lenis con el reloj interno de GSAP. Por defecto, GSAP actualiza sus animaciones a través de su propio ticker. Si Lenis corre su bucle de scroll de forma independiente, ambos motores terminan compitiendo por actualizar el DOM en momentos ligeramente desfasados del renderizado del navegador, lo que genera micro-tirones visibiles (stuttering).
Para coordinarlos de forma estricta, configuré una instancia global de Lenis cuyo paso de renderizado es impulsado directamente por el ticker de GSAP, conectando además el evento de desplazamiento de Lenis a la actualización de posiciones de ScrollTrigger:
import { onMounted, onUnmounted } from 'vue'
import Lenis from 'lenis'
import gsap from 'gsap'
import ScrollTrigger from 'gsap/ScrollTrigger'
export function useSmoothScroll() {
let lenis: Lenis | null = null
onMounted(() => {
lenis = new Lenis({
duration: 1.2,
easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
smoothWheel: true
})
lenis.on('scroll', ScrollTrigger.update)
const updateFn = (time: number) => {
lenis?.raf(time * 1000)
}
gsap.ticker.add(updateFn)
gsap.ticker.lagSmoothing(0)
})
onUnmounted(() => {
if (lenis) {
lenis.destroy()
gsap.ticker.remove(lenis.raf)
}
})
return {
lenis
}
}La llamada a gsap.ticker.lagSmoothing(0) cumple un papel fundamental. GSAP incluye por defecto un mecanismo de suavizado por desfase que ralentiza las animaciones si detecta una caída de cuadros por segundo para mantener la coherencia temporal. En animaciones atadas al movimiento físico de la rueda del ratón a través de Lenis, ese ajuste automático entra en conflicto directo con la aceleración inercial. Desactivar el lagSmoothing elimina esa latencia agregada y unifica el ritmo de cálculo.
Gestión de coordenadas en transiciones de Vue Router
El último eslabón de esta arquitectura se presenta al navegar entre vistas. Cuando el usuario hace clic en una ruta diferente mientras se encuentra en la parte inferior de la página, Vue Router actualiza el árbol de componentes sin reiniciar la posición física del scroll de forma inmediata a menos que se lo ordenemos.
Si la vista entrante calcula sus posiciones de inicio (start) y fin (end) con ScrollTrigger antes de que el scroll se haya reseteado al origen (top: 0), las animaciones se disparan inmediatamente de manera prematura o calculan valores desfasados por la altura de la página saliente.
En la configuración de Vue Router solucioné esto combinando el comportamiento de scroll nativo de la librería con una recarga del motor de ScrollTrigger diferida mediante nextTick:
import { createRouter, createWebHistory } from 'vue-router'
import { nextTick } from 'vue'
import gsap from 'gsap'
import ScrollTrigger from 'gsap/ScrollTrigger'
const router = createRouter({
history: createWebHistory(),
routes: [
// Definición de rutas del proyecto
],
scrollBehavior(to, from, savedPosition) {
if (savedPosition) {
return savedPosition
} else {
return { top: 0 }
}
}
})
router.afterEach(async () => {
await nextTick()
ScrollTrigger.refresh()
})
export default routerAl invocar ScrollTrigger.refresh() justo después de que Vue termina de procesar los cambios del árbol de nodos en el ciclo nextTick(), nos aseguramos de que el DOM de la nueva ruta ya tenga asignadas sus dimensiones reales en el flujo tipográfico antes de que se tracen las zonas de activación de scroll.
Optimización del pintado mediante propiedades aceleradas por GPU
Complementar la gestión del ciclo de vida con un código CSS eficiente en Tailwind es vital para evitar el desbordamiento de repintados (repaints) durante la ejecución del scroll suave. Animar propiedades como margin, top o height fuerza al motor del navegador a reconfigurar la geometría global de la página en cada cuadro.
En La Rúcula Gastrobar restringí las animaciones de scroll a dos propiedades exclusivas manipuladas por GSAP: transform (mediante traslaciones y o x) y opacity. Estas propiedades son procesadas directamente en la unidad de procesamiento gráfico (GPU) sin provocar recálculos del diseño compositivo (reflow).
Mediante Tailwind CSS apliqué clases de preparación de capa como will-change-transform o transform-gpu únicamente en las tarjetas o contenedores con secuencias de animación complejas. Esto le indica al navegador que reserve una capa de composición dedicada en la placa de video para esos elementos antes de que la animación comience, previniendo caídas bruscas en el rendimiento del renderizado durante desplazamientos rápidos.
Cierre y consideraciones finales
Diseñar una interfaz web de alto impacto gráfico requiere equilibrar la propuesta visual con los principios esenciales de la ingeniería de software. Las librerías de animación y scroll suave ofrecen posibilidades creativas enormes, pero utilizarlas dentro de un ecosistema reactivo como Vue 3 exige controlar rigurosamente el ciclo de vida de cada objeto que introducimos en la memoria.
A través del uso de gsap.context() para encapsular la limpieza de eventos, la integración explícita de Lenis en el ticker de GSAP y la resincronización de dimensiones tras cada cambio de ruta con Vue Router, logré que La Rúcula Gastrobar funcione como una aplicación robusta, fluida y predecible. Garantizar que cada recurso que se monta se remueva sin dejar rastros es el camino para construir experiencias interactivas memorables sin comprometer la estabilidad del sistema.