/web-meta-framework-remix

name: web-meta-framework-remix
description: File-based routing, loaders, actions, defer streaming, useFetcher, error boundaries, progressive enhancement

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".

| Remix v2 (Deprecated) | React Router v7 (Current) | | --------------------------------- | ------------------------------------------------ | | `json(data)` | Return raw objects directly | | `json(data, { status, headers })` | `data(data, { status, headers })` | | `defer({ key: promise })` | Return `{ key: promise }` with Single Fetch | | `@remix-run/node` imports | `react-router` / `@react-router/node` | | `LoaderFunctionArgs` | `Route.LoaderArgs` (generated types) | | `ActionFunctionArgs` | `Route.ActionArgs` (generated types) | | `useLoaderData<typeof loader>()` | `loaderData` prop via `Route.ComponentProps` | | `RemixServer` | `ServerRouter` (from `react-router`) | | `RemixBrowser` | `HydratedRouter` (from `react-router/dom`) | | File-based routing (automatic) | `routes.ts` + optional `@react-router/fs-routes` |

**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](examples/react-router-v7.md).

**Migration guide:** [Upgrading from Remix](https://reactrouter.com/upgrading/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>

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

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: File-Based Routing

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

| File Name | URL | Description | | ----------------- | ------------- | ----------------------------- | | `_index.tsx` | `/` | Index route (root) | | `about.tsx` | `/about` | Static route | | `blog.$slug.tsx` | `/blog/:slug` | Dynamic parameter | | `blog_.tsx` | `/blog` | Pathless layout escape | | `_auth.tsx` | (none) | Layout route (no URL segment) | | `_auth.login.tsx` | `/login` | Route nested in layout | | `$.tsx`