Skip to main content
v2.4.1 — compatível com App Router, Pages Router e Edge Runtime.

​
Instalação

Instale o pacote oficial usando seu gerenciador preferido. 
npm install @caracracha/nextjs

​
Configuração

Adicione suas chaves no .env.local. Você encontra elas no dashboard em Developers → API Keys.
.env.local
# Ambiente Dev
NEXT_PUBLIC_CARACRACHA_APP_ID="app_live_y8k..."
CARACRACHA_SECRET_KEY="sk_live_..."
Nunca exponha sk_live_*. A chave secreta só deve ser usada no servidor. O SDK se recusa a carregar uma sk_* em Client Components — mas é bom saber.

​
Uso rápido

Envolva sua aplicação com o <CaraCrachaProvider />. Ele cuida de sessão, refresh e sincronização entre abas.
app/layout.tsx
import { CaraCrachaProvider } from "@caracracha/nextjs"

export default function RootLayout({ children }) {
  return (
    <html lang="pt-BR">
      <body>
        <CaraCrachaProvider>
          {children}
        </CaraCrachaProvider>
      </body>
    </html> 
  )
}

​
Criando um usuário

No servidor, use o cliente do CaraCrachá para criar usuários programaticamente — útil para migrations e SSO customizado.
app/api/users/route.ts
import { caracracha } from "@caracracha/nextjs/server"

export async function POST(req: Request) {
  const user = await caracracha.users.create({
    email: "ana@acme.com.br",
    phoneNumber: "+55 11 91234-5678",
    metadata: { plan: "pro" },
  })

  return Response.json(user)
}

​
Resposta

O objeto User retornado pela API tem o seguinte formato: 
{
  "id": "user_2xk9Aq...",
  "email": "ana@acme.com.br",
  "phoneNumber": "+55 11 91234-5678",
  "emailVerified": false,
  "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_ indica tipo.
​
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.
Pronto para agentes. Claude e ChatGPT integram este SDK lendo uma Agent Skill oficial. Rode claude add-skill @caracracha/nextjs e peça “add login with Google to my app”. Veja Usando com IA.

​
Próximos passos

SDK React

Se você não usa Next.js, o SDK React funciona em qualquer app SPA.

Webhooks

Receba eventos quando usuários são criados ou atualizados.