|
1 | 1 | --- |
2 | | -title: Docs Home |
3 | | -toc: false |
| 2 | +title: React Router Home |
4 | 3 | order: 1 |
5 | 4 | --- |
6 | 5 |
|
7 | | -# Welcome to React Router |
8 | | - |
9 | | -<docs-cards> |
10 | | - <a href="dev/getting-started/data"> |
11 | | - <docs-card> |
12 | | - <h3>Ready for Data?</h3> |
13 | | - <p>v6.4 brings over all the things we've learned about keeping your data in sync with your UI from Remix to React Router. Developing web apps has never been this fun. Get started with data here.</p> |
14 | | - </docs-card> |
15 | | - </a> |
16 | | - <a href="dev/getting-started/tutorial"> |
17 | | - <docs-card> |
18 | | - <h3>New to React Router?</h3> |
19 | | - <p>We suggest you start with the tutorial. It's got everything you need to know to get up and running in React Router quickly.</p> |
20 | | - </docs-card> |
21 | | - </a> |
22 | | - <a href="dev/getting-started/overview"> |
23 | | - <docs-card> |
24 | | - <h3>Familiar with React Router?</h3> |
25 | | - <p>We introduced several new features and exciting changes in version 6. Learn all about them in this quick overview of the features that make v6 special.</p> |
26 | | - </docs-card> |
27 | | - </a> |
28 | | - <a href="dev/getting-started/faq"> |
29 | | - <docs-card> |
30 | | - <h3>Frequently Asked Questions</h3> |
31 | | - <p>Running into a problem? Chances are, you're not the first! Explore some of the questions that people commonly have about React Router v6.</p> |
32 | | - </docs-card> |
33 | | - </a> |
34 | | -</docs-cards> |
35 | | - |
36 | | -## Previous Versions |
37 | | - |
38 | | -- [React Router v4/5 docs](https://v5.reactrouter.com) |
39 | | -- [React Router v3 docs](https://github.com/remix-run/react-router/tree/v3.2.6/docs) |
| 6 | +# React Router Home |
| 7 | + |
| 8 | +React Router is a multi-strategy router for React. You can use it maximally as a React framework or minimally as a library with your own architecture. |
| 9 | + |
| 10 | +- [Getting Started - Framework](./framework/start/installation) |
| 11 | +- [Getting Started - Library](./library/installation) |
| 12 | + |
| 13 | +If you are caught up on future flags, upgrading from React Router v6 or Remix is generally non-breaking: |
| 14 | + |
| 15 | +- [Upgrade from v6](./upgrading/v6) |
| 16 | +- [Upgrade from Remix](./upgrading/remix) |
| 17 | + |
| 18 | +## React Router as a Library |
| 19 | + |
| 20 | +Like previous versions, React Router can still be used as a simple, declarative routing library. Its only job will be matching the URL to a set of components, providing access to URL data, and navigating around the app. |
| 21 | + |
| 22 | +This strategy is popular for "Single Page Apps" that have their own frontend infrastructure and v6 apps looking for a stress free upgrade. |
| 23 | + |
| 24 | +It's particularly good at offline + sync architectures where pending states are rare and users have long running sessions. Framework features like pending states, code splitting, server rendering, SEO, and initial page load times can be traded out for instant local-first interactions. |
| 25 | + |
| 26 | +```tsx |
| 27 | +ReactDOM.createRoot(root).render( |
| 28 | + <BrowserRouter> |
| 29 | + <Routes> |
| 30 | + <Route path="/" element={<Home />} /> |
| 31 | + <Route path="dashboard" element={<Dashboard />}> |
| 32 | + <Route index element={<RecentActivity />} /> |
| 33 | + <Route path="project/:id" element={<Project />} /> |
| 34 | + </Route> |
| 35 | + </Routes> |
| 36 | + </BrowserRouter> |
| 37 | +); |
| 38 | +``` |
| 39 | + |
| 40 | +[Get Started](./library/installation) with React Router as a library. |
| 41 | + |
| 42 | +## React Router as a framework |
| 43 | + |
| 44 | +React Router can be used maximally as your React framework. In this setup, you'll use the React Router CLI and Vite bundler plugin for a full-stack development and deployment architecture. This enables React Router to provide a large set of features most web projects will want, including: |
| 45 | + |
| 46 | +- Vite bundler and dev server integration |
| 47 | +- hot module replacement |
| 48 | +- code splitting |
| 49 | +- route conventions with type safety |
| 50 | +- file system or config-based routing |
| 51 | +- data loading with type safety |
| 52 | +- actions with type safety |
| 53 | +- automatic revalidation of page data after actions |
| 54 | +- SSR, SPA, and static rendering strategies |
| 55 | +- APIs for pending states and optimistic UI |
| 56 | +- deployment adapters |
| 57 | + |
| 58 | +Routes are configured with `routes.ts` which enables React Router to do a lot for you. For example, it will automatically code-split each route, provide type safety for the parameters and data, and automatically load the data with access to pending states as the user navigates to it. |
| 59 | + |
| 60 | +```ts |
| 61 | +import { |
| 62 | + type RouteConfig, |
| 63 | + route, |
| 64 | + index, |
| 65 | + layout, |
| 66 | + prefix, |
| 67 | +} from "@react-router/dev/routes"; |
| 68 | + |
| 69 | +export const routes: RouteConfig = [ |
| 70 | + index("./home.tsx"), |
| 71 | + route("about", "./about.tsx"), |
| 72 | + |
| 73 | + layout("./auth/layout.tsx", [ |
| 74 | + route("login", "./auth/login.tsx"), |
| 75 | + route("register", "./auth/register.tsx"), |
| 76 | + ]), |
| 77 | + |
| 78 | + ...prefix("concerts", [ |
| 79 | + index("./concerts/home.tsx"), |
| 80 | + route(":city", "./concerts/city.tsx"), |
| 81 | + route(":city/:id", "./concerts/show.tsx") |
| 82 | + route("trending", "./concerts/trending.tsx"), |
| 83 | + ]), |
| 84 | +]; |
| 85 | +``` |
| 86 | + |
| 87 | +You'll have access to the Route Module API, which most of the other features are built on. |
| 88 | + |
| 89 | +Loaders provide data to route components: |
| 90 | + |
| 91 | +```tsx |
| 92 | +// loaders provide data to components |
| 93 | +export async function loader({ params }: Route.LoaderArgs) { |
| 94 | + const [show, isLiked] = await Promise.all([ |
| 95 | + fakeDb.find("show", params.id), |
| 96 | + fakeIsLiked(params.city), |
| 97 | + ]); |
| 98 | + return { show, isLiked }; |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +Components render at their configured URLs from routes.ts with the loader data passed in as a prop: |
| 103 | + |
| 104 | +```tsx |
| 105 | +export default function Show({ |
| 106 | + loaderData, |
| 107 | +}: Route.ComponentProps) { |
| 108 | + const { show, isLiked } = loaderData; |
| 109 | + return ( |
| 110 | + <div> |
| 111 | + <h1>{show.name}</h1> |
| 112 | + <p>{show.description}</p> |
| 113 | + |
| 114 | + <form method="post"> |
| 115 | + <button |
| 116 | + type="submit" |
| 117 | + name="liked" |
| 118 | + value={isLiked ? 0 : 1} |
| 119 | + > |
| 120 | + {isLiked ? "Remove" : "Save"} |
| 121 | + </button> |
| 122 | + </form> |
| 123 | + </div> |
| 124 | + ); |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +Actions can update data and trigger a revalidation of all data on |
| 129 | +the page so your UI stays up to date automatically: |
| 130 | + |
| 131 | +```tsx |
| 132 | +export async function action({ |
| 133 | + request, |
| 134 | + params, |
| 135 | +}: Route.LoaderArgs) { |
| 136 | + const formData = await request.formData(); |
| 137 | + await fakeSetLikedShow(formData.get("liked")); |
| 138 | + return { ok: true }; |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +Route modules also provide conventions for SEO, asset loading, error boundaries, and more. |
| 143 | + |
| 144 | +[Get Started](./framework/start/installation) with React Router as a framework. |
0 commit comments