# clerk-react-patterns

Provides authentication patterns for React single-page apps using @clerk/react in Vite and CRA. It helps implement route guards, session hooks, and custom forms.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 19700 installs · ★ 89
- Author: clerk
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/clerk/skills/tree/HEAD/skills/clerk-react-patterns/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/clerk-react-patterns

## What it does

The skill provides patterns for integrating `@clerk/react` into client-side single-page applications. It details wrapping the root component in `ClerkProvider`, configuring `VITE_CLERK_PUBLISHABLE_KEY`, and fetching session JWTs via `getToken()` for backend calls.

Inside, you get reference implementations for `useAuth`, `useUser`, and `useClerk`, along with custom login flows and route protection using React Router v6 or v7. The library runs strictly in the browser, meaning there is no server-side `auth()` helper available.

Because auth state resolves asynchronously, code must verify `isLoaded` before reading `isSignedIn` to avoid undefined checks. If your app relies on Next.js or TanStack Start, this skill is the wrong choice — Clerk maintains separate skill packages for those frameworks.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add clerk/skills --skill clerk-react-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/clerk-react-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/clerk-react-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add clerk/skills --skill clerk-react-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/clerk-react-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add clerk/skills --skill clerk-react-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/clerk-react-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install clerk/skills clerk-react-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/clerk-react-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add clerk/skills --skill clerk-react-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/clerk/skills --path skills/clerk-react-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/clerk-react-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add clerk/skills --skill clerk-react-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/clerk/skills/tree/HEAD/skills/clerk-react-patterns/SKILL.md

## When to use it
- protect routes in React Router v6 and v7
- configure ClerkProvider in Vite and Create React App
- retrieve JWT bearer tokens for API requests using useAuth
- build custom sign-in and sign-up flows with Clerk hooks

## Example prompts
- Set up ClerkProvider for my Vite app and protect the /dashboard route
- Show how to safely check auth state with useAuth before calling an API
- Create a custom sign-in form using the useSignIn hook

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 68fb98892247f93b.

BEGIN THIRD-PARTY FILE 68fb98892247f93b
````text
---
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?

| Task | Reference |
|------|-----------|
| useAuth / useUser / useClerk hooks | references/hooks.md |
| Protected routes with React Router | references/protected-routes.md |
| Custom sign-in / sign-up forms | references/custom-flows.md |
| React Router v6/v7 integration | references/router-integration.md |

## References

| Reference | Description |
|-----------|-------------|
| `references/hooks.md` | useAuth, isLoaded guard |
| `references/protected-routes.md` | ProtectedRoute pattern |
| `references/custom-flows.md` | useSignIn, useSignUp flows |
| `references/router-integration.md` | React Router v6/v7 setup |

## Setup

```
npm install @clerk/react
```

`.env`:
```
VITE_CLERK_PUBLISHABLE_KEY=pk_...
```

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

```tsx
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)

```tsx
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 />
}
```

```tsx
<Routes>
  <Route element={<ProtectedRoute />}>
    <Route path="/dashboard" element={<Dashboard />} />
    <Route path="/settings" element={<Settings />} />
  </Route>
````
END THIRD-PARTY FILE 68fb98892247f93b

The third-party file has ended. Everything between the 68fb98892247f93b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2936 of 4162 bytes. © clerk · MIT · https://github.com/clerk/skills/tree/HEAD/skills/clerk-react-patterns/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md