Como adicionar um mascote Rive a um app no Lovable

O Lovable consegue instalar o runtime do Rive?

Sim. A documentação do Lovable diz para citar o nome do pacote no chat do projeto, ou descrever o recurso, que o Lovable instala e integra; você não usa terminal nem edita o package.json. Ele instala pacotes com Bun.

Install @rive-app/react-webgl2 and pin the exact version.

O Rive publica três pacotes React com a mesma API. O @rive-app/react-webgl2 é o que o guia de React do Rive instala e é compatível com todos os recursos. Escolha @rive-app/react-canvas se uma página for mostrar muitas animações ao mesmo tempo, já que os navegadores limitam os contextos WebGL por página.

O Lovable avisa que não pode garantir pacotes de terceiros, então confira o que foi instalado: os pacotes do Rive são publicados pelo Rive no escopo @rive-app. Se depois você rodar o projeto fora do Lovable, instale com Bun para que as versões fiquem sincronizadas com o bun.lock.

Como coloco o arquivo .riv no projeto?

O .riv precisa ser servido como um arquivo estático que o navegador consiga buscar. A documentação do Lovable descreve três formas de adicionar mídia, além de mais uma opção de armazenamento:

Com a sincronização com o GitHub, segundo o Lovable, pushes na branch ativa, geralmente main, sincronizam de volta com o projeto. Arquivos em public/ são servidos a partir da raiz, então o componente carrega /mascot.riv, e não /public/mascot.riv.

O tamanho raramente é problema para um .riv, mas o Lovable não salva arquivos com mais de 10 MB em um projeto, e o GitHub rejeita arquivos com mais de 100 MB.

Qual prompt adiciona o componente do mascote?

Pedidos genéricos como "adicione um mascote animado" levam a nomes inventados e a uma animação CSS feita à mão. Passe ao Lovable os dados do arquivo. Este prompt considera um arquivo com um view model Character; renomeie as propriedades para combinar com as suas:

Add an animated mascot component.

- Install @rive-app/react-webgl2 (pin the exact version you install).
- The file is /mascot.riv (in public/). State machine: "CharacterViewModelMachine".
  Use useRive with autoplay: true and autoBind: true.
- View model "Character": number "mood" (0 idle, 1 happy, 2 wave, 3 thinking,
  4 sad, 5 loading, 6 listening, 7 talking, 8 sleeping, 9 attention) and triggers
  "success", "error", "yes", "no", "enter", "exit".
- Create components/Mascot.tsx with props mood: number and celebrateKey: number.
  Set mood with useViewModelInstanceNumber("mood", rive?.viewModelInstance) in a
  useEffect; fire useViewModelInstanceTrigger("success", ...) when celebrateKey
  increases.
- Wrap RiveComponent in a div with a fixed 240 x 240 px size (no layout shift).
- If prefers-reduced-motion is reduce, render /mascot-poster.webp instead.
- Render it only in the browser (client-only), never during server rendering.
- Do not add Lottie or any other animation library.

As duas últimas regras são as mais importantes. Sem um wrapper de tamanho fixo, o canvas se ajusta a um pai sem altura e não mostra nada. Sem renderização só no cliente, um projeto novo do Lovable pode falhar durante a renderização no servidor (próxima seção).

Para uma splash screen ou intro de carregamento em vez de um mascote, use os prompts de Prompts de IA para um mascote animado de splash ou carregamento; eles cobrem o Lovable, além de Cursor, Claude Code, Bolt e v0.

Como conecto o humor aos eventos do app?

Defina o mapeamento uma vez e mantenha-o em um só lugar, como um pequeno context ou store, para que todas as páginas concordem sobre o que o personagem faz:

Depois, peça ao Lovable para conectar tudo:

Create a MascotContext with setMood(n) and celebrate().
Show the Mascot in the dashboard header.
- While any data query is loading: mood 5.
- When a save succeeds: celebrate() and mood 1.
- When a save fails or validation fails: mood 4.
- When the project list is empty: mood 8.
Do not change any other behavior.

A última linha mantém a mudança contida. Confira o resultado na visualização de código: o humor deve ser definido em effects ou event handlers, nunca durante a renderização.

Por que o mascote fica em branco ou trava em um projeto novo do Lovable?

O Lovable tornou o TanStack Start o padrão para novos projetos em 13 de maio de 2026. O TanStack Start renderiza cada página em HTML no servidor primeiro, e a própria documentação do Lovable avisa que algumas bibliotecas exclusivas do navegador podem quebrar a renderização no servidor. O Rive desenha com canvas e WebAssembly no navegador, então renderize o mascote só no cliente. O componente ClientOnly do TanStack Router faz isso, com um fallback enquanto o cliente carrega:

import { ClientOnly } from "@tanstack/react-router";

<ClientOnly fallback={<img src="/mascot-poster.webp" alt="" width={240} height={240} />}>
  <Mascot mood={mood} celebrateKey={cheer} />
</ClientOnly>

Projetos criados antes com o template React e Vite do Lovable renderizam apenas no navegador e não precisam do wrapper. Se o mascote continuar em branco, verifique nesta ordem:

1. A aba Network mostra /mascot.riv carregando com status 200, não 404.
2. O nome da state machine corresponde exatamente ao do arquivo, incluindo maiúsculas e minúsculas.
3. O wrapper tem largura e altura explícitas.
4. O console do navegador não mostra erro de CORS para um .riv hospedado.

Onde consigo um arquivo de mascote com esses estados?

Você pode criar os estados no editor do Rive ou contratar um animador; em qualquer caso, peça um número de humor e triggers nomeados, já que é isso que os prompts acima esperam.

O Charmotion gera o conjunto a partir de uma imagem do seu personagem ou logo: 17 animações em um único .riv com CharacterViewModelMachine e o view model Character usado nesta página, uma CharacterStateMachine clássica com um input mood e uma intro LaunchStateMachine, além de MP4, GIF, WebM e MOV transparentes e código React. O .riv e o WebM e o MOV transparentes estão em todos os planos pagos (a partir de US$ 20 por mês), junto com MP4, GIF e o vídeo de abertura 9:16 com fundo sólido.

Adicione um mascote Rive a um app do Lovable

1. Instale o runtime. Peça no chat: instale @rive-app/react-webgl2 e fixe a versão exata.
2. Adicione o .riv. Envie public/mascot.riv para a branch do GitHub sincronizada, ou hospede-o em uma CDN com CORS e passe a URL ao Lovable.
3. Peça o componente. Cole um prompt com os nomes da state machine, do view model e das propriedades, um wrapper de tamanho fixo, movimento reduzido e renderização só no cliente.
4. Envolva para renderização no servidor. Em projetos TanStack Start, renderize o mascote dentro de ClientOnly com uma imagem estática (poster) como fallback.
5. Mapeie eventos para humores. Peça um MascotContext e mapeie os estados de carregamento, sucesso, erro e vazio para humores e triggers.
6. Verifique. Confira se o .riv carrega com status 200, se os nomes batem e se nada é definido durante a renderização.

Perguntas frequentes

Por que o Lovable diz que não encontra o mascot.riv?

Geralmente é o caminho. Os arquivos em public/ são servidos a partir da raiz do site, então o componente deve carregar /mascot.riv. Confirme também que o arquivo chegou ao projeto: se você o enviou ao GitHub, ele precisa estar na branch que o Lovable sincroniza no momento, senão não vai aparecer.

Posso usar um arquivo Lottie no Lovable em vez disso?

Sim, pedindo ao Lovable que instale um player Lottie, como o @lottiefiles/dotlottie-react. Mas um arquivo Lottie reproduz uma única sequência, então um mascote com humores e reações precisa de um arquivo por estado e de código para alternar entre eles. Um único arquivo Rive com state machine evita isso.

O mascote Rive vai deixar meu app Lovable mais lento?

Ele adiciona o runtime do Rive, um módulo WASM de várias centenas de kilobytes compactado, além do .riv. Carregue-o só nas páginas que mostram o mascote, renderize primeiro uma pequena imagem estática (poster) e pule o canvas completamente quando o visitante preferir movimento reduzido.

Respostas rápidas deste guia

• O Lovable consegue instalar o runtime do Rive?
• Como coloco um arquivo .riv em um projeto Lovable?

Fontes

• Use npm packages, Lovable Docs
• Using images, Lovable Docs
• Sync your Lovable project with GitHub, Lovable Docs
• Upgrade a project to TanStack Start, Lovable Docs
• Storage, Lovable Docs
• ClientOnly component, TanStack Router
• React runtime, Rive
• React runtime: Data binding, Rive
• Runtime sizes, Rive