| 1 | ---
|
| 2 | title: Server Bundles
|
| 3 | ---
|
| 4 |
|
| 5 | # Server Bundles
|
| 6 |
|
| 7 | [MODES: framework]
|
| 8 |
|
| 9 | <docs-warning>This is an advanced feature designed for hosting provider integrations. When compiling your app into multiple server bundles, there will need to be a custom routing layer in front of your app directing requests to the correct bundle.</docs-warning>
|
| 10 |
|
| 11 | React Router typically builds your server code into a single bundle that exports a request handler function. However, there are scenarios where you might want to split your route tree into multiple server bundles, each exposing a request handler function for a subset of routes. To provide this flexibility, [`react-router.config.ts`][react-router-config] supports a `serverBundles` option, which is a function for assigning routes to different server bundles.
|
| 12 |
|
| 13 | The [`serverBundles` function][server-bundles-function] is called for each route in the tree (except for routes that aren't addressable, e.g., pathless layout routes) and returns a server bundle ID that you'd like to assign that route to. These bundle IDs will be used as directory names in your server build directory.
|
| 14 |
|
| 15 | For each route, this function receives an array of routes leading to and including that route, referred to as the route `branch`. This allows you to create server bundles for different portions of the route tree. For example, you could use this to create a separate server bundle containing all routes within a particular layout route:
|
| 16 |
|
| 17 | ```ts filename=react-router.config.ts lines=[5-13]
|
| 18 | import type { Config } from "@react-router/dev/config";
|
| 19 |
|
| 20 | export default {
|
| 21 | // ...
|
| 22 | serverBundles: ({ branch }) => {
|
| 23 | const isAuthenticatedRoute = branch.some((route) =>
|
| 24 | route.id.split("/").includes("_authenticated"),
|
| 25 | );
|
| 26 |
|
| 27 | return isAuthenticatedRoute
|
| 28 | ? "authenticated"
|
| 29 | : "unauthenticated";
|
| 30 | },
|
| 31 | } satisfies Config;
|
| 32 | ```
|
| 33 |
|
| 34 | Each `route` in the `branch` array contains the following properties:
|
| 35 |
|
| 36 | - `id` — The unique ID for this route, named like its `file` but relative to the app directory and without the extension, e.g., `app/routes/gists.$username.tsx` will have an `id` of `routes/gists.$username`
|
| 37 | - `path` — The path this route uses to match the URL pathname
|
| 38 | - `file` — The absolute path to the entry point for this route
|
| 39 | - `index` — Whether this route is an index route
|
| 40 |
|
| 41 | ## Build manifest
|
| 42 |
|
| 43 | When the build is complete, React Router will call the `buildEnd` hook, passing a `buildManifest` object. This is useful if you need to inspect the build manifest to determine how to route requests to the correct server bundle.
|
| 44 |
|
| 45 | ```ts filename=react-router.config.ts lines=[5-7]
|
| 46 | import type { Config } from "@react-router/dev/config";
|
| 47 |
|
| 48 | export default {
|
| 49 | // ...
|
| 50 | buildEnd: async ({ buildManifest }) => {
|
| 51 | // ...
|
| 52 | },
|
| 53 | } satisfies Config;
|
| 54 | ```
|
| 55 |
|
| 56 | When using server bundles, the build manifest contains the following properties:
|
| 57 |
|
| 58 | - `serverBundles` — An object that maps bundle IDs to the bundle's `id` and `file`
|
| 59 | - `routeIdToServerBundleId` — An object that maps route IDs to their server bundle ID
|
| 60 | - `routes` — A route manifest that maps route IDs to route metadata. This can be used to drive a custom routing layer in front of your React Router request handlers
|
| 61 |
|
| 62 | [react-router-config]: https://api.reactrouter.com/v8/types/_react-router_dev.config.Config.html
|
| 63 | [server-bundles-function]: https://api.reactrouter.com/v8/types/_react-router_dev.config.ServerBundlesFunction.html
|