React Router v7 Complete Guide (2026): Framework Mode, Loaders & Actions

npx create-react-router@latest my-app
cd my-app
npm run dev

app/
  routes/
    home.tsx         ← /
    blog.tsx         ← /blog (layout)
    blog._index.tsx  ← /blog (index)
    blog.$slug.tsx   ← /blog/:slug
  root.tsx
react-router.config.ts
vite.config.ts

// react-router.config.ts
import type { Config } from '@react-router/dev/config'
export default { ssr: true } satisfies Config

home.tsx              → /
blog.tsx              → /blog (layout)
blog._index.tsx       → /blog (index inside layout)
blog.$slug.tsx        → /blog/:slug
blog.$slug.edit.tsx   → /blog/:slug/edit
_auth.tsx             → layout, no URL segment
_auth.login.tsx       → /login (inside _auth layout)
$.tsx                 → catch-all / 404

import { type RouteConfig, route, index, layout } from '@react-router/dev/routes'
export default [
  index('routes/home.tsx'),
  layout('routes/_auth.tsx', [
    route('login', 'routes/login.tsx'),
    route('signup', 'routes/signup.tsx'),
  ]),
] satisfies RouteConfig

// app/routes/blog.$slug.tsx
import { useLoaderData, redirect } from 'react-router'
import type { Route } from './+types/blog.$slug'
import { db } from '~/lib/db.server'
export async function loader({ params, request }: Route.LoaderArgs) {
  const post = await db.posts.findUnique({
    where: { slug: params.slug, published: true },
    include: { author: true }
  })
  if (!post) throw new Response('Not Found', { status: 404 })
  return { post }
}
export function meta({ data }: Route.MetaArgs) {
  return [
    { title: data?.post.title },
    { name: 'description', content: data?.post.excerpt }
  ]
}
export default function BlogPost() {
  const { post } = useLoaderData<typeof loader>()
  // post is fully typed — no manual type annotation needed
  return (
    <article>
      <h1>{post.title}</h1>
      <p>By {post.author.name}</p>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  )
}

// app/routes/(protected)/+layout.server.ts
export async function loader({ locals, url }: Route.LoaderArgs) {
  const session = await getSession(request)
  if (!session.userId) {
    throw redirect(`/login?next=${encodeURIComponent(url.pathname)}`)
  }
  return { user: session.user }
}

// app/routes/blog.$slug.edit.tsx
import { Form, useActionData, redirect } from 'react-router'
import { z } from 'zod'
import type { Route } from './+types/blog.$slug.edit'
const schema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1),
  published: z.coerce.boolean().default(false)
})
export async function action({ params, request }: Route.ActionArgs) {
  const { user } = await requireAuth(request)
  const formData = await request.formData()
  const parsed = schema.safeParse(Object.fromEntries(formData))
  if (!parsed.success) {
    return {
      errors: parsed.error.flatten().fieldErrors,
      values: Object.fromEntries(formData)
    }
  }
  const post = await db.posts.update({
    where: { slug: params.slug, authorId: user.id },
    data: parsed.data
  })
  throw redirect(`/blog/${post.slug}`)
}
export default function EditPost() {
  const { post } = useLoaderData<typeof loader>()
  const actionData = useActionData<typeof action>()
  return (
    <Form method="post">
      <input
        name="title"
        defaultValue={actionData?.values?.title ?? post.title}
      />
      {actionData?.errors?.title && (
        <p className="error">{actionData.errors.title[0]}</p>
      )}
      <button type="submit">Save</button>
    </Form>
  )
}

export async function action({ params, request }: Route.ActionArgs) {
  const formData = await request.formData()
  switch (formData.get('intent')) {
    case 'publish':
      await db.posts.update({ where: { slug: params.slug }, data: { published: true } })
      return { success: true }
    case 'delete':
      await db.posts.delete({ where: { slug: params.slug } })
      throw redirect('/blog')
    default:
      throw new Response('Invalid intent', { status: 400 })
  }
}

<Form method="post">
  <button name="intent" value="publish">Publish</button>
  <button name="intent" value="delete">Delete</button>
</Form>

import { useFetcher } from 'react-router'
function LikeButton({ postId, initialLikes, isLiked }: Props) {
  const fetcher = useFetcher()
  // Optimistic UI: read in-flight form data
  const optimisticLiked = fetcher.formData
    ? fetcher.formData.get('liked') === 'true'
    : isLiked
  const optimisticCount = fetcher.formData
    ? initialLikes + (optimisticLiked ? 1 : -1)
    : initialLikes
  return (
    <fetcher.Form method="post" action="/api/likes">
      <input type="hidden" name="postId" value={postId} />
      <input type="hidden" name="liked" value={String(!optimisticLiked)} />
      <button type="submit">
        {optimisticLiked ? '❤️' : '🤍'} {optimisticCount}
      </button>
    </fetcher.Form>
  )
}

import { useRouteError, isRouteErrorResponse } from 'react-router'
export function ErrorBoundary() {
  const error = useRouteError()
  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>{error.status} {error.statusText}</h1>
        <p>{error.data}</p>
      </div>
    )
  }
  return (
    <div>
      <h1>Something went wrong</h1>
      <p>{error instanceof Error ? error.message : 'Unknown error'}</p>
    </div>
  )
}

npm install @react-router/serve @vercel/react-router  # Vercel
npm install @react-router/express                     # Node.js
npm install @react-router/cloudflare                  # Cloudflare Workers

// react-router.config.ts — Vercel
import { vercelPreset } from '@vercel/react-router/vite'
export default { ssr: true, presets: [vercelPreset()] } satisfies Config

// server.ts
import { createRequestHandler } from '@react-router/express'
import express from 'express'
import * as build from './build/server/index.js'
const app = express()
app.use(express.static('build/client'))
app.all('*', createRequestHandler({ build }))
app.listen(3000)

// v6
import { BrowserRouter, Routes, Route } from 'react-router-dom'
function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/blog/:slug" element={<BlogPost />} />
      </Routes>
    </BrowserRouter>
  )
}
// v7 library mode
import { createBrowserRouter, RouterProvider } from 'react-router'
const router = createBrowserRouter([
  { path: '/', element: <Home /> },
  { path: '/blog/:slug', element: <BlogPost /> }
])
function App() { return <RouterProvider router={router} /> }

npm install react-router @react-router/node @react-router/serve
npm uninstall @remix-run/react @remix-run/node @remix-run/serve

// Before
import { json, redirect, useLoaderData } from '@remix-run/react'
import type { LoaderFunctionArgs } from '@remix-run/node'
// After
import { redirect, useLoaderData } from 'react-router'
import type { Route } from './+types/your-route'
// Before: return json({ user })
// After: return { user }

// Auto-generated: app/routes/+types/blog.$slug.ts
export namespace Route {
  export interface LoaderArgs {
    request: Request
    params: { slug: string }  // typed from filename, never undefined
  }
  export type LoaderData = Awaited<ReturnType<typeof loader>>
}