Remix / React Router v7 Framework Patterns

Quick Guide: Each route exports a loader for reads and an action for writes. Both run on the server. Data flows through loaders, mutations go through actions, forms work without JavaScript, and nested routes enable parallel data loading. json() and defer() are deprecated in React Router v7 -- return raw objects instead, use data() for custom headers/status.

<migration_notice>

IMPORTANT: React Router v7 Migration

Remix has merged into React Router v7. What was planned as Remix v3 is now React Router v7 "framework mode".

This skill covers both Remix v2 and React Router v7 patterns. Examples use Remix v2 imports by default with RR v7 equivalents documented in examples/react-router-v7.md.

Migration guide: Upgrading from Remix

</migration_notice>

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST export loaders and actions as named exports from route modules only -- they do not work in non-route files)

(You MUST throw Response objects for expected errors (404, 403) -- use ErrorBoundary for handling)

(You MUST await critical data and return non-critical data as Promises for streaming)

(You MUST use named constants for HTTP status codes -- no magic numbers)

</critical_requirements>

Auto-detection: Remix routes, React Router v7, loader function, action function, clientAction, clientLoader, useLoaderData, useActionData, useFetcher, defer, ErrorBoundary, Form component, meta function, links function, Single Fetch, ServerRouter, HydratedRouter, Route.LoaderArgs, Route.ComponentProps, shouldRevalidate

When to use:

• Building full-stack React applications with server-side rendering
• Implementing data loading with loaders and mutations with actions
• Creating progressively enhanced forms that work without JavaScript
• Streaming non-critical data with defer/Promises and Suspense
• Handling errors gracefully with route-level ErrorBoundary

When NOT to use:

• Static sites without server-side logic
• Simple SPAs without server rendering needs
• Projects already committed to a different meta-framework

Key patterns covered:

• File-based routing (routes/, _index, $params, _layout)
• Loaders for server-side data fetching
• Actions for mutations with progressive enhancement
• Streaming with defer() / raw Promises (RR v7)
• useFetcher for non-navigation mutations and optimistic UI
• Error boundaries with multi-status handling
• Meta and Links functions for SEO
• Resource routes (API endpoints, file downloads)
• Nested routing with parallel data loading
• React Router v7 migration (Single Fetch, type generation, clientAction)

Philosophy

Remix simplifies full-stack development to a single mental model: each route exports a loader for reads and an action for writes. Both functions execute exclusively on the server, enabling direct database access without exposing secrets to the client.

Core Principles:

1. Server-first data loading: Loaders run on the server before rendering, eliminating client-side data fetching waterfalls
2. Progressive enhancement: Forms work with plain POST requests -- JavaScript enhances but isn't required
3. HTTP semantics: Caching uses standard HTTP headers (Cache-Control), not framework-specific solutions
4. Nested routes: URL segments map to component hierarchy, enabling parallel data loading
5. Web standards: Uses Fetch API Request/Response objects throughout

Data Flow:

URL Change -> Loader(s) Execute -> Component Renders -> User Interacts
                                                            |
                                          Action Executes -> Loaders Revalidate

Core Patterns

Pattern 1: File-Based Routing

Files in app/routes/ become URL paths. File naming conventions control nesting, layouts, and dynamic segments.

// app/routes/blog.$slug.tsx -- dynamic route with loader
import type { LoaderFunctionArgs } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";

const HTTP_NOT_FOUND = 404;

export async function loader({ params }: LoaderFunctionArgs) {
  const post = await db.post.findUnique({ where: { slug: params.slug } });
  if (!post) throw new Response("Not Found", { status: HTTP_NOT_FOUND });
  return { post };
}

Why good: File names map directly to URLs, $ prefix for dynamic segments, loader params are typed, named constant for status code

See examples/core.md for complete route examples and examples/nested-routes.md for layout nesting patterns.

Pattern 2: Loaders for Data Fetching

Loaders are server-only functions that provide data to routes. They run on initial server render and on client navigation via fetch.

const HTTP_NOT_FOUND = 404;

export async function loader({ params, request }: LoaderFunctionArgs) {
  const user = await db.user.findUnique({ where: { id: params.userId } });
  if (!user) {
    throw json({ message: "User not found" }, { status: HTTP_NOT_FOUND });
  }
  return json({ user });
}

Key rules:

• Always throw Response for expected errors (triggers ErrorBoundary)
• Use useLoaderData<typeof loader>() for type-safe access (or Route.ComponentProps in RR v7)
• Loaders run on every navigation -- parent loaders re-run even for child route changes
• Use shouldRevalidate to optimize unnecessary re-runs

See examples/loaders.md for authentication, pagination, and caching examples.

Pattern 3: Actions for Mutations

Actions handle non-GET requests (POST, PUT, DELETE, PATCH). They run before loaders and enable progressive form handling.

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const intent = formData.get("intent");

  switch (intent) {
    case "update": {
      /* ... */ return json({ success: true });
    }
    case "dele