gsap-react

Vue d’ensemble du skill gsap-react

À quoi sert gsap-react

gsap-react est le skill officiel GSAP pour React et les frameworks basés sur React comme Next.js. Il vous aide à créer des animations avec les bons patterns compatibles avec React : useGSAP(), les sélecteurs bornés à un contexte, gsap.context() et le nettoyage automatique. Utilisez le skill gsap-react quand vous devez ajouter du mouvement dans un composant sans vous battre avec les re-renders, les démontages de composant ou les bugs de sélection du DOM.

Qui devrait l’utiliser

Ce skill s’adresse aux développeurs frontend qui connaissent déjà React et veulent une mise en place fiable des animations, pas une initiation générale à l’animation. Il est particulièrement utile quand vous hésitez sur l’usage de GSAP dans une app React, quand une animation casse après un changement de route, ou quand vous avez besoin d’aide pour le flux d’installation et d’intégration de gsap-react.

Ce qui le distingue

Son principal atout, c’est la sécurité spécifique à React. Au lieu d’écrire une animation dans un simple useEffect() puis de gérer le nettoyage à la main, gsap-react vous oriente vers useGSAP() et des cibles bornées au contexte pour garder des animations prévisibles. Il aide aussi à éviter les erreurs fréquentes qui bloquent l’adoption : sélecteurs non bornés, enregistrement de plugin oublié et confusion liée au SSR.

Comment utiliser le skill gsap-react

Installer GSAP et le package React

Pour l’installation de gsap-react, ajoutez les deux packages à votre application :

npm install gsap
npm install @gsap/react

Enregistrez ensuite le plugin avant d’utiliser useGSAP() ou tout autre code GSAP :

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

Si vous sautez cette étape, le hook ne se comportera pas comme prévu.

Transformer un objectif flou en prompt exploitable

La meilleure façon d’utiliser gsap-react, c’est de partir d’un objectif d’animation concret, pas de “rendre l’interface plus jolie”. Précisez : le type de composant, ce qui doit s’animer, à quel moment le mouvement doit démarrer, s’il doit se répéter, et si l’effet doit survivre aux changements de route ou au nettoyage lors du démontage.

Un bon prompt ressemble à ceci :

• “Animer trois cartes qui glissent à l’apparition dans un client component Next.js, avec un scope limité à ce conteneur.”
• “Convertir cette animation GSAP en useEffect() vers useGSAP() avec nettoyage et refs.”
• “Ajouter un mouvement au survol et au scroll, tout en gardant des sélecteurs bornés au composant.”

Lire d’abord les bons fichiers

Commencez par SKILL.md, puis inspectez dans le repo les parties qui définissent le comportement et les contraintes. Pour ce skill, le chemin utile est court : lisez d’abord les instructions centrales, puis les exemples liés ou la documentation environnante s’ils existent. Pour gsap-react, les points de décision principaux sont les sections When to Use This Skill, Installation et Prefer the useGSAP() Hook.

Utiliser le workflow compatible React

Le flux par défaut est le suivant : importer useGSAP, enregistrer le plugin, créer un ref, borner les sélecteurs à ce ref, puis mettre le code d’animation dans le hook. Préférez cette approche à des sélecteurs globaux sur le document ou à des timelines non bornées. Si vous avez besoin de callbacks exécutés plus tard, utilisez contextSafe pour que les interactions différées soient elles aussi nettoyées correctement.

FAQ du skill gsap-react

Faut-il utiliser gsap-react pour chaque animation GSAP dans React ?

Non. Si l’animation est simple et déjà bien gérée ailleurs dans votre stack, ce skill peut être inutile. Utilisez gsap-react quand le code touche au cycle de vie du composant, au nettoyage, au ciblage DOM borné ou au comportement spécifique au framework dans React ou Next.js.

En quoi est-ce différent d’un prompt ordinaire ?

Un prompt classique peut produire du code d’animation fonctionnel, mais gsap-react ajoute des règles d’intégration React orientées production : enregistrement du plugin, useGSAP(), sélecteurs bornés et comportement de nettoyage. Cela réduit le temps de débogage et rend la sortie plus réutilisable dans du vrai code applicatif.

gsap-react est-il adapté aux débutants ?

Oui, si l’utilisateur sait décrire un composant et le mouvement souhaité. Ce n’est pas un cours débutant sur la théorie de l’animation ; c’est un guide pratique gsap-react pour passer d’une idée d’UI approximative à du code React sûr. Les débutants obtiennent les meilleurs résultats lorsqu’ils fournissent la structure du composant et le déclencheur attendu.

Quand ne faut-il pas l’utiliser ?

N’utilisez pas gsap-react pour des frameworks non React, ni quand vous avez besoin d’une réponse d’animation agnostique du framework. Pour Vue, Svelte et les autres stacks, utilisez plutôt le skill GSAP spécifique au framework. Si vous n’avez besoin que de la syntaxe de base des tweens ou des timelines, un autre skill GSAP peut être plus adapté.

Comment améliorer le skill gsap-react

Donner de la structure, pas seulement l’intention

Le meilleur moyen d’améliorer la sortie de gsap-react, c’est d’être précis. Fournissez le markup du composant, les sélecteurs ou refs que vous avez déjà, ainsi que les conditions exactes de déclenchement. “Animer le hero” est trop vague ; “faire apparaître le titre en fondu, faire glisser le CTA et décaler les cartes de fonctionnalités à la première render” donne au skill assez de matière pour produire du code exploitable.

Mentionner les contraintes qui changent l’implémentation

Indiquez tôt le SSR, les transitions de route, prefers-reduced-motion et les attentes en matière de nettoyage. Ces contraintes déterminent si la réponse doit utiliser useGSAP(), un client component, des refs bornées ou une autre approche d’animation. Si votre application est sous Next.js, dites-le explicitement dans le prompt.

Vérifier les erreurs de scope dans le premier résultat

Les échecs les plus courants sont les sélecteurs non bornés, les animations qui partent trop tôt et le code qui ignore le démontage du composant. Si la première sortie utilise des sélecteurs larges comme .box sans scope, demandez une réécriture bornée par ref. Si des callbacks se déclenchent plus tard, demandez la prise en charge de contextSafe dans l’itération suivante.

Itérer avec le mouvement exact que vous voulez

Après le premier passage, affinez un seul paramètre à la fois : le timing, l’easing, le stagger, le déclencheur ou le comportement de nettoyage. Un bon cycle d’utilisation de gsap-react consiste à implémenter l’animation de base, la tester dans le composant, puis demander des ajustements ciblés comme “rendre l’effet moins agressif sur mobile” ou “passer le déclenchement uniquement au survol”.