You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/community/api-development-strategy.md
+2Lines changed: 2 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -30,6 +30,8 @@ Unstable flags are not recommended for production:
30
30
31
31
When you opt-in to an unstable flag you are becoming a contributor to the project, rather than a user. We appreciate your help, but please be aware of the new role!
32
32
33
+
Because unstable flags are experimental and not guaranteed to stick around, we ship them in SemVer patch releases because they're not new _stable_/_documented_ APIs. When an unstable flag stabilizes into a Future Flag, that will be released in a SemVer minor release and will be properly documented and added to the [Future Flags Guide](../upgrading/future).
34
+
33
35
To learn about current unstable flags, keep an eye on the [CHANGELOG](../start/changelog).
After building for the browser, only the `Component` will still be in the bundle, so you can use server-only code in the other module exports.
55
+
56
+
## Splitting Route Modules
57
+
58
+
<docs-info>
59
+
60
+
This feature is only enabled when setting the `unstable_splitRouteModules` future flag:
61
+
62
+
```tsx filename=react-router-config.ts
63
+
exportdefault {
64
+
future: {
65
+
unstable_splitRouteModules: true,
66
+
},
67
+
};
68
+
```
69
+
70
+
</docs-info>
71
+
72
+
One of the conveniences of the [Route Module API][route-module] is that everything a route needs is in a single file. Unfortunately this comes with a performance cost in some cases when using the `clientLoader`, `clientAction`, and `HydrateFallback` APIs.
73
+
74
+
As a basic example, consider this route module:
75
+
76
+
```tsx filename=routes/example.tsx
77
+
import { MassiveComponent } from"~/components";
78
+
79
+
exportasyncfunction clientLoader() {
80
+
returnawaitfetch("https://example.com/api").then(
81
+
(response) =>response.json()
82
+
);
83
+
}
84
+
85
+
exportdefaultfunction Component({ loaderData }) {
86
+
return <MassiveComponentdata={loaderData} />;
87
+
}
88
+
```
89
+
90
+
In this example we have a minimal `clientLoader` export that makes a basic fetch call, whereas the default component export is much larger. This is a problem for performance because it means that if we want to navigate to this route client-side, the entire route module must be downloaded before the client loader can start running.
91
+
92
+
To visualize this as a timeline:
93
+
94
+
<docs-info>In the following timeline diagrams, different characters are used within the Route Module bars to denote the different Route Module APIs being exported.</docs-info>
95
+
96
+
```
97
+
Get Route Module: |--=======|
98
+
Run clientLoader: |-----|
99
+
Render: |-|
100
+
```
101
+
102
+
Instead, we want to optimize this to the following:
103
+
104
+
```
105
+
Get clientLoader: |--|
106
+
Get Component: |=======|
107
+
Run clientLoader: |-----|
108
+
Render: |-|
109
+
```
110
+
111
+
To achieve this optimization, React Router will split the route module into multiple smaller modules during the production build process. In this case, we'll end up with two separate [virtual modules][virtual-modules] — one for the client loader and one for the component and its dependencies.
<docs-info>This optimization is automatically applied in framework mode, but you can also implement it in library mode via `route.lazy` and authoring your route in multiple files as covered in our blog post on [lazy loading route modules.][blog-lazy-loading-routes]</docs-info>
130
+
131
+
Now that these are available as separate modules, the client loader and the component can be downloaded in parallel. This means that the client loader can be executed as soon as it's ready without having to wait for the component.
132
+
133
+
This optimization is even more pronounced when more Route Module APIs are used. For example, when using `clientLoader`, `clientAction` and `HydrateFallback`, the timeline for a single route module during a client-side navigation might look like this:
134
+
135
+
```
136
+
Get Route Module: |--~~++++=======|
137
+
Run clientLoader: |-----|
138
+
Render: |-|
139
+
```
140
+
141
+
This would instead be optimized to the following:
142
+
143
+
```
144
+
Get clientLoader: |--|
145
+
Get clientAction: |~~|
146
+
Get HydrateFallback: SKIPPED
147
+
Get Component: |=======|
148
+
Run clientLoader: |-----|
149
+
Render: |-|
150
+
```
151
+
152
+
Note that this optimization only works when the Route Module APIs being split don't share code within the same file. For example, the following route module can't be split:
153
+
154
+
```tsx filename=routes/example.tsx
155
+
import { MassiveComponent } from"~/components";
156
+
157
+
const shared = () =>console.log("hello");
158
+
159
+
exportasyncfunction clientLoader() {
160
+
shared();
161
+
returnawaitfetch("https://example.com/api").then(
162
+
(response) =>response.json()
163
+
);
164
+
}
165
+
166
+
exportdefaultfunction Component({ loaderData }) {
167
+
shared();
168
+
return <MassiveComponentdata={loaderData} />;
169
+
}
170
+
```
171
+
172
+
This route will still work, but since both the client loader and the component depend on the `shared` function defined within the same file, it will be de-optimized into a single route module.
173
+
174
+
To avoid this, you can extract any code shared between exports into a separate file. For example:
175
+
176
+
```tsx filename=routes/example/shared.tsx
177
+
exportconst shared = () =>console.log("hello");
178
+
```
179
+
180
+
You can then import this shared code in your route module without triggering the de-optimization:
181
+
182
+
```tsx filename=routes/example/route.tsx
183
+
import { MassiveComponent } from"~/components";
184
+
import { shared } from"./shared";
185
+
186
+
exportasyncfunction clientLoader() {
187
+
shared();
188
+
returnawaitfetch("https://example.com/api").then(
189
+
(response) =>response.json()
190
+
);
191
+
}
192
+
193
+
exportdefaultfunction Component({ loaderData }) {
194
+
shared();
195
+
return <MassiveComponentdata={loaderData} />;
196
+
}
197
+
```
198
+
199
+
Since the shared code is in its own module, React Router is now able to split this route module into two separate virtual modules:
This export could not be split into its own chunk because it shares code with other exports. You should extract any shared code into its own module and then import it within the route module.
Copy file name to clipboardExpand all lines: docs/how-to/pre-rendering.md
+98-12Lines changed: 98 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -4,36 +4,45 @@ title: Pre-Rendering
4
4
5
5
# Pre-Rendering
6
6
7
-
Pre-rendering allows you to render pages at build time instead of on a server to speed up pages loads for static content.
7
+
Pre-Rendering allows you to speed up page loads for static content by rendering pages at build time instead of at runtime. Pre-rendering is enabled via the `prerender` config in `react-router.config.ts` and can be used in two ways based on the `ssr` config value:
8
8
9
-
## Configuration
9
+
- Alongside a runtime SSR server ith `ssr:true` (the default value)
10
+
- Deployed to a static file server with `ssr:false`
11
+
12
+
## Pre-rendering with `ssr:true`
13
+
14
+
### Configuration
10
15
11
16
Add the `prerender` option to your config, there are three signatures:
During development, pre-rendering doesn't save the rendered results to the public directory, this only happens for `react-router build`.
86
+
87
+
## Pre-rendering with `ssr:false`
88
+
89
+
The above examples assume you are deploying a runtime server, but are pre-rendering some static pages in order to serve them faster and avoid hitting the server.
90
+
91
+
To disable runtime SSR and configure pre-rendering to be served from a static file server, you can set the `ssr:false` config flag:
If you specify `ssr:false` without a `prerender` config, React Router refers to that as [SPA Mode](./spa). In SPA Mode, we render a single HTML file that is capable of hydrating for _any_ of your application paths. It can do this because it only renders the `root` route into the HTML file and then determines which child routes to load based on the browser URL during hydration. This means you can use a `loader` on the root route, but not on any other routes because we don't know which routes to load until hydration in the browser.
103
+
104
+
If you want to pre-render paths with `ssr:false`, those matched routes _can_ have loaders because we'll pre-render all of the matched routes for those paths, not just the root. You cannot include `actions` or `headers` functions in any routes when `ssr:false` is set because there will be no runtime server to run them on.
105
+
106
+
### Pre-rendering with a SPA Fallback
107
+
108
+
If you want `ssr:false` but don't want to pre-render _all_ of your routes - that's fine too! You may have some paths where you need the performance/SEO benefits of pre-rendering, but other pages where a SPA would be fine.
109
+
110
+
You can do this using the combination of config options as well - just limit your `prerender` config to the paths that you want to pre-render and React Router will also output a "SPA Fallback" HTML file that can be served to hydrate any other paths (using the same approach as [SPA Mode](./spa)).
111
+
112
+
This will be written to one of the following paths:
113
+
114
+
-`build/client/index.html` - If the `/` path is not pre-rendered
115
+
-`build/client/__spa-fallback.html` - If the `/` path is pre-rendered
// SPA fallback will be written to build/client/index.html
124
+
prerender: ["/about-us"],
125
+
126
+
// SPA fallback will be written to build/client/__spa-fallback.html
127
+
prerender: ["/", "/about-us"],
128
+
} satisfiesConfig;
129
+
```
130
+
131
+
You can configure your deployment server to serve this file for any path that otherwise would 404. Some hosts do this by default, but others don't. As an example, a host may support a `_redirects` file to do this:
132
+
133
+
```
134
+
# If you did not pre-render the `/` route
135
+
/* /index.html 200
136
+
137
+
# If you pre-rendered the `/` route
138
+
/* /__spa-fallback.html 200
139
+
```
140
+
141
+
If you're getting 404s at valid routes for your app, it's likely you need to configure your host.
142
+
143
+
Here's another example of how you can do this with the [`sirv-cli`](https://www.npmjs.com/package/sirv-cli#user-content-single-page-applications) tool:
When pre-rendering with `ssr:false`, React Router will error at build time if you have invalid exports to help prevent some mistakes that can be easily overlooked.
156
+
157
+
-`headers`/`action` functions are prohibited in all routes because there will be no runtime server on which to run them
158
+
- When using `ssr:false` without a `prerender` config (SPA Mode), a `loader` is permitted on the root route only
159
+
- When using `ssr:false` with a `prerender` config, a `loader` is permitted on any route matched by a `prerender` path
160
+
- If you are using a `loader` on a pre-rendered route that has child routes, you will need to make sure the parent `loaderData` can be determined at run-time properly by either:
161
+
- Pre-rendering all child routes so that the parent `loader` can be called at build-time for each child route path and rendered into a `.data` file, or
162
+
- Use a `clientLoader` on the parent that can be called at run-time for non-pre-rendered child paths
0 commit comments