Overview
Remix is a full-stack web framework built on web standards: nested routing, loader/action data patterns, progressive enhancement, and error boundaries that isolate failures to one route segment. Forms work without JavaScript and nested route loaders run in parallel.
Know which "Remix" you are in before writing code:
- Remix v2 (
@remix-run/*packages) is the React framework most existing apps use. Its features were merged into React Router v7 (November 2024) as "framework mode", and the team recommends upgrading. New React projects should start on React Router, not Remix v2. - Remix 3 (
remixpackage,npx remix new) is a different, new framework: it is not built on React and uses its own component runtime and router. Its release candidate appeared on 2026-08-31 and a stable release was scheduled for 2026-10-02. Its API is not compatible with the loader/action code below.
The patterns in this skill (loader, action, Form, fetchers, error boundaries) apply to Remix v2 and React Router framework mode. Check package.json first: @remix-run/* means v2, react-router plus @react-router/dev means framework mode, remix alone means Remix 3.
Instructions
- Routes: file-based nested routing; each route module holds the UI and its data layer, with
<Outlet />for children and pathless layouts for shared UI. In React Router v7 routes are declared inapp/routes.ts(flat-file conventions are available through@react-router/fs-routes). - Loaders: server-side
loaderfunctions; nested loaders run in parallel, so there is no client-server waterfall. In Remix v2 with single fetch, and in React Router v7, return plain objects (anddata()for status codes or headers) rather thanjson();defer()is replaced by returning promises, rendered with<Suspense>and<Await>. Useredirect()to redirect. - Actions:
actionfunctions triggered by<Form method="post">; return validation errors with a 400 status and rely on automatic revalidation of every active loader afterwards. - UX:
useFetcher()for mutations that should not navigate (like buttons, inline edits),useNavigation()for pending state,fetcher.formDatafor optimistic UI. - Errors: export an
ErrorBoundaryper route and useisRouteErrorResponse()to tell thrown responses (404, 403) from unexpected errors. - Sessions:
createCookieSessionStorage()with asecretsarray from the environment; redirect from the loader when unauthenticated. Remix has no built-in CSRF protection: validate theOriginheader or add a token for state-changing actions. - Types (v7): import
type { Route } from "./+types/<module>"and annotateRoute.LoaderArgs,Route.ActionArgs,Route.ComponentProps; runreact-router typegen(also part ofnpm run typecheck). - Deploy: Vite is the compiler. Remix v2 adapters:
@remix-run/node,@remix-run/cloudflare,@remix-run/deno. React Router v7:@react-router/node,@react-router/cloudflare,@react-router/serve.
Migrating Remix v2 to React Router v7
npx codemod remix/2/react-router/upgrade && npm install
npm run typecheck && npm run build
- Enable all Remix v2 future flags first and make the app work.
- Run the community codemod shown above (it covers most of steps 3 to 5).
- Package mapping:
@remix-run/reacttoreact-router,@remix-run/nodeto@react-router/node,@remix-run/devto@react-router/dev. - Scripts become
react-router dev,react-router build,react-router-serve build/server/index.js. - Add
app/routes.tsandreact-router.config.ts(ssr: true), swapremix()forreactRouter()from@react-router/dev/vite, renameRemixServertoServerRouterandRemixBrowsertoHydratedRouter(fromreact-router/dom), and add.react-router/to.gitignore.
Examples
Example 1: Task manager with progressive enhancement
User request: "Create a route that lists tasks and lets me add one with a form that works without JavaScript."
// app/routes/tasks.tsx (React Router framework mode)
import { data, Form } from "react-router";
import type { Route } from "./+types/tasks";
import { createTask, listTasks } from "~/models/task.server";
export async function loader() {
return { tasks: await listTasks() };
}
export async function action({ request }: Route.ActionArgs) {
const form = await request.formData();
const title = String(form.get("title") ?? "").trim();
if (!title) return data({ error: "Title is required" }, { status: 400 });
await createTask({ title });
return { ok: true };
}
export default function Tasks({ loaderData, actionData }: Route.ComponentProps) {
return (
<>
<ul>{loaderData.tasks.map((t) => <li key={t.id}>{t.title}</li>)}</ul>
<Form method="post">
<input name="title" />
{actionData && "error" in actionData && <p>{actionData.error}</p>}
<button type="submit">Add task</button>
</Form>
</>
);
}
Result: submitting with JavaScript disabled does a normal POST and re-renders the list; with JavaScript it submits via fetch and revalidates the loader without a full reload.
Example 2: Upgrade an existing Remix v2 app
User request: "Move our Remix 2 app to React Router 7."
Run the codemod and the commands from the migration steps. A typical leftover fix, a like button that must not navigate:
const fetcher = useFetcher();
<fetcher.Form method="post" action="/posts/42/like">
<button type="submit">{fetcher.formData ? "Liked" : "Like"}</button>
</fetcher.Form>
Result: imports come from react-router, scripts call react-router, and remaining errors are mostly json()/defer() calls to replace with plain returns and useLoaderData call sites to move to loaderData props (or keep the hook).
Guidelines
- Fetch initial page data in
loader, notuseEffectplusfetch. - Use
<Form>rather than<form onSubmit>so the page works before hydration. - Return real status codes (400, 403, 404) from loaders and actions.
- Put
ErrorBoundaryon every route that can fail so one child does not take the page down. - Stream slow, non-critical data by returning promises instead of awaiting them.
- Keep server-only code in
*.server.tsfiles; the build removesloaderandactionfrom client bundles, but imports they share do not get removed unless they are server modules. - Do not start new work on Remix v2 or mix
@remix-run/*withreact-routerpackages; pick one. - Do not apply this skill's code to Remix 3, which has its own APIs; read its documentation instead.