+ );
+}
+```
+
+## Protected Routes
+
+React Router 7 supports route-level authentication using loaders. Protected routes can access user data directly from context:
+
+### Creating a Protected Route
+
+Create a protected route that gets user data from context:
+
+```tsx app/routes/protected._index.tsx
+import { data, redirect, Outlet } from "react-router";
+import type { Route, MetaFunction } from "react-router";
+import { userContext } from "@civic/auth/react-router-7";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Protected Page - Civic Auth Demo" }];
+};
+
+export function loader({ context }: Route.LoaderArgs) {
+ // Get user from context (set by middleware)
+ const user = context.get(userContext);
+
+ if (!user) {
+ // Redirect to home page if user is not authenticated
+ return redirect("/");
+ }
+
+ return data({ user });
+}
+
+export default function ProtectedPage() {
+ return (
+
+
+
+ );
+}
+```
+
+### Protected Route Layout
+
+Create the protected route content that displays to authenticated users:
+
+```tsx app/routes/protected.tsx
+import { Link } from "react-router";
+import type { MetaFunction } from "react-router";
+import { useUser } from "@civic/auth/react-router-7/useUser";
+
+export const meta: MetaFunction = () => {
+ return [{ title: "Protected Page - Civic Auth Demo" }];
+};
+
+export default function ProtectedLayout() {
+ const { user } = useUser();
+
+ return (
+
+
+
Protected Page
+
+
+
Welcome to this protected page, {user?.name || "User"}!
+
This content is only visible to authenticated users.
+
+
+
+
+ Back to Home
+
+
+ Logout
+
+
+
+
+ );
+}
+```
+
+### How It Works
+
+1. **Centralized Auth**: Middleware handles authentication once per request before any loaders
+2. **Context Storage**: User data is stored in React Router context for all routes to access
+3. **Route Protection**: Protected route loaders get user data from context
+4. **Redirect Logic**: If no user is found in context, it redirects to the home page
+5. **Performance**: More efficient as authentication logic runs only once per request
+
+### Alternative Protection Patterns
+
+#### Reusable Protection Utilities
+
+```tsx app/utils/requireAuth.ts
+import { redirect } from "react-router";
+import { userContext } from "@civic/auth/react-router-7";
+
+export function requireAuth(context: any) {
+ const user = context.get(userContext);
+
+ if (!user) {
+ throw redirect("/auth/login");
+ }
+
+ // Additional admin-specific checks can go here
+ if (!isUserAdmin(user.email)) {
+ throw redirect("/");
+ }
+
+ return user;
+}
+```
+
+Then use it in any protected route:
+
+```tsx app/routes/admin.tsx
+import type { Route } from "react-router";
+import { requireAuth } from "~/utils/requireAuth";
+
+export function loader({ context }: Route.LoaderArgs) {
+ const user = requireAuth(context);
+
+ return { user };
+}
+```
+
+## Benefits of Middleware Approach
+
+1. **Performance**: Authentication logic runs only once per request instead of in every loader
+2. **Centralization**: All auth logic is centralized, similar to Next.js middleware
+3. **Token Refresh**: Handles token refresh globally before any route processing
+4. **Clean Separation**: Routes focus on their specific logic rather than auth concerns
+5. **Consistency**: User data is always available and consistent across all routes
+
+## Advanced Configuration
+
+Civic Auth is a "low-code" solution, so most configuration takes place via the [dashboard](https://auth.civic.com). Changes you make there will be updated automatically in your integration without any code changes.
+
+You can customize the library according to your React Router 7 app's needs. Configure options when calling `createRouteHandlers`:
+
+### Middleware Configuration
+
+Configure options in your `app/root.tsx` file:
+
+```tsx app/root.tsx
+import { authMiddleware } from "@civic/auth/react-router-7";
+
+export const unstable_middleware = [
+ authMiddleware({
+ clientId: "YOUR_CLIENT_ID",
+ loginSuccessUrl: "/myCustomSuccessEndpoint",
+ callbackUrl: "/api/myroute/callback",
+ logoutUrl: "/goodbye",
+ baseUrl: "https://myapp.com",
+ }),
+];
+```
+
+### Configuration Options
+
+| Field | Required | Default | Example | Description |
+| ----------------- | -------- | ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clientId` | Yes | - | `2cc5633d-2c92-48da-86aa-449634f274b9` | The key obtained on signup to [auth.civic.com](https://auth.civic.com/) |
+| `loginSuccessUrl` | No | - | `/myCustomSuccessEndpoint` | In a React Router 7 app, we will redirect your user to this page once the login is finished. If not set, users will be sent back to the root of your app. |
+| `callbackUrl` | No | `/auth/callback` | `/api/myroute/callback` | If you cannot host Civic’s SDK handlers in the default location, you can specify a custom callback route here. This is where you must attach Civic’s GET handler as described above, so Civic can complete the OAuth token exchange. Use `loginSuccessUrl` to redirect after login. |
+| `logoutUrl` | No | `/` | `/goodbye` | The path your user will be sent to after a successful log-out. |
+| `baseUrl` | No | - | `https://myapp.com` | The public-facing base URL for your application. Required when deploying behind reverse proxies (Cloudfront + Vercel, AWS ALB, nginx, etc.) to ensure authentication redirects use the correct public domain instead of internal origins. |