gsap-react

Visão geral da skill gsap-react

Para que serve o gsap-react

gsap-react é a skill oficial do GSAP para React e para frameworks baseados em React, como o Next.js. Ela ajuda você a criar animações com os padrões certos para React: useGSAP(), seletores com escopo, gsap.context() e limpeza automática. Use a skill gsap-react quando precisar adicionar motion a um componente sem brigar com re-renders, unmounts ou bugs de seleção no DOM.

Quem deve usar

Esta skill é indicada para engenheiros frontend que já conhecem React e querem uma configuração confiável de animações, não uma introdução genérica a motion. Ela é especialmente útil quando você está decidindo se vale usar GSAP em um app React, quando uma animação quebra após mudanças de rota ou quando precisa de orientação sobre o fluxo de instalação e integração do gsap-react.

O que a torna diferente

O principal valor está na segurança específica para React. Em vez de escrever uma animação em useEffect() e fazer a limpeza manualmente, o gsap-react orienta você a usar useGSAP() e alvos com escopo, para que as animações continuem previsíveis. Ele também ajuda a evitar os erros comuns que travam a adoção: seletores sem escopo, falta de registro do plugin e confusão relacionada a SSR.

Como usar a skill gsap-react

Instale o GSAP e o pacote para React

Para instalar o gsap-react, adicione os dois pacotes ao seu app:

npm install gsap
npm install @gsap/react

Depois, registre o plugin antes de usar useGSAP() ou qualquer outro código do GSAP:

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

Se você pular o registro, o hook não vai se comportar como esperado.

Transforme um objetivo vago em um prompt útil

O melhor uso do gsap-react começa com um objetivo concreto de animação, não com “deixar mais bonito”. Inclua: o tipo de componente, o que deve animar, quando a animação deve começar, se ela precisa repetir e se o efeito deve sobreviver a mudanças de rota ou ser limpo no unmount.

Um prompt forte seria algo como:

• “Anime três cards deslizando na montagem em um client component do Next.js, com escopo limitado a este container.”
• “Converta esta animação GSAP em useEffect() para useGSAP() com cleanup e refs.”
• “Adicione motion no hover e no scroll, mas mantenha os seletores com escopo no componente.”

Leia primeiro os arquivos certos

Comece por SKILL.md e depois inspecione as partes do repositório que definem comportamento e restrições. Nesta skill, o caminho útil é curto, então leia primeiro as instruções centrais e, em seguida, quaisquer exemplos ou documentos relacionados, se houver. Para o gsap-react, os principais pontos de decisão ficam nas seções When to Use This Skill, Installation e Prefer the useGSAP() Hook.

Use o fluxo seguro para React

O fluxo padrão é: importar useGSAP, registrar o plugin, criar uma ref, aplicar escopo aos seletores dessa ref e colocar o código de animação dentro do hook. Prefira isso em vez de seletores globais no documento ou timelines sem escopo. Se você precisar de callbacks que disparem depois, use contextSafe para que interações atrasadas também sejam limpas corretamente.

FAQ da skill gsap-react

Preciso do gsap-react para toda animação GSAP em React?

Não. Se a animação for pequena e já estiver resolvida em outra parte da sua stack, a skill pode ser desnecessária. Use gsap-react quando o código tocar o ciclo de vida do componente, a limpeza, o alvo DOM com escopo ou comportamentos específicos do framework em React ou Next.js.

Qual é a diferença em relação a um prompt comum?

Um prompt normal pode gerar código de animação que funciona, mas o gsap-react adiciona regras opinativas de integração com React que importam em produção: registro do plugin, useGSAP(), seletores com escopo e comportamento de cleanup. Isso reduz o tempo de debug e torna a saída mais reutilizável em código real de aplicação.

O gsap-react é amigável para iniciantes?

Sim, desde que a pessoa consiga descrever um componente e o movimento desejado. Não é um curso introdutório de teoria de animação; é um guia prático de gsap-react para sair de uma ideia visual inicial até um código React seguro. Iniciantes têm melhores resultados quando informam a estrutura do componente e o trigger esperado.

Quando eu não devo usar?

Não escolha gsap-react para frameworks que não sejam React, nem quando você precisar de uma resposta de animação agnóstica de biblioteca. Para Vue, Svelte e outras stacks, use a skill do GSAP específica do framework. Se você só precisa da sintaxe básica de tween ou timeline, outra skill do GSAP pode ser mais adequada.

Como melhorar a skill gsap-react

Dê estrutura, não só intenção

A melhor forma de melhorar a saída do gsap-react é ser específico. Forneça o markup do componente, os seletores ou refs que você já tem e as condições exatas de disparo. “Animar o hero” é fraco; “fazer o título aparecer em fade, deslizar o CTA e aplicar stagger nos cards de recursos na primeira renderização” dá detalhes suficientes para a skill gerar código útil.

Mencione as restrições que mudam a implementação

Informe cedo sobre SSR, transições de rota, redução de movimento e expectativas de cleanup. Essas restrições determinam se a resposta deve usar useGSAP(), um client component, refs com escopo ou uma abordagem diferente de animação. Se o seu app é Next.js, diga isso explicitamente no prompt.

Revise o primeiro resultado em busca de erros de escopo

Os modos de falha mais comuns são seletores sem escopo, animações que rodam cedo demais e código que ignora o unmount do componente. Se a primeira saída usar seletores amplos como .box sem um scope, peça uma reescrita com ref e escopo. Se callbacks forem disparados depois, solicite no follow-up o tratamento com contextSafe.

Itere com o movimento exato que você quer

Depois da primeira versão, refine mudando uma variável de cada vez: timing, easing, stagger, trigger ou comportamento de cleanup. Um bom ciclo de uso do gsap-react é: implementar a animação base, testá-la no componente e então pedir ajustes pontuais como “deixe menos agressivo no mobile” ou “mude o trigger para apenas hover”.