Skills

Skill 13 of 22

Clerk React Router Patterns

React Router v7/v8 patterns with Clerk — rootAuthLoader, getAuth in loaders, clerkMiddleware, protected routes, SSR user data, org switching.

2 minutes · 420 words · 16 sections

Install

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

$ npx skills add clerk/skills

» /plugin marketplace add clerk/skills

The first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.

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

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 from the upstream React Router issue (opens in a new tab):

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

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

2. root.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>
  )
}

There is no ClerkApp HOC in @clerk/react-router (that was the @clerk/remix API). Render <ClerkProvider loaderData={loaderData}> inside the default export and pass it the root route’s loaderData.

3. react-router.config.ts (v7 only)

import type { Config } from '@react-router/dev/config'

export default {
  future: {
    v8_middleware: true,
  },
} satisfies Config

On v8, omit the future block entirely — the flag no longer exists.

Required: rootAuthLoader must be called in root.tsx‘s loader. Without it, getAuth throws in nested loaders.

Mental Model

React Router v7/v8 uses a middleware + loader pipeline. Clerk plugs into both layers:

Middleware (clerkMiddleware()) — runs on every request, attaches auth to context
rootAuthLoader — required in root.tsx to pass Clerk state to the client
getAuth(args) — called inside any loader/action to get the current user

Request → clerkMiddleware() → rootAuthLoader → page loader → component
                 ↓                   ↓               ↓
           attaches auth      injects state     getAuth(args)
           to context         to response       reads context

Auth in Loaders

import { getAuth } from '@clerk/react-router/server'
import type { Route } from './+types/dashboard'

export async function loader(args: Route.LoaderArgs) {
  const { userId } = await getAuth(args)
  if (!userId) throw redirect('/sign-in')

  const data = await fetchUserData(userId)
  return { data }
}

Auth in Actions

import { getAuth } from '@clerk/react-router/server'

export async function action(args: Route.ActionArgs) {
  const { userId, orgId } = await getAuth(args)
  if (!userId) throw new Response('Unauthorized', { status: 401 })

  const formData = await args.request.formData()
  await saveData(userId, orgId, formData)
  return redirect('/dashboard')
}

Client Components

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

export function Profile() {
  const { userId, isSignedIn } = useAuth()
  const { user } = useUser()
  if (!isSignedIn) return null
  return <p>{user?.firstName}</p>
}

Org Switching

import { OrganizationSwitcher } from '@clerk/react-router'

export function Nav() {
  return <OrganizationSwitcher afterSelectOrganizationUrl="/dashboard" />
}

export async function loader(args: Route.LoaderArgs) {
  const { userId, orgId } = await getAuth(args)
  if (!userId) throw redirect('/sign-in')
  if (!orgId) throw redirect('/select-org')

  return { data: await fetchOrgData(orgId) }
}

Common Pitfalls

Symptom	Cause	Fix
`useNavigate() may be used only in the context of a <Router>` thrown from ClerkProvider during SSR in dev (v8)	Vite dev SSR externalizes `@clerk/react-router`, which then loads react-router’s production build while the app uses the development build — two Router contexts. A single copy in `npm ls` does not rule this out.	Add `ssr: { noExternal: ['@clerk/react-router'] }` to `vite.config.ts`. Do NOT downgrade to v7
Build error: `ClerkApp` is not exported	`ClerkApp` does not exist in `@clerk/react-router`	Use `<ClerkProvider loaderData={loaderData}>` in root.tsx’s default export
`clerkMiddleware() not detected`	Missing middleware (or on v7, missing `v8_middleware` future flag)	Export `middleware = [clerkMiddleware()]` from root route; on v7 also set `future: { v8_middleware: true }`
Unknown future flag error/warning (v8)	`v8_middleware` flag left in `react-router.config.ts` after upgrading	Remove the `future.v8_middleware` entry — middleware is always on in v8
`getAuth` returns empty userId	`rootAuthLoader` not called	Call `rootAuthLoader(args)` in `root.tsx` loader
Infinite redirect loop	Redirect target is also protected	Exclude `/sign-in` from protection check
`redirect` not working in action	Using `Response` instead of `throw redirect()`	Use `throw redirect('/path')` from `react-router`

Import Map

What	Import From
`getAuth`	`@clerk/react-router/server`
`rootAuthLoader`	`@clerk/react-router/server`
`clerkMiddleware`	`@clerk/react-router/server`
`ClerkProvider`	`@clerk/react-router`
`useAuth`, `useUser`	`@clerk/react-router`
`OrganizationSwitcher`	`@clerk/react-router`

Docs

React Router SDK (opens in a new tab)

About this skill

Trigger

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.

The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.

Allowed tools: WebFetch
Licence: MIT
Source: skills/clerk-react-router-patterns/SKILL.md

Colophon for this issue

Colophon

How this issue was made

Source

github.com/clerk/skills, branch main, last pushed 6 November 2026.

Licence

Discovery

22 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. 2 distinct layouts observed: .agents/skills/*/SKILL.md, skills/*/SKILL.md.

Authorship

2 of 22 skills are installed into the repository rather than published from it. They are shelved in the closing “Credited skills” part and remain the work of their own authors. A skill counts as credited when its only copy lives under one agent’s dot directory; visible directories, per-agent mirror sets, and skills installable from this repository on skills.sh all count as published.

Issue colours

Resolved from the owner’s published design.md — hue 284°, chroma 0.190. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Typefaces

Display: Suisse Intl is not available to us; set in Inter.
Body: Suisse Intl is not available to us; set in Inter.
Mono: Söhne Mono is not available to us; set in JetBrains Mono.

We never load a typeface at request time from a third-party origin, so a brand face we do not already self-host is substituted rather than fetched.

Heading repairs

1 repair applied to this skill so the document has one h1 and no skipped levels:

Shifted “16 headings” from h1 to h2 so the skill title is the only h1.

Spec compliance

Every skill satisfies the Agent Skills specification’s frontmatter rules.

Images

Images inside a skill come from the upstream repository. Where the author gave no alternative text we mark the image decorative rather than inventing a description — a plausible caption we made up is worse than none for the reader who depends on it.

Marketplace

A plugin manifest is published at .claude-plugin/marketplace.json by Clerk, declaring 1 plugin. It is read for editorial metadata only — never as the skill index, which is always the repository tree.

Signal

Install counts come from skills.sh. They measure downloads, not quality, and an unranked repository is not an unread one.

Agent surfaces

The whole issue is available as one markdown document at /clerk/skills.md, and each skill at its own .md URL.

Publication

Set by Skills Docs from the source repository. Body text is Literata at the reader’s chosen size and measure; code is Geist Mono. Nothing on this page was written by us except this paragraph.

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)

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

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

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

2. root.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>
  )
}

3. react-router.config.ts (v7 only)

import type { Config } from '@react-router/dev/config'

export default {
  future: {
    v8_middleware: true,
  },
} satisfies Config

On v8, omit the future block entirely — the flag no longer exists.

Required: rootAuthLoader must be called in root.tsx‘s loader. Without it, getAuth throws in nested loaders.

Mental Model

React Router v7/v8 uses a middleware + loader pipeline. Clerk plugs into both layers:

Middleware (clerkMiddleware()) — runs on every request, attaches auth to context
rootAuthLoader — required in root.tsx to pass Clerk state to the client
getAuth(args) — called inside any loader/action to get the current user

Request → clerkMiddleware() → rootAuthLoader → page loader → component
                 ↓                   ↓               ↓
           attaches auth      injects state     getAuth(args)
           to context         to response       reads context

Auth in Loaders

import { getAuth } from '@clerk/react-router/server'
import type { Route } from './+types/dashboard'

export async function loader(args: Route.LoaderArgs) {
  const { userId } = await getAuth(args)
  if (!userId) throw redirect('/sign-in')

  const data = await fetchUserData(userId)
  return { data }
}

Auth in Actions

import { getAuth } from '@clerk/react-router/server'

export async function action(args: Route.ActionArgs) {
  const { userId, orgId } = await getAuth(args)
  if (!userId) throw new Response('Unauthorized', { status: 401 })

  const formData = await args.request.formData()
  await saveData(userId, orgId, formData)
  return redirect('/dashboard')
}

Client Components

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

export function Profile() {
  const { userId, isSignedIn } = useAuth()
  const { user } = useUser()
  if (!isSignedIn) return null
  return <p>{user?.firstName}</p>
}

Org Switching

import { OrganizationSwitcher } from '@clerk/react-router'

export function Nav() {
  return <OrganizationSwitcher afterSelectOrganizationUrl="/dashboard" />
}

export async function loader(args: Route.LoaderArgs) {
  const { userId, orgId } = await getAuth(args)
  if (!userId) throw redirect('/sign-in')
  if (!orgId) throw redirect('/select-org')

  return { data: await fetchOrgData(orgId) }
}

Common Pitfalls

Symptom	Cause	Fix
`useNavigate() may be used only in the context of a <Router>` thrown from ClerkProvider during SSR in dev (v8)	Vite dev SSR externalizes `@clerk/react-router`, which then loads react-router’s production build while the app uses the development build — two Router contexts. A single copy in `npm ls` does not rule this out.	Add `ssr: { noExternal: ['@clerk/react-router'] }` to `vite.config.ts`. Do NOT downgrade to v7
Build error: `ClerkApp` is not exported	`ClerkApp` does not exist in `@clerk/react-router`	Use `<ClerkProvider loaderData={loaderData}>` in root.tsx’s default export
`clerkMiddleware() not detected`	Missing middleware (or on v7, missing `v8_middleware` future flag)	Export `middleware = [clerkMiddleware()]` from root route; on v7 also set `future: { v8_middleware: true }`
Unknown future flag error/warning (v8)	`v8_middleware` flag left in `react-router.config.ts` after upgrading	Remove the `future.v8_middleware` entry — middleware is always on in v8
`getAuth` returns empty userId	`rootAuthLoader` not called	Call `rootAuthLoader(args)` in `root.tsx` loader
Infinite redirect loop	Redirect target is also protected	Exclude `/sign-in` from protection check
`redirect` not working in action	Using `Response` instead of `throw redirect()`	Use `throw redirect('/path')` from `react-router`

Import Map

What	Import From
`getAuth`	`@clerk/react-router/server`
`rootAuthLoader`	`@clerk/react-router/server`
`clerkMiddleware`	`@clerk/react-router/server`
`ClerkProvider`	`@clerk/react-router`
`useAuth`, `useUser`	`@clerk/react-router`
`OrganizationSwitcher`	`@clerk/react-router`

Docs

React Router SDK (opens in a new tab)

About this skill

Trigger

Colophon

Appendix 13.1–13.11

ReferencesMarkdown · 3 files

Assets7 files

Also bundledJSON · 1 file

About this skill

Trigger

Colophon

Appendix 13.1–13.11

ReferencesMarkdown · 3 files

Assets7 files

Also bundledJSON · 1 file