React
Guia completo de autenticação com Clowk no React: ClowkProvider, os hooks useAuth, useToken e useClowk, botões de login, rotas protegidas e o usuário.
Instalação
pnpm add @clowk/react@clowk/react já traz @clowk/core como dependência.
Configurar o provider
Envolva seu app com ClowkProvider:
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ClowkProvider } from '@clowk/react'
import App from './App'
createRoot(document.getElementById('root')!).render(
<StrictMode>
<ClowkProvider publishableKey={import.meta.env.VITE_CLOWK_PUBLISHABLE_KEY}>
<App />
</ClowkProvider>
</StrictMode>
)Props do ClowkProvider
| Prop | Tipo | Descrição |
|---|---|---|
publishableKey | string | Sua publishable key do Clowk |
secretKey | string | Secret key (só no servidor) |
tokenParam | string | Nome do parâmetro de query do token (padrão: "token") |
afterSignOutPath | string | Caminho de redirect após sair (padrão: "/") |
Acessar o usuário
Use o hook useAuth:
import { useAuth } from '@clowk/react'
function App() {
const { user, signedIn, isLoading, signOut } = useAuth()
if (isLoading) return <div>Loading...</div>
if (!signedIn) return <div>Not signed in</div>
return (
<div>
<p>Hello, {user?.name}</p>
<button onClick={signOut}>Sign out</button>
</div>
)
}Tipo de retorno de useAuth()
interface ClowkAuthState {
user: JwtPayload | null
token: string | null
signedIn: boolean
isLoading: boolean
signOut: () => void
}O objeto user contém todas as claims do JWT: sub, email, name, avatar_url, provider, instance_id, app_id.
Botões de autenticação
import { SignInButton, SignUpButton, SignOutButton, useAuth } from '@clowk/react'
function App() {
const { signedIn, user, isLoading } = useAuth()
if (isLoading) return <div>Loading...</div>
if (!signedIn) {
return (
<div>
<SignInButton />
<SignUpButton />
</div>
)
}
return (
<div>
<p>Hello, {user?.name}</p>
<SignOutButton />
</div>
)
}Todos os componentes de botão estendem ButtonHTMLAttributes e aceitam a prop redirectUri:
<SignInButton redirectUri="https://myapp.com/auth/callback">
Sign in with Clowk
</SignInButton>Hooks disponíveis
| Hook | Retorna | Descrição |
|---|---|---|
useAuth() | { user, token, signedIn, isLoading, signOut } | Estado e ações de autenticação |
useToken() | string | null | A string JWT bruta |
useClowk() | ClowkClient | Instância do cliente de API para chamadas ao backend |
Rotas protegidas
import { useAuth } from '@clowk/react'
import { Navigate } from 'react-router-dom'
function ProtectedRoute({ children }: { children: React.ReactNode }) {
const { signedIn, isLoading } = useAuth()
if (isLoading) return <div>Loading...</div>
if (!signedIn) return <Navigate to="/sign-in" />
return children
}Como funciona
O ClowkProvider procura um parâmetro de query ?token= ao montar. Quando encontra (depois do redirect de callback do OAuth), ele guarda o JWT, decodifica o usuário e limpa o parâmetro da URL. Nas próximas cargas, ele lê o token do cookie clowk_token.
Ruby on Rails
Guia completo de autenticação com Clowk no Ruby on Rails: configuração da gem clowk, credenciais por tenant, controllers protegidos, Hotwire e SDK client.
Next.js
Guia completo de autenticação com Clowk no Next.js: middleware para proteger rotas, auth() em Server Components e Route Handlers, e hooks React no cliente.