feat(remix-dev/vite): Add unstable_serverBundles (#8332)

Co-authored-by: Pedro Cattori <pcattori@gmail.com>

.changeset/five-peaches-attend.md

@@ -0,0 +1,5 @@
+---
+"@remix-run/dev": patch
+---
+
+Remove Vite plugin config option `serverBuildPath` in favor of separate `serverBuildDirectory` and `serverBuildFile` options

.changeset/flat-toys-hope.md

@@ -0,0 +1,30 @@
+---
+"@remix-run/dev": minor
+---
+
+Add `unstable_serverBundles` option to Vite plugin to support splitting server code into multiple request handlers.
+
+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. This feature is currently unstable and only designed to gather early feedback.
+
+**Example usage:**
+
+```ts
+import { unstable_vitePlugin as remix } from "@remix-run/dev";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    remix({
+      unstable_serverBundles: ({ branch }) => {
+        const isAuthenticatedRoute = branch.some(
+          (route) => route.id === "routes/_authenticated"
+        );
+
+        return isAuthenticatedRoute
+          ? "authenticated"
+          : "unauthenticated";
+      },
+    }),
+  ],
+});
+```

docs/future/server-bundles.md

@@ -0,0 +1,52 @@
+---
+title: Server Bundles (Unstable)
+---
+
+# Server Bundles (Unstable)
+
+<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. This feature is currently unstable and only designed to gather early feedback.</docs-warning>
+
+Remix typically builds your server code into a bundle that exposes a single request handler function. However, there are some scenarios where you might want to split your route tree into multiple server bundles that expose a request handler function for a subset of routes. To provide this level of flexibility, the [Remix Vite plugin][remix-vite] supports an `unstable_serverBundles` option which is a function for assigning routes to different server bundles.
+
+The provided `unstable_serverBundles` 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 it to. These bundle IDs will be used as directory names in your server build directory.
+
+For each route, this function is passed 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:
+
+```ts filename=vite.config.ts lines=[7-15]
+import { unstable_vitePlugin as remix } from "@remix-run/dev";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    remix({
+      unstable_serverBundles: ({ branch }) => {
+        const isAuthenticatedRoute = branch.some(
+          (route) => route.id === "routes/_authenticated"
+        );
+
+        return isAuthenticatedRoute
+          ? "authenticated"
+          : "unauthenticated";
+      },
+    }),
+  ],
+});
+```
+
+Each `route` in the `branch` array contains the following properties:
+
+- `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`.
+- `path` — The path this route uses to match on the URL pathname.
+- `file` — The absolute path to the entry point for this route.
+- `index` — Whether or not this route is an index route.
+
+## Server bundle manifest
+
+When the build is complete, Remix will generate a `bundles.json` manifest file in your server build directory containing an object with the following properties:
+
+- `serverBundles` — An object that maps bundle IDs to the bundle's `id` and `file`.
+- `routeIdToServerBundleId` — An object that maps route IDs to its server bundle ID.
+- `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 Remix request handlers.
+
+[remix-vite]: ./vite.md
+[pathless-layout-route]: ../file-conventions/routes#nested-layouts-without-nested-urls

docs/future/vite.md

@@ -34,15 +34,7 @@ These templates include a `vite.config.ts` file which is where the Remix Vite pl
 
 ## Configuration
 
-The Vite plugin does not use [`remix.config.js`][remix-config]. Instead, the plugin directly accepts the following subset of Remix config options:
-
-- [appDirectory][app-directory]
-- [assetsBuildDirectory][assets-build-directory]
-- [ignoredRouteFiles][ignored-route-files]
-- [publicPath][public-path]
-- [routes][routes]
-- [serverBuildPath][server-build-path]
-- [serverModuleFormat][server-module-format]
+The Vite plugin does not use [`remix.config.js`][remix-config]. Instead, the plugin accepts options directly.
 
 For example, to configure `ignoredRouteFiles`:
 
@@ -61,6 +53,32 @@ export default defineConfig({
 
 All other bundling-related options are now [configured with Vite][vite-config]. This means you have much greater control over the bundling process.
 
+#### Supported Remix config options
+
+The following subset of Remix config options are supported:
+
+- [appDirectory][app-directory]
+- [assetsBuildDirectory][assets-build-directory]
+- [ignoredRouteFiles][ignored-route-files]
+- [publicPath][public-path]
+- [routes][routes]
+- [serverBuildPath][server-build-path]
+- [serverModuleFormat][server-module-format]
+
+The Vite plugin also accepts the following additional options:
+
+#### serverBuildDirectory
+
+The path to the server build directory, relative to the project root. Defaults to `"build/server"`.
+
+#### serverBuildFile
+
+The name of the server file generated in the server build directory. Defaults to `"index.js"`.
+
+#### unstable_serverBundles
+
+A function for assigning addressable routes to [server bundles][server-bundles].
+
 ## New build output paths
 
 There is a notable difference with the way Vite manages the `public` directory compared to the existing Remix compiler. During the build, Vite copies files from the `public` directory into `build/client`, whereas the Remix compiler left the `public` directory untouched and used a subdirectory (`public/build`) as the client build directory.
@@ -74,7 +92,7 @@ This means that the following configuration defaults have been changed:
 
 - [assetsBuildDirectory][assets-build-directory] defaults to `"build/client"` rather than `"public/build"`
 - [publicPath][public-path] defaults to `"/"` rather than `"/build/"`
-- [serverBuildPath][server-build-path] defaults to `"build/server/index.js"` rather than `"build/index.js"`
+- [serverBuildPath][server-build-path] has been split into `serverBuildDirectory` and `serverBuildFile`, with the equivalent default for `serverBuildDirectory` being `"build/server"` rather than `"build"`
 
 ## Additional features & plugins
 
@@ -875,3 +893,4 @@ We're definitely late to the Vite party, but we're excited to be here now!
 [server-dependencies-to-bundle]: https://remix.run/docs/en/main/file-conventions/remix-config#serverdependenciestobundle
 [blues-stack]: https://github.com/remix-run/blues-stack
 [global-node-polyfills]: ../other-api/node#polyfills
+[server-bundles]: ./server-bundles

integration/helpers/vite.ts

@@ -16,6 +16,7 @@ const __dirname = url.fileURLToPath(new URL(".", import.meta.url));
 
 export const VITE_CONFIG = async (args: {
   port: number;
+  pluginOptions?: string;
   vitePlugins?: string;
 }) => {
   let hmrPort = await getPort();
@@ -31,7 +32,7 @@ export const VITE_CONFIG = async (args: {
           port: ${hmrPort}
         }
       },
-      plugins: [remix(),${args.vitePlugins ?? ""}],
+      plugins: [remix(${args.pluginOptions}),${args.vitePlugins ?? ""}],
     });
   `;
 };
@@ -136,14 +137,19 @@ export const viteBuild = ({ cwd }: { cwd: string }) => {
 export const viteRemixServe = async ({
   cwd,
   port,
+  serverBundle,
 }: {
   cwd: string;
   port: number;
+  serverBundle?: string;
 }) => {
   let nodeBin = process.argv[0];
   let serveProc = spawn(
     nodeBin,
-    ["node_modules/@remix-run/serve/dist/cli.js", "build/server/index.js"],
+    [
+      "node_modules/@remix-run/serve/dist/cli.js",
+      `build/server/${serverBundle ? serverBundle + "/" : ""}index.js`,
+    ],
     {
       cwd,
       stdio: "pipe",