feat(remix-dev/vite): Add unstable_serverBundles

.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

docs/future/server-bundles.md

@@ -0,0 +1,54 @@
+---
+title: Server Bundles (Unstable)
+---
+
+# Server Bundles (Unstable)
+
+<docs-warning>This is an advanced feature designed for hosting provider integrations. When a Remix app is compiled into multiple request handlers, there will need to be a custom routing layer in front of your app directing requests to the correct handler. Hosting providers that want to make use of this feature are expected to implement this custom routing layer, not the average Remix developer. This feature is currently unstable and only designed to gather early feedback.</docs-warning>
+
+Remix typically builds your server code into a single request handler function. However, there are some scenarios where you might want to split your route tree into multiple request handlers that each accept a subset of requests. 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.
+
+The function is passed a route `branch` which is a root-first array of `route` objects leading to and including the target route which which allows you to create server bundles for different portions of the route tree. For example, you could use this to create a server bundle containing all routes within a particular layout route:
+
+```ts filename=vite.config.ts lines=[7-10]
+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` object 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.
+- `caseSensitive` — Whether or not the `path` is case-sensitive.
+- `parentId` — The unique `id` for this route's parent route, if there is one.
+
+## 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 mapping bundle IDs to an object containing the bundle's `id` and `file`.
+- `routeIdToServerBundleId` — An object mapping route IDs to server bundle ID.
+- `routes` — A route manifest mapping 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",