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:

src/main.tsx
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

PropTipoDescrição
publishableKeystringSua publishable key do Clowk
secretKeystringSecret key (só no servidor)
tokenParamstringNome do parâmetro de query do token (padrão: "token")
afterSignOutPathstringCaminho de redirect após sair (padrão: "/")

Acessar o usuário

Use o hook useAuth:

src/App.tsx
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

src/App.tsx
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

HookRetornaDescrição
useAuth(){ user, token, signedIn, isLoading, signOut }Estado e ações de autenticação
useToken()string | nullA string JWT bruta
useClowk()ClowkClientInstância do cliente de API para chamadas ao backend

Rotas protegidas

src/components/ProtectedRoute.tsx
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.

Nesta página