Skip to content
Clerk React Patterns

Clerk React Patterns Skill

Clerk's official skill for authentication in React single-page apps with @clerk/react on Vite or Create React App: ClerkProvider setup, useAuth, useUser and useClerk hooks, React Router protected routes and custom sign-in flows.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from clerk/skills.

$ npx skills add clerk/skills --skill clerk-react-patterns

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/clerk-react-patterns/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/clerk/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/clerk-react-patterns ~/.claude/skills/clerk-react-patterns

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/clerk-react-patterns/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • ClerkProvider setup for Vite and Create React App with VITE_CLERK_PUBLISHABLE_KEY
  • useAuth, useUser and useClerk hooks with the isLoaded guard
  • Protected routes for React Router v6 and v7
  • Custom sign-in and sign-up flows with useSignIn and useSignUp
  • Session JWTs for API calls via getToken() and a common-pitfalls table

Clerk React Patterns is Clerk's own skill, from the clerk/skills repository, for adding Clerk authentication to a client-only React single-page app built with Vite or Create React App. It is scoped tightly: Next.js projects are sent to clerk-nextjs-patterns and TanStack Start to clerk-tanstack-patterns.

The setup is spelled out end to end: install @clerk/react, put the publishable key in VITE_CLERK_PUBLISHABLE_KEY, and wrap the app in ClerkProvider in main.tsx. The skill's mental model is the part agents most often get wrong: @clerk/react is client-only, so there is no server-side auth(), all state comes from hooks, isLoaded must be true before isSignedIn can be trusted, useClerk() exposes signOut, openSignIn and openUserProfile, and getToken() from useAuth() fetches the session JWT for API calls.

It includes a minimal guarded component, a protected-route pattern for React Router v6 and v7, and a pitfalls table (undefined isSignedIn, a missing provider, the wrong Vite environment prefix, a null token, a blank sign-in component). Reference files go deeper on hooks, protected routes, custom sign-in and sign-up flows with useSignIn and useSignUp, and router integration. MIT licensed per its frontmatter.

SKILL.md

The instructions your agent loads, as published by Clerk.

SKILL.md
name
clerk-react-patterns
description
React SPA auth patterns with @clerk/react for Vite/CRA - ClerkProvider setup, useAuth/useUser/useClerk hooks, React Router protected routes, custom sign-in flows. Triggers on: Vite Clerk setup, React Router auth, useAuth hook, protected route, custom sign-in form React.
license
MIT
allowed-tools
WebFetch
metadata
author: clerk version: 1.0.0

React SPA Patterns

This skill covers @clerk/react for Vite/CRA SPAs. For Next.js use clerk-nextjs-patterns. For TanStack Start use clerk-tanstack-patterns.
What Do You Need?
TaskReference
useAuth / useUser / useClerk hooksreferences/hooks.md
Protected routes with React Routerreferences/protected-routes.md
Custom sign-in / sign-up formsreferences/custom-flows.md
React Router v6/v7 integrationreferences/router-integration.md
References
ReferenceDescription
references/hooks.mduseAuth, isLoaded guard
references/protected-routes.mdProtectedRoute pattern
references/custom-flows.mduseSignIn, useSignUp flows
references/router-integration.mdReact Router v6/v7 setup
Setup
npm install @clerk/react

.env:

VITE_CLERK_PUBLISHABLE_KEY=pk_...

src/main.tsx:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ClerkProvider } from '@clerk/react'
import App from './App.tsx'

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ClerkProvider publishableKey={PUBLISHABLE_KEY}>
      <App />
    </ClerkProvider>
  </StrictMode>,
)
Mental Model

@clerk/react is client-only — there is no server-side auth(). All auth state comes from hooks.

  • isLoaded must be true before trusting isSignedIn — always guard on isLoaded
  • useClerk() gives access to signOut, openSignIn, openUserProfile and other methods
  • getToken() from useAuth() fetches the session JWT for API calls
Minimal Pattern
import { useAuth } from '@clerk/react'

export function Dashboard() {
  const { isLoaded, isSignedIn, userId } = useAuth()

  if (!isLoaded) return <div>Loading...</div>
  if (!isSignedIn) return <div>Please sign in</div>

  return <div>Hello {userId}</div>
}
Protected Route (React Router v6/v7)
import { Navigate, Outlet } from 'react-router-dom'
import { useAuth } from '@clerk/react'

export function ProtectedRoute() {
  const { isLoaded, isSignedIn } = useAuth()

  if (!isLoaded) return <div>Loading...</div>
  if (!isSignedIn) return <Navigate to="/sign-in" replace />

  return <Outlet />
}
<Routes>
  <Route element={<ProtectedRoute />}>
    <Route path="/dashboard" element={<Dashboard />} />
    <Route path="/settings" element={<Settings />} />
  </Route>
  <Route path="/sign-in" element={<SignIn />} />
</Routes>
Token for API Calls
import { useAuth } from '@clerk/react'

export function DataFetcher() {
  const { getToken } = useAuth()

  async function fetchData() {
    const token = await getToken()
    if (!token) return

    const res = await fetch('/api/data', {
      headers: { Authorization: `Bearer ${token}` },
    })
    return res.json()
  }

  return <button onClick={fetchData}>Load</button>
}
Common Pitfalls
SymptomCauseFix
isSignedIn is undefinedisLoaded is still falseAlways check isLoaded first
ClerkProvider missingProvider not at rootWrap <App> in main.tsx
Env var undefinedWrong Vite prefixUse VITE_CLERK_PUBLISHABLE_KEY, access via import.meta.env
Token is nullUser not signed inNull-check getToken() result
Sign-in component shows blankNo publishableKey on providerPass publishableKey explicitly
See Also
  • clerk-setup - Initial Clerk install
  • clerk-custom-ui - Custom flows & appearance
  • clerk-orgs - B2B organizations
Docs

React SDK

Install
Browse all skills →