Como adicionar autenticação a um aplicativo React com Clerk em 2026

Criar autenticação do zero é complexo e sujeito a erros: fluxos de inscrição, redefinição de senha, login social, gerenciamento de sessão e segurança. Escriturário lida com tudo isso com componentes React drop-in. Este guia adiciona autenticação completa a um aplicativo React de forma rápida e segura.

Por que usar o escriturário?

• Componentes de UI pré-construídos: Componentes de login, inscrição e perfil de usuário prontos para uso
• Login social integrado: Google, GitHub e muito mais com configuração mínima
• Lida com as partes difíceis: Sessões, redefinição de senha, verificação de e-mail, MFA
• Seguro por padrão: Segue as práticas recomendadas de segurança que você não precisa implementar
• Gerenciamento de usuários: Um painel para visualizar e gerenciar usuários

Configuração

npm install @clerk/clerk-react

# Create an app at clerk.com, get your publishable key, add to .env
VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxx

Prepare seu aplicativo com ClerkProvider

// main.jsx
import { ClerkProvider } from '@clerk/clerk-react';

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

ReactDOM.createRoot(document.getElementById('root')).render(
  <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
    <App />
  </ClerkProvider>
);

Adicionar login e inscrição

import {
  SignedIn, SignedOut, SignInButton, SignUpButton, UserButton
} from '@clerk/clerk-react';

function Header() {
  return (
    <header>
      <SignedOut>
        {/* Shown only when signed OUT */}
        <SignInButton />
        <SignUpButton />
      </SignedOut>

      <SignedIn>
        {/* Shown only when signed IN - includes profile/sign-out menu */}
        <UserButton />
      </SignedIn>
    </header>
  );
}

Páginas completas de login/inscrição

import { SignIn, SignUp } from '@clerk/clerk-react';

// Dedicated sign-in page with the full Clerk UI
function SignInPage() {
  return <SignIn routing="path" path="/sign-in" />;
}

function SignUpPage() {
  return <SignUp routing="path" path="/sign-up" />;
}
// These render complete, styled auth flows with social login,
// password reset, email verification - all handled for you

Protegendo Rotas

import { SignedIn, SignedOut, RedirectToSignIn } from '@clerk/clerk-react';

function ProtectedPage() {
  return (
    <>
      <SignedIn>
        {/* Protected content - only for signed-in users */}
        <Dashboard />
      </SignedIn>
      <SignedOut>
        {/* Redirect signed-out users to sign in */}
        <RedirectToSignIn />
      </SignedOut>
    </>
  );
}

Acessando dados do usuário

import { useUser, useAuth } from '@clerk/clerk-react';

function Profile() {
  const { isLoaded, isSignedIn, user } = useUser();

  if (!isLoaded) return <div>Loading...</div>;
  if (!isSignedIn) return <div>Not signed in</div>;

  return (
    <div>
      <h1>Hello, {user.firstName}!</h1>
      <p>Email: {user.primaryEmailAddress?.emailAddress}</p>
      <img src={user.imageUrl} alt="avatar" />
    </div>
  );
}

Chamando seu back-end com tokens de autenticação

import { useAuth } from '@clerk/clerk-react';

function useApi() {
  const { getToken } = useAuth();

  const callApi = async (endpoint) => {
    const token = await getToken();   // Clerk session token
    const res = await fetch(endpoint, {
      headers: { Authorization: `Bearer ${token}` },
    });
    return res.json();
  };

  return { callApi };
}
// Your backend verifies the Clerk token to authenticate the request

Verificação de back-end (Node.js)

npm install @clerk/backend

import { verifyToken } from '@clerk/backend';

async function authenticate(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'No token' });

  try {
    const payload = await verifyToken(token, {
      secretKey: process.env.CLERK_SECRET_KEY,
    });
    req.userId = payload.sub;   // Clerk user ID
    next();
  } catch {
    res.status(401).json({ error: 'Invalid token' });
  }
}

Perguntas Frequentes

P: Escriturário vs. construir autenticação sozinho?
R: O Clerk lida com as partes complexas e críticas de segurança (sessões, redefinição de senha, verificação de e-mail, MFA, login social) com componentes pré-construídos — economizando tempo significativo e reduzindo riscos de segurança. Construir você mesmo a autenticação oferece controle total, mas requer a implementação e proteção correta de todos esses fluxos. Para a maioria dos aplicativos, Clerk (ou similar) é a escolha pragmática.

P: Escriturário vs NextAuth vs Supabase Auth?
R: O Clerk oferece os componentes de UI pré-construídos e gerenciamento de usuários mais sofisticados. NextAuth (Auth.js) é ótimo para Next.js e flexibilidade auto-hospedada. Supabase Auth emparelha com um backend Supabase. Todos são sólidos – Clerk é excelente em UI e DX drop-in; escolha com base em sua pilha e se deseja conveniência hospedada ou controle auto-hospedado.

P: Como protejo rotas de API de back-end?
R: Obtenha o token de sessão do Clerk no frontend comgetToken(), envie-o como um token de portador e verifique-o em seu back-end com@clerk/backendé verificarToken. O token verificado fornece o ID do usuário para autorizar solicitações. Este é o fluxo padrão baseado em token.

P: O Clerk oferece suporte para login social?
R: Sim — Google, GitHub e muitos outros provedores com configuração mínima. Habilite-os no painel do Clerk e os componentes de login/inscrição mostram automaticamente as opções de login social. Nenhuma implementação manual do OAuth é necessária.

P: O funcionário é gratuito?
R: O Clerk tem um nível gratuito adequado para muitos aplicativos, com níveis pagos para maior uso e recursos avançados. Verifique os preços atuais para a contagem de usuários esperada. Para aplicativos iniciais e de pequeno a médio porte, o nível gratuito geralmente é suficiente.

Conclusão

Clerk torna a adição de autenticação a um aplicativo React rápida e segura, lidando com partes complexas – sessões, redefinição de senha, verificação de e-mail, MFA e login social – com componentes drop-in. O fluxo de trabalho:envolva seu aplicativo em ClerkProvider, use componentes SignedIn/SignedOut para mostrar a UI correta, adicione páginas SignIn/SignUp, proteja rotas com SignedIn + RedirectToSignIn, acesse dados do usuário com useUser e verifique tokens Clerk em seu backend. Você obtém um sistema de autenticação completo e seguro com interface de usuário sofisticada em uma fração do tempo que levaria para criá-lo sozinho e sem o risco de segurança de implementar fluxos de autenticação manualmente. Para a maioria dos aplicativos React que precisam de autenticação, o Clerk (ou um provedor de autenticação gerenciado semelhante) permite que você se concentre nos recursos reais do seu aplicativo em vez de reinventar a autenticação segura.