Skip to content

Commit 71be3d6

Browse files
markdalgleishmarkdalgleish
authored
Move Split Route Modules docs to release notes (#13160)
1 parent ec722ee commit 71be3d6

File tree

2 files changed

+176
-188
lines changed

2 files changed

+176
-188
lines changed

‎CHANGELOG.md

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -407,6 +407,182 @@ In order to use your build-time loader data during pre-rendering, we now also ex
407407
- `@react-router/dev` - Add unstable support for splitting route modules in framework mode via `future.unstable_splitRouteModules` ([#11871](https://github.com/remix-run/react-router/pull/11871))
408408
- `@react-router/dev` - Add `future.unstable_viteEnvironmentApi` flag to enable experimental Vite Environment API support ([#12936](https://github.com/remix-run/react-router/pull/12936))
409409

410+
#### Split Route Modules (unstable)
411+
412+
> ⚠️ This feature is currently [unstable](https://reactrouter.com/community/api-development-strategy#unstable-flags), enabled by the `future.unstable_splitRouteModules` flag. We’d love any interested users to play with it locally and provide feedback, but we do not recommend using it in production yet.
413+
>
414+
> If you do choose to adopt this flag in production, please ensure you do sufficient testing against your production build to ensure that the optimization is working as expected.
415+
416+
One of the conveniences of the [Route Module API](https://reactrouter.com/start/framework/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.
417+
418+
As a basic example, consider this route module:
419+
420+
```tsx filename=routes/example.tsx
421+
import { MassiveComponent } from "~/components";
422+
423+
export async function clientLoader() {
424+
return await fetch("https://example.com/api").then((response) =>
425+
response.json()
426+
);
427+
}
428+
429+
export default function Component({ loaderData }) {
430+
return <MassiveComponent data={loaderData} />;
431+
}
432+
```
433+
434+
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.
435+
436+
To visualize this as a timeline:
437+
438+
<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>
439+
440+
```
441+
Get Route Module: |--=======|
442+
Run clientLoader: |-----|
443+
Render: |-|
444+
```
445+
446+
Instead, we want to optimize this to the following:
447+
448+
```
449+
Get clientLoader: |--|
450+
Get Component: |=======|
451+
Run clientLoader: |-----|
452+
Render: |-|
453+
```
454+
455+
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](https://vite.dev/guide/api-plugin#virtual-modules-convention) — one for the client loader and one for the component and its dependencies.
456+
457+
```tsx filename=routes/example.tsx?route-chunk=clientLoader
458+
export async function clientLoader() {
459+
return await fetch("https://example.com/api").then((response) =>
460+
response.json()
461+
);
462+
}
463+
```
464+
465+
```tsx filename=routes/example.tsx?route-chunk=main
466+
import { MassiveComponent } from "~/components";
467+
468+
export default function Component({ loaderData }) {
469+
return <MassiveComponent data={loaderData} />;
470+
}
471+
```
472+
473+
> 💡 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.](https://remix.run/blog/lazy-loading-routes#advanced-usage-and-optimizations)
474+
475+
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.
476+
477+
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:
478+
479+
```
480+
Get Route Module: |--~~++++=======|
481+
Run clientLoader: |-----|
482+
Render: |-|
483+
```
484+
485+
This would instead be optimized to the following:
486+
487+
```
488+
Get clientLoader: |--|
489+
Get clientAction: |~~|
490+
Get HydrateFallback: SKIPPED
491+
Get Component: |=======|
492+
Run clientLoader: |-----|
493+
Render: |-|
494+
```
495+
496+
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:
497+
498+
```tsx filename=routes/example.tsx
499+
import { MassiveComponent } from "~/components";
500+
501+
const shared = () => console.log("hello");
502+
503+
export async function clientLoader() {
504+
shared();
505+
return await fetch("https://example.com/api").then((response) =>
506+
response.json()
507+
);
508+
}
509+
510+
export default function Component({ loaderData }) {
511+
shared();
512+
return <MassiveComponent data={loaderData} />;
513+
}
514+
```
515+
516+
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.
517+
518+
To avoid this, you can extract any code shared between exports into a separate file. For example:
519+
520+
```tsx filename=routes/example/shared.tsx
521+
export const shared = () => console.log("hello");
522+
```
523+
524+
You can then import this shared code in your route module without triggering the de-optimization:
525+
526+
```tsx filename=routes/example/route.tsx
527+
import { MassiveComponent } from "~/components";
528+
import { shared } from "./shared";
529+
530+
export async function clientLoader() {
531+
shared();
532+
return await fetch("https://example.com/api").then((response) =>
533+
response.json()
534+
);
535+
}
536+
537+
export default function Component({ loaderData }) {
538+
shared();
539+
return <MassiveComponent data={loaderData} />;
540+
}
541+
```
542+
543+
Since the shared code is in its own module, React Router is now able to split this route module into two separate virtual modules:
544+
545+
```tsx filename=routes/example/route.tsx?route-chunk=clientLoader
546+
import { shared } from "./shared";
547+
548+
export async function clientLoader() {
549+
shared();
550+
return await fetch("https://example.com/api").then((response) =>
551+
response.json()
552+
);
553+
}
554+
```
555+
556+
```tsx filename=routes/example/route.tsx?route-chunk=main
557+
import { MassiveComponent } from "~/components";
558+
import { shared } from "./shared";
559+
560+
export default function Component({ loaderData }) {
561+
shared();
562+
return <MassiveComponent data={loaderData} />;
563+
}
564+
```
565+
566+
If your project is particularly performance sensitive, you can set the `unstable_splitRouteModules` future flag to `"enforce"`:
567+
568+
```tsx filename=react-router-config.ts
569+
export default {
570+
future: {
571+
unstable_splitRouteModules: "enforce",
572+
},
573+
};
574+
```
575+
576+
This setting will raise an error if any route modules can't be split:
577+
578+
```
579+
Error splitting route module: routes/example/route.tsx
580+
581+
- clientLoader
582+
583+
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.
584+
```
585+
410586
### Changes by Package
411587

412588
- [`create-react-router`](https://github.com/remix-run/react-router/blob/react-router%407.2.0/packages/create-react-router/CHANGELOG.md#720)

‎docs/explanation/code-splitting.md

Lines changed: 0 additions & 188 deletions
Original file line numberDiff line numberDiff line change
@@ -53,192 +53,4 @@ export default function Component({ loaderData }) {
5353

5454
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.
5555

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-
export default {
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-
export async function clientLoader() {
80-
return await fetch("https://example.com/api").then(
81-
(response) => response.json()
82-
);
83-
}
84-
85-
export default function Component({ loaderData }) {
86-
return <MassiveComponent data={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.
112-
113-
```tsx filename=routes/example.tsx?route-chunk=clientLoader
114-
export async function clientLoader() {
115-
return await fetch("https://example.com/api").then(
116-
(response) => response.json()
117-
);
118-
}
119-
```
120-
121-
```tsx filename=routes/example.tsx?route-chunk=main
122-
import { MassiveComponent } from "~/components";
123-
124-
export default function Component({ loaderData }) {
125-
return <MassiveComponent data={loaderData} />;
126-
}
127-
```
128-
129-
<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-
export async function clientLoader() {
160-
shared();
161-
return await fetch("https://example.com/api").then(
162-
(response) => response.json()
163-
);
164-
}
165-
166-
export default function Component({ loaderData }) {
167-
shared();
168-
return <MassiveComponent data={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-
export const 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-
export async function clientLoader() {
187-
shared();
188-
return await fetch("https://example.com/api").then(
189-
(response) => response.json()
190-
);
191-
}
192-
193-
export default function Component({ loaderData }) {
194-
shared();
195-
return <MassiveComponent data={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:
200-
201-
```tsx filename=routes/example/route.tsx?route-chunk=clientLoader
202-
import { shared } from "./shared";
203-
204-
export async function clientLoader() {
205-
shared();
206-
return await fetch("https://example.com/api").then(
207-
(response) => response.json()
208-
);
209-
}
210-
```
211-
212-
```tsx filename=routes/example/route.tsx?route-chunk=main
213-
import { MassiveComponent } from "~/components";
214-
import { shared } from "./shared";
215-
216-
export default function Component({ loaderData }) {
217-
shared();
218-
return <MassiveComponent data={loaderData} />;
219-
}
220-
```
221-
222-
If your project is particularly performance sensitive, you can set the `unstable_splitRouteModules` future flag to `"enforce"`:
223-
224-
```tsx filename=react-router-config.ts
225-
export default {
226-
future: {
227-
unstable_splitRouteModules: "enforce",
228-
},
229-
};
230-
```
231-
232-
This setting will raise an error if any route modules can't be split:
233-
234-
```
235-
Error splitting route module: routes/example/route.tsx
236-
237-
- clientLoader
238-
239-
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.
240-
```
241-
24256
[route-module]: ../../start/framework/route-module
243-
[virtual-modules]: https://vite.dev/guide/api-plugin#virtual-modules-convention
244-
[blog-lazy-loading-routes]: https://remix.run/blog/lazy-loading-routes#advanced-usage-and-optimizations

0 commit comments

Comments
 (0)