foxlau/react-router-better-auth / .agents/skills/react-router-framework-mode
react-router-framework-mode
VerifiedBuild full-stack React applications using React Router's framework mode. Use when configuring routes, working with loaders and actions, handling forms, handling navigation, pending/optimistic UI, error boundaries, or working with react-router.config.ts or other react router conventions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.5 KB |
| references/actions.md | markdown | 8.9 KB |
| references/data-loading.md | markdown | 3.8 KB |
| references/error-handling.md | markdown | 4.5 KB |
| references/middleware.md | markdown | 6.6 KB |
| references/navigation.md | markdown | 4.1 KB |
| references/pending-ui.md | markdown | 6.8 KB |
| references/rendering-strategies.md | markdown | 3.8 KB |
| references/route-modules.md | markdown | 8.5 KB |
| references/routing.md | markdown | 6.0 KB |
| references/sessions.md | markdown | 10.2 KB |
| references/special-files.md | markdown | 12.2 KB |
| references/type-safety.md | markdown | 4.1 KB |
references/middleware.md
View on GitHub---
title: Middleware & Context API
description: Server and client middleware, context API for sharing data
tags: [middleware, context, authentication, logging, request-processing]
requires: [react-router@7.9.0+, v8_middleware: true]
---
# Middleware & Context API
## ⚠️ Version Requirements - Check First!
**Before implementing middleware, verify your React Router version:**
```bash
npm list react-router
```
| Feature | Minimum Version | Config Flag Required |
| ---------- | --------------- | --------------------- |
| Middleware | 7.9.0+ | `v8_middleware: true` |
**If your version is below 7.9.0:**
- Middleware is not available
- Use loaders/actions for request processing instead
- Or upgrade: `npm install react-router@latest`
### Enabling Middleware
```ts
// react-router.config.ts
import type { Config } from "@react-router/dev/config";
export default {
future: {
v8_middleware: true, // Required for middleware
},
} satisfies Config;
```
See https://reactrouter.com/how-to/middleware#changes-to-getloadcontextapploadcontext for migration instructions.
## Overview
Middleware runs code before and after response generation. Executes in a nested chain: parent → child on the way down, child → parent on the way up.
```
Root middleware start
Parent middleware start
Child middleware start
→ Run loaders, generate Response
Child middleware end
Parent middleware end
Root middleware end
```
## Basic Middleware
```tsx
import type { Route } from "./+types/dashboard";
import { redirect } from "react-router";
async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
const user = await getUserFromSession(request);
if (!user) {
throw redirect("/login");
}
context.set(userContext, user);
}
export const middleware: Route.MiddlewareFunction[] = [authMiddleware];
```
### The `next` Function
Call `next()` to continue the chain and get the response:
```tsx
async function loggingMiddleware(
{ request }: Route.MiddlewareArgs,
next: Route.MiddlewareNext,
) {
console.log(`→ ${request.method} ${request.url}`);
const response = await next();
console.log(`← ${response.status}`);
return response;
}
```
- Call `next()` only once
- If you don't need post-processing, skip calling `next()` (called automatically)
- `next()` never throws—errors return as error responses
## Context API
Create typed context to share data between middleware and loaders/actions:
```tsx
// app/context.ts
import { createContext } from "react-router";
export const userContext = createContext<User | null>(null);
export const dbContext = createContext<Database>();
```
### Setting Context in Middleware
```tsx
import { userContext } from "~/context";
async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
const user = await getUser(request);
context.set(userContext, user);
}
export const middleware: Route.MiddlewareFunction[] = [authMiddleware];
```
### Reading Context in Loaders/Actions
```tsx
import { userContext } from "~/context";
export async function loader({ context }: Route.LoaderArgs) {
const user = context.get(userContext);
return { profile: await getProfile(user) };
}
export async function action({ context }: Route.ActionArgs) {
const user = context.get(userContext);
// user is available here too
}
```
## Server vs Client Middleware
**Server middleware** (`middleware`) runs on document requests and `.data` fetches:
```tsx
export const middleware: Route.MiddlewareFunction[] = [
async ({ request, context }, next) => {
// Runs on server
const response = await next();
return response;
},
];
```
**Client middleware** (`clientMiddleware`) runs on client-side navigations:
```tsx
export const clientMiddleware: Route.ClientMiddlewareFunction[] = [
async ({ context }, next) => {
// Runs in browser
const start = performance.now();
await next();
console.log(`Navigation: ${performance.now() - start}ms`);
},
];
```
## When Server Middleware Runs
| Request Type | Middleware Runs? |
| -------------------------------- | --------------------- |
| Document request (`GET /route`) | Always |
| Client navigation with loader | Yes (`.data` request) |
| Client navigation without loader | No |
To force middleware on routes without loaders, add an empty loader:
```tsx
export const middleware: Route.MiddlewareFunction[] = [authMiddleware];
export async function loader() {
return null;
}
```
## Common Patterns
### Authentication
```tsx
async function authMiddleware({ request, context }: Route.MiddlewareArgs) {
const session = await getSession(request);
if (!session.get("userId")) {
throw redirect("/login");
}
context.set(userContext, await getUserById(session.get("userId")));
}
```
### Request Logging
```tsx
async function loggingMiddleware(
{ request }: Route.MiddlewareArgs,
next: Route.MiddlewareNext,
) {
const id = crypto.randomUUID();
const start = performance.now();
console.log(`[${id}] ${request.method} ${request.url}`);
const response = await next();
console.log(`[${id}] ${response.status} (${performance.now() - start}ms)`);
return response;
}
```
### Response Headers
```tsx
async function securityHeaders(
_: Route.MiddlewareArgs,
next: Route.MiddlewareNext,
) {
const response = await next();
response.headers.set("X-Frame-Options", "DENY");
response.headers.set("X-Content-Type-Options", "nosniff");
return response;
}
```
### 404 Fallback
```tsx
async function cmsFallback(
{ request }: Route.MiddlewareArgs,
next: Route.MiddlewareNext,
) {
const response = await next();
if (response.status === 404) {
const redirect = await checkCmsRedirects(request.url);
if (redirect) throw redirect(redirect, 302);
}
return response;
}
```
### Conditional Execution
```tsx
export const middleware: Route.MiddlewareFunction[] = [
async ({ request, context }, next) => {
if (request.method === "POST") {
await requireAuth(request, context);
}
return next();
},
];
```
## Error Handling
Errors bubble to the nearest `ErrorBoundary`. The `next()` function always returns a response (never throws):
```tsx
export const middleware: Route.MiddlewareFunction[] = [
async (_, next) => {
const response = await next();
// response.status = 500 if child threw
// Can still set headers, commit sessions, etc.
return response;
},
];
```
- Error **before** `next()`: Bubbles to highest route with a loader
- Error **after** `next()`: Bubbles from the throwing route
## See Also
- [React Router Middleware Documentation](https://reactrouter.com/how-to/middleware)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |