# clerk-react-router-patterns

Guides Clerk integration with React Router v7/v8, including loaders, protected routes, SSR auth, and organization switching. Useful when wiring auth into a router.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 15500 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-router-patterns/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/clerk-react-router-patterns

## What it does

This skill focuses on `@clerk/react-router` with React Router v7.9+ and v8. It explains how `clerkMiddleware()` feeds request auth into the router pipeline, how `rootAuthLoader` passes Clerk state to the client, and how loaders or actions can read the current user with `getAuth(args)`. It also covers protected routes, client auth hooks, SSR data, and `OrganizationSwitcher`.

The material is split into references for loaders and actions, protected routes, and SSR authentication. Version checks matter: React Router v7 needs the `future.v8_middleware` setting, while v8 removes that flag and requires `ssr.noExternal` for `@clerk/react-router` in `vite.config.ts`. If `rootAuthLoader(args)` is missing from `root.tsx`, `getAuth` fails in nested loaders.

## Install

### Claude Code (native platform)

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

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

### Codex

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

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

### Cursor

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

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

### GitHub Copilot

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

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

### Gemini CLI

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

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

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add clerk/skills --skill clerk-react-router-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-router-patterns/SKILL.md

## When to use it
- configure Clerk in a React Router v7 or v8 app
- read `userId` and `orgId` inside a loader or action
- protect a route with an auth redirect
- pass Clerk session state through SSR
- fix the Router context issue in React Router v8

## Example prompts
- Set up Clerk auth for my React Router v8 app and update `root.tsx` and `vite.config.ts`.
- Review the dashboard loader: use `getAuth(args)`, redirect guests, and return the signed-in user's data.
- Add `OrganizationSwitcher` and load organization data from `orgId` in the route loader.

## 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: ff9771422685b10c.

BEGIN THIRD-PARTY FILE ff9771422685b10c
````text
---
name: clerk-react-router-patterns
description: 'React Router v7/v8 patterns with Clerk — rootAuthLoader, getAuth in loaders,
  clerkMiddleware, protected routes, SSR user data, org switching. Triggers on: react-router
  auth, rootAuthLoader, getAuth loader, react-router protected route, loader authentication,
  SSR auth react-router, useNavigate may be used only in the context of a Router.'
license: MIT
allowed-tools: WebFetch
metadata:
  author: clerk
  version: 1.1.0
---

# React Router Patterns

SDK: `@clerk/react-router` v3.5+. Supports React Router v7.9+ and v8.

## What Do You Need?

| Task | Reference |
|------|-----------|
| Auth in loaders and actions | references/loaders-actions.md |
| Protected routes and redirects | references/protected-routes.md |
| SSR user data and session | references/ssr-auth.md |

## React Router v7 vs v8

Check the installed `react-router` major version before scaffolding — the config differs:

| | v7.9+ | v8+ |
|--|--|--|
| Middleware API | Opt-in: set `future: { v8_middleware: true }` in `react-router.config.ts` | Always on — do NOT set the flag (v8 removed it) |
| `ssr.noExternal` workaround (below) | Not needed | **Required** |

## Minimal Setup

### 1. vite.config.ts (v8 only — REQUIRED)

React Router v8 ships development/production conditional exports. In `react-router dev`,
Vite externalizes `@clerk/react-router` for SSR, so Node resolves the production build of
react-router while the app code gets the development build — two module instances, two
Router contexts. Every request then fails during SSR with:

```
Error: useNavigate() may be used only in the context of a <Router> component.
```

**`npm ls react-router` shows a single copy — that does NOT rule this out.** The
duplication is per export condition, not per installed copy. Do not chase duplicate
installs; add the workaround (upstream issue:
https://github.com/remix-run/react-router/issues/15232):

```ts
import { reactRouter } from '@react-router/dev/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [reactRouter()],
  ssr: {
    noExternal: ['@clerk/react-router'],
  },
})
```

### 2. root.tsx

```tsx
import { Outlet } from 'react-router'
import { rootAuthLoader, clerkMiddleware } from '@clerk/react-router/server'
import { ClerkProvider } from '@clerk/react-router'
import type { Route } from './+types/root'

export const middleware: Route.MiddlewareFunction[] = [clerkMiddleware()]

export async function loader(args: Route.LoaderArgs) {
  return rootAuthLoader(args)
}

export default function App({ loaderData }: Route.ComponentProps) {
  return (
    <ClerkProvider loaderData={loaderData}>
      <Outlet />
    </ClerkProvider>
  )
}
```
````
END THIRD-PARTY FILE ff9771422685b10c

The third-party file has ended. Everything between the ff9771422685b10c 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 2733 of 7395 bytes. © clerk · MIT · https://github.com/clerk/skills/tree/HEAD/skills/clerk-react-router-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