Skip to main content
v2.4.1 — funciona com Vite, Create React App, Remix (client) e qualquer bundler compatível com React 18+.

​
Instalação

Crie um novo projeto React com Vite (ou use um existente) e instale o SDK. 
npm create vite@latest meu-app -- --template react-ts
cd meu-app
npm install @caracracha/react

​
Configuração

Adicione sua chave pública no .env.local. Você encontra ela no dashboard em Developers → API Keys.
.env.local
VITE_CARACRACHA_APP_ID="app_live_y8k..."
O prefixo VITE_ é obrigatório para que o Vite exponha a variável ao código client-side. Use .env.local para chaves de desenvolvimento — esse arquivo é ignorado pelo Git por padrão.
Em Create React App, troque o prefixo para REACT_APP_ e use process.env.REACT_APP_CARACRACHA_APP_ID no código.

​
Configure o Provider

Envolva sua aplicação com o <CaraCrachaProvider /> no arquivo de entrada. Ele cuida de sessão, refresh automático e sincronização entre abas.
src/main.tsx
import { CaraCrachaProvider } from "@caracracha/react"
import { createRoot } from "react-dom/client"
import App from "./App"

createRoot(document.getElementById("root")!).render(
  <CaraCrachaProvider afterSignOutUrl="/">
    <App />
  </CaraCrachaProvider>
)
O Provider lê VITE_CARACRACHA_APP_ID automaticamente. Se precisar passar a chave explicitamente, use a prop appId.

​
Use os componentes

Com o Provider configurado, você já pode usar os componentes prontos para cobrir os fluxos mais comuns.
src/App.tsx
import {
  Show,
  SignInButton,
  SignUpButton,
  UserButton,
} from "@caracracha/react"

export default function App() {
  return (
    <header>
      <Show when="signed-out">
        <SignInButton />
        <SignUpButton />
      </Show>
      <Show when="signed-in">
        <UserButton />
      </Show>
    </header>
  )
}
ComponenteO que faz
<Show when="signed-in">Renderiza filhos apenas se há sessão ativa.
<Show when="signed-out">Renderiza filhos apenas se não há sessão.
<SignInButton />Abre o modal de login.
<SignUpButton />Abre o modal de cadastro.
<UserButton />Avatar com menu (perfil, sair, trocar conta).

​
Acessando o usuário atual

Use o hook useUser() para ler dados do usuário autenticado em qualquer Client Component.
src/components/Greeting.tsx
import { useUser } from "@caracracha/react"

export function Greeting() {
  const { user, isLoaded } = useUser()

  if (!isLoaded) return <p>Carregando…</p>
  if (!user) return <p>Você não está logado.</p>

  return <p>Olá, {user.email} 👋</p>
}
O objeto user tem o seguinte formato: 
{
  "id": "user_2xk9Aq...",
  "email": "ana@acme.com.br",
  "phoneNumber": "+55 11 91234-5678",
  "emailVerified": true,
  "mfaEnabled": false,
  "organizations": [],
  "metadata": { "plan": "pro" },
  "createdAt": "2026-04-24T18:38:28.573Z",
  "updatedAt": "2026-04-24T18:38:28.573Z",
  "devMode": true
}
​
id
string
required
Identificador único do usuário. Prefixo user_.
​
email
string | null
Email principal. Normalizado para lowercase.
​
phoneNumber
string | null
Formato E.164. Verificado via SMS antes de persistir.
​
metadata
object
Lido no cliente. Use para dados não-sensíveis (plano, preferências).
​
devMode
boolean
true se o usuário pertence ao ambiente Dev.

​
Protegendo rotas

Combine <Show> com o router da sua preferência para criar rotas privadas.
src/routes/Dashboard.tsx
import { Show, RedirectToSignIn } from "@caracracha/react"

export function Dashboard() {
  return (
    <>
      <Show when="signed-in">
        <h1>Bem-vindo ao seu dashboard</h1>
      </Show>
      <Show when="signed-out">
        <RedirectToSignIn />
      </Show>
    </>
  )
}
Pronto para agentes. Claude e ChatGPT integram este SDK lendo uma Agent Skill oficial. Rode claude add-skill @caracracha/react e peça “add login with Google to my app”. Veja Usando com IA.

​
Próximos passos

SDK Next.js

Usa App Router ou Pages Router? O SDK Next.js adiciona suporte a Server Components e Route Handlers.

API de usuários

Crie, atualize e liste usuários programaticamente pelo servidor.