gsap-react

Descripción general de la skill gsap-react

Para qué sirve gsap-react

gsap-react es la skill oficial de GSAP para React y frameworks basados en React como Next.js. Te ayuda a crear animaciones con los patrones correctos y seguros para React: useGSAP(), selectores con scope, gsap.context() y limpieza automática. Usa la skill gsap-react cuando necesites añadir movimiento a un componente sin pelearte con re-renderizados, desmontajes o errores de selección en el DOM.

Quién debería usarla

Esta skill encaja con ingenieros frontend que ya conocen React y quieren una configuración de animaciones fiable, no una introducción genérica a las animaciones. Es especialmente útil cuando estás decidiendo si conviene usar GSAP en una app React, cuando una animación se rompe después de cambios de ruta o cuando necesitas orientación sobre el flujo de instalación e integración de gsap-react.

Qué la hace diferente

Su valor principal es la seguridad específica para React. En lugar de escribir una animación con un useEffect() básico y limpiar todo a mano, gsap-react te guía hacia useGSAP() y objetivos acotados para que las animaciones se mantengan previsibles. También ayuda a evitar los errores comunes que frenan la adopción: selectores sin scope, registro ausente de plugins y confusión relacionada con SSR.

Cómo usar la skill gsap-react

Instala GSAP y el paquete para React

Para instalar gsap-react, añade ambos paquetes a tu app:

npm install gsap
npm install @gsap/react

Después, registra el plugin antes de usar useGSAP() u otro código de GSAP:

import { useGSAP } from "@gsap/react";
gsap.registerPlugin(useGSAP);

Si omites el registro, el hook no se comportará como esperas.

Convierte un objetivo vago en un prompt útil

El mejor uso de gsap-react empieza con un objetivo de animación concreto, no con “haz que se vea mejor”. Incluye: el tipo de componente, qué debe animarse, cuándo debe empezar, si debe repetirse y si el efecto tiene que sobrevivir a cambios de ruta o limpiarse al desmontar.

Un prompt sólido se vería así:

• “Anima tres tarjetas deslizándose al cargar en un client component de Next.js, acotado a este contenedor.”
• “Convierte esta animación GSAP con useEffect() a useGSAP() con limpieza y refs.”
• “Añade movimiento al pasar el cursor y al hacer scroll, pero mantiene los selectores acotados al componente.”

Lee primero los archivos correctos

Empieza por SKILL.md y luego revisa las partes del repo copy que definen comportamiento y restricciones. En esta skill, la ruta útil es corta, así que lee primero las instrucciones centrales y después cualquier ejemplo enlazado o la documentación cercana, si existe. Para gsap-react, los puntos de decisión principales están en las secciones When to Use This Skill, Installation y Prefer the useGSAP() Hook.

Usa el flujo de trabajo seguro para React

El flujo por defecto es: importar useGSAP, registrar el plugin, crear una ref, acotar los selectores a esa ref y colocar el código de animación dentro del hook. Prefiere esto frente a selectores globales sobre document o timelines sin scope. Si necesitas callbacks que se ejecuten más tarde, usa contextSafe para que las interacciones diferidas también se limpien correctamente.

Preguntas frecuentes sobre la skill gsap-react

¿Necesito gsap-react para cada animación de GSAP en React?

No. Si la animación es pequeña y ya está resuelta en otra parte de tu stack, la skill puede ser innecesaria. Usa gsap-react cuando el código toque el ciclo de vida del componente, la limpieza, el targeting acotado del DOM o comportamientos específicos del framework en React o Next.js.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede generar código de animación que funcione, pero gsap-react añade reglas opinadas de integración con React que importan en producción: registro de plugins, useGSAP(), selectores con scope y comportamiento de limpieza. Eso reduce el tiempo de depuración y hace que la salida sea más reutilizable en código real de aplicación.

¿gsap-react es apta para principiantes?

Sí, si la persona puede describir un componente y el movimiento deseado. No es un curso básico de teoría de animación; es una guía práctica de gsap-react para pasar de una idea visual general a código React seguro. Los principiantes obtienen mejores resultados cuando aportan la estructura del componente y el disparador esperado.

¿Cuándo no debería usarla?

No elijas gsap-react para frameworks que no sean React, ni cuando necesites una respuesta de animación agnóstica a la librería. Para Vue, Svelte y otros stacks, usa la skill de GSAP específica del framework. Si solo necesitas sintaxis básica de tweens o timelines, otra skill de GSAP puede encajar mejor.

Cómo mejorar la skill gsap-react

Aporta estructura, no solo intención

La mejor mejora para la salida de gsap-react es la especificidad. Proporciona el markup del componente, los selectores o refs que ya tienes y las condiciones exactas del disparador. “Anima el hero” es demasiado vago; “haz que aparezca el título con fade in, deslice el CTA y escalone las tarjetas de funcionalidades en el primer render” da a la skill suficientes detalles para generar código útil.

Menciona las restricciones que cambian la implementación

Señala pronto SSR, cambios de ruta, prefers-reduced-motion y expectativas de limpieza. Estas restricciones deciden si la respuesta debe usar useGSAP(), un client component, refs con scope o un enfoque de animación distinto. Si tu app es Next.js, dilo explícitamente en el prompt.

Revisa el primer resultado buscando errores de scope

Los fallos más comunes son selectores sin acotar, animaciones que se ejecutan demasiado pronto y código que ignora el desmontaje del componente. Si la primera salida usa selectores amplios como .box sin un scope, pide una reescritura acotada por ref. Si los callbacks se disparan más tarde, solicita manejo con contextSafe en el siguiente intento.

Itera con el movimiento exacto que quieres

Después del primer pase, refina cambiando una sola variable a la vez: tiempo, easing, stagger, disparador o comportamiento de limpieza. Un buen ciclo de uso de gsap-react es: implementar la animación base, probarla en el componente y luego pedir ajustes concretos como “hazlo menos agresivo en móvil” o “mueve el disparador para que solo responda al hover”.