Integrar RainbowKit a uma rede Tanssi¶
Introdução¶
RainbowKit é uma biblioteca React que adiciona conexão de carteiras a um dApp. Ela suporta várias carteiras e oferece recursos como alternar cadeias, resolver endereços ENS e exibir saldo. O RainbowKit traz opções de customização para cadeias compatíveis com EVM, facilitando conectar carteiras a redes personalizadas.
O RainbowKit agrupa várias ferramentas para simplificar a conexão de carteiras em um dApp:
- Wagmi — hooks React para contas, carteiras, contratos, transações, assinatura, ENS e mais
- viem — interface TypeScript com primitivas de baixo nível para interagir com Ethereum
- WalletConnect — adiciona conexões criptografadas e UX aprimorada (ex.: conectar carteira móvel via QR)
- TanStack Query — ajuda a gerenciar e atualizar estado de servidor no app
Usando essas peças juntas, você evita reimplementar fluxo de conexão, persistência de sessão, atualização de saldo e troca de redes, acelerando a entrega do dApp.
Este guia explica como adicionar o RainbowKit a um dApp em uma rede com tecnologia Tanssi usando a CLI, além de opções para personalizar a integração.
Início rápido¶
Para começar um projeto novo, o RainbowKit pode gerar um esqueleto via CLI com RainbowKit e Wagmi em uma aplicação Next.js. Use o gerenciador de pacotes de sua preferência:
npm init @rainbow-me/rainbowkit@latest
pnpm create @rainbow-me/rainbowkit@latest
yarn create @rainbow-me/rainbowkit
O script pedirá o nome do projeto, criará o diretório com o boilerplate e instalará as dependências.
Em seguida, inicie o servidor de desenvolvimento e abra http://localhost:3000:
cd INSERT_PROJECT_NAME
npm run dev
cd INSERT_PROJECT_NAME
pnpm run dev
cd INSERT_PROJECT_NAME
yarn dev
Você verá a tela inicial:
Abra o projeto no editor e veja o arquivo wagmi.ts. É nele que você configura as cadeias disponíveis para conexão.
Como a rede EVM demo é uma rede personalizada do Tanssi, ela não pode ser importada direto de wagmi/chains. Defina a cadeia manualmente em wagmi.ts.
Configuração para a rede EVM demo do Tanssi:
import '@rainbow-me/rainbowkit/styles.css';
import { getDefaultConfig, RainbowKitProvider } from '@rainbow-me/rainbowkit';
import { WagmiProvider } from 'wagmi';
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
import { type Chain } from 'viem'
export const demoEVMChain = {
id: 5678,
name: "Tanssi demo EVM Network",
nativeCurrency: { name: "TANGO", symbol: "TANGO", decimals: 18 },
rpcUrls: {
default: { http: ['https://services.tanssi-testnet.network/dancelight-2001'] }
},
blockExplorers: {
default: { name: 'Demo EVM Explorer', url: 'https://dancelight-2001-blockscout.tanssi-chains.network/' }
},
} as const satisfies Chain
export const config = getDefaultConfig({
appName: 'My Tanssi-powered Network',
projectId: 'TODO: get project id from...',
chains: [demoEVMChain],
ssr: true,
});
Atualize wagmi.ts conforme acima para suportar a rede demo. A próxima seção mostra como obter o projectId do WalletConnect.
Configuração manual¶
As seções seguintes mostram como integrar o RainbowKit em um app React existente: instalar dependências, configurar cadeias, disponibilizar o RainbowKit no dApp, definir a cadeia padrão do Connect Wallet e personalizar o tema. O exemplo usa a rede EVM demo do Tanssi, mas pode ser adaptado mudando o RPC.
Verificando pré-requisitos¶
- Uma rede compatível com EVM no Tanssi
- Um dApp existente em React
- Exemplos do repositório RainbowKit (há templates para vários frameworks)
- Para seguir este guia, crie um projeto Next.js (Typescript + App Router) seguindo a instalação automática em Next.js
- A carteira deve suportar redes personalizadas (a rede demo será adicionada manualmente)
- Um
projectIddo WalletConnect (gratuito):- Vá em WalletConnect Cloud
- Em Projects, clique Create
- Preencha as informações (pode deixar Homepage URL em branco se não estiver deployado)
- Escolha o SDK AppKit
- Escolha o ambiente (React neste guia)
- Copie o
projectIdno menu lateral ou no snippet do Quickstart
Começando¶
Instale RainbowKit e dependências:
npm install @rainbow-me/rainbowkit wagmi viem@2.x @tanstack/react-query
pnpm install @rainbow-me/rainbowkit wagmi viem@2.x @tanstack/react-query
yarn add @rainbow-me/rainbowkit wagmi viem@2.x @tanstack/react-query
Suba o servidor de desenvolvimento:
npm run dev
pnpm run dev
yarn dev
Abra http://localhost:3000.
Para testar, conecte a carteira MetaMask na rede EVM demo do Tanssi. Adicione a rede no MetaMask:
- Configurações > Redes > Adicionar Rede
- Preencha:
- Nome:
Demo EVM Chain - RPC URL:
https://services.tanssi-testnet.network/dancelight-2001/ - Chain ID:
5678 - Símbolo:
TANGO - Block Explorer:
https://dancelight-2001-blockscout.tanssi-chains.network/
Para instruções detalhadas, veja Conecte o MetaMask à sua Rede EVM Tanssi.
Depois, adicione o projectId ao app:
-
Crie
.env.localna raiz:touch .env.local -
Adicione o ID:
.env.localNEXT_PUBLIC_PROJECT_ID='INSERT_PROJECT_ID' -
Confirme que
.env*.localestá no.gitignorepara evitar commit.
Se você usa vários ambientes (dev/homologação/prod), crie um projectId separado para cada um e valide se o domínio cadastrado no WalletConnect Cloud corresponde ao ambiente correto.
Conectar o dApp ao MetaMask¶
Passos principais:
- Importar RainbowKit, Wagmi e TanStack Query
- Configurar o Wagmi
- Envolver o app com providers
- Adicionar o botão de conexão
Seguir essa ordem garante que o estado de conexão e os modais do RainbowKit funcionem em toda a aplicação.
Importar RainbowKit, Wagmi e TanStack Query¶
Crie wagmi.ts na raiz com imports e a cadeia demo EVM:
touch wagmi.ts
import '@rainbow-me/rainbowkit/styles.css';
import { getDefaultConfig, RainbowKitProvider } from '@rainbow-me/rainbowkit';
import { WagmiProvider } from 'wagmi';
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
import { type Chain } from 'viem'
export const demoEVMChain = {
id: 5678,
name: "Tanssi demo EVM Network",
nativeCurrency: { name: "TANGO", symbol: "TANGO", decimals: 18 },
rpcUrls: {
default: { http: ['https://services.tanssi-testnet.network/dancelight-2001'] }
},
blockExplorers: {
default: { name: 'Demo EVM Explorer', url: 'https://dancelight-2001-blockscout.tanssi-chains.network/' }
},
} as const satisfies Chain
export const config = getDefaultConfig({
appName: 'My Tanssi-powered Network',
projectId: 'process.env.NEXT_PUBLIC_PROJECT_ID',
chains: [demoEVMChain ],
ssr: true,
});
Envolver o aplicativo com providers¶
Crie providers.tsx para incluir WagmiProvider e QueryClientProvider:
cd app && touch providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';
import { RainbowKitProvider } from '@rainbow-me/rainbowkit';
import { config } from '../wagmi';
const queryClient = new QueryClient();
export function Providers({ children }: { children: React.ReactNode }) {
return (
<WagmiProvider config={config}>
<QueryClientProvider client={queryClient}>
<RainbowKitProvider>{children}</RainbowKitProvider>
</QueryClientProvider>
</WagmiProvider>
);
}
Depois, edite app/layout.tsx para usar Providers:
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';
import '@rainbow-me/rainbowkit/styles.css';
import { Providers } from './providers';
const inter = Inter({ subsets: ['latin'] });
export const metadata: Metadata = {
title: 'My Tanssi dApp',
description: 'Generated by create next app',
};
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang='en'>
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
Adicionar o botão Connect¶
Use o componente ConnectButton (pode ficar em page.tsx ou em um header/nav):
import { ConnectButton } from '@rainbow-me/rainbowkit';
export default function Home() {
return (
<div className="flex h-screen items-center justify-center">
<ConnectButton />
</div>
);
}
Com o servidor rodando, aparecerá Connect Wallet; clicar abre o modal RainbowKit. Selecione MetaMask e conecte. A configuração padrão usa a Demo EVM Chain e mostra rede, saldo do token nativo e endereço.
Se você tiver vários botões ou páginas, considere criar um componente compartilhado para evitar duplicar lógica de conexão e estilização.
Personalizar o RainbowKit¶
O RainbowKit facilita a conexão e permite customizar UI/UX. Veja todas as opções na docs do RainbowKit. Aqui vamos definir a cadeia inicial e aplicar tema customizado.
Definir cadeia inicial¶
O RainbowKit conecta na primeira cadeia da lista do Wagmi. Melhor é usar initialChain no RainbowKitProvider. Em providers.tsx, defina:
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';
import { RainbowKitProvider, darkTheme } from '@rainbow-me/rainbowkit';
import { config, demoEVMChain } from '../wagmi';
const queryClient = new QueryClient();
export function Providers({ children }: { children: React.ReactNode }) {
return (
<WagmiProvider config={config}>
<QueryClientProvider client={queryClient}>
<RainbowKitProvider initialChain={demoEVMChain}>
{children}
</RainbowKitProvider>
</QueryClientProvider>
</WagmiProvider>
);
}
Isso força conectar primeiro na Demo EVM Chain.
Definir cores de tema¶
Use lightTheme, darkTheme ou midnightTheme. Exemplo com tema escuro customizado (adicione darkTheme ao import):
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { WagmiProvider } from 'wagmi';
import { RainbowKitProvider, darkTheme } from '@rainbow-me/rainbowkit';
import { config, demoEVMChain } from '../wagmi';
const queryClient = new QueryClient();
export function Providers({ children }: { children: React.ReactNode }) {
return (
<WagmiProvider config={config}>
<QueryClientProvider client={queryClient}>
<RainbowKitProvider
initialChain={demoEVMChain}
theme={darkTheme({
accentColor: '#189B9B', // Tanssi accent color
accentColorForeground: 'white',
borderRadius: 'medium',
fontStack: 'system',
overlayBlur: 'small'
})}
>
{children}
</RainbowKitProvider>
</QueryClientProvider>
</WagmiProvider>
);
}
Campos: - accentColor — cor primária (ex.: #189B9B do Tanssi) - accentColorForeground — cor do texto sobre a primária - borderRadius — arredondamento - fontStack — fontes (ex.: system) - overlayBlur — desfoque de fundo em modais
Você pode ainda ajustar ícones, textos do modal e posição do botão criando um tema customizado ou sobrescrevendo componentes via props do ConnectButton.
Conselho
Teste temas e cores para combinar com o estilo do seu dApp.
Lidar com desconexões¶
Desconectar no dApp¶
O modal RainbowKit inclui Disconnect; clique na seta ao lado da conta e depois Disconnect.
Desconectar no MetaMask¶
- Abra a extensão MetaMask
- Clique nos três pontos (canto superior direito)
- Selecione Connected sites
- Revise e clique Disconnect nos sites desejados
Resultado final¶
O botão Connect Wallet deve usar a cor definida em accentColor; o modal também. Escolha MetaMask, assine e veja a rede EVM demo conectada com o saldo de TANGO sem precisar trocar manualmente.
Se desejar suportar redes adicionais, basta adicioná-las em wagmi.ts e fornecer RPCs confiáveis; o modal exibirá as opções no Switch Networks respeitando a ordem definida. Verifique também se os explorers configurados respondem corretamente para evitar erros de UX.
Mais opções estão na docs do RainbowKit. Código completo no repositório rainbowkit-manual-build-demo.
| Criada: 9 de dezembro de 2025