feat(rsc): add customBuildApp option (#1052)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: hi-ogawa

packages/plugin-rsc/examples/no-ssr/vite.config.ts

@@ -1,6 +1,6 @@
 import fsp from 'node:fs/promises'
 import react from '@vitejs/plugin-react'
-import rsc from '@vitejs/plugin-rsc'
+import rsc, { getPluginApi } from '@vitejs/plugin-rsc'
 import { defineConfig, type Plugin } from 'vite'
 
 export default defineConfig({
@@ -11,8 +11,34 @@ export default defineConfig({
       entries: {
         rsc: './src/framework/entry.rsc.tsx',
       },
+      customBuildApp: true,
     }),
   ],
+  builder: {
+    sharedPlugins: true,
+    sharedConfigBuild: true,
+    async buildApp(builder) {
+      const { manager } = getPluginApi(builder.config)!
+
+      // Scan
+      manager.isScanBuild = true
+      builder.environments.rsc!.config.build.write = false
+      builder.environments.client!.config.build.write = false
+      await builder.build(builder.environments.rsc!)
+      await builder.build(builder.environments.client!)
+      builder.environments.rsc!.config.build.write = true
+      builder.environments.client!.config.build.write = true
+      manager.isScanBuild = false
+      manager.stabilize()
+
+      // Build
+      await builder.build(builder.environments.rsc!)
+      await builder.build(builder.environments.client!)
+
+      // write manifest
+      manager.writeAssetsManifest(['rsc'])
+    },
+  },
 })
 
 function spaPlugin(): Plugin[] {

packages/plugin-rsc/src/plugin.ts

@@ -106,6 +106,9 @@ function resolvePackage(name: string) {
 
 export type { RscPluginManager }
 
+/**
+ * @experimental
+ */
 class RscPluginManager {
   server!: ViteDevServer
   config!: ResolvedConfig
@@ -127,6 +130,21 @@ class RscPluginManager {
   toRelativeId(id: string): string {
     return normalizePath(path.relative(this.config.root, id))
   }
+
+  writeAssetsManifest(environmentNames: string[]): void {
+    // write client manifest to all non-client builds during post-build step.
+    // this makes each server build to be self-contained and deploy-able for cloudflare.
+    const assetsManifestCode = `export default ${serializeValueWithRuntime(
+      this.buildAssetsManifest,
+    )}`
+    for (const name of environmentNames) {
+      const manifestPath = path.join(
+        this.config.environments[name]!.build.outDir,
+        BUILD_ASSETS_MANIFEST_NAME,
+      )
+      fs.writeFileSync(manifestPath, assetsManifestCode)
+    }
+  }
 }
 
 export type RscPluginOptions = {
@@ -186,6 +204,14 @@ export type RscPluginOptions = {
    */
   useBuildAppHook?: boolean
 
+  /**
+   * Skip the default buildApp orchestration and expose utilities on `builder.rsc`
+   * for downstream frameworks to implement custom build pipelines.
+   * @experimental
+   * @default false
+   */
+  customBuildApp?: boolean
+
   /**
    * Custom environment configuration
    * @experimental
@@ -343,7 +369,7 @@ export default function vitePluginRsc(
       manager.stabilize()
       logStep('[4/4] build client environment...')
       await builder.build(builder.environments.client!)
-      writeAssetsManifest(['rsc'])
+      manager.writeAssetsManifest(['rsc'])
       return
     }
 
@@ -399,27 +425,23 @@ export default function vitePluginRsc(
       fs.renameSync(tempRscOutDir, rscOutDir)
     }
 
-    writeAssetsManifest(['ssr', 'rsc'])
-  }
-
-  function writeAssetsManifest(environmentNames: string[]) {
-    // output client manifest to non-client build directly.
-    // this makes server build to be self-contained and deploy-able for cloudflare.
-    const assetsManifestCode = `export default ${serializeValueWithRuntime(
-      manager.buildAssetsManifest,
-    )}`
-    for (const name of environmentNames) {
-      const manifestPath = path.join(
-        manager.config.environments[name]!.build.outDir,
-        BUILD_ASSETS_MANIFEST_NAME,
-      )
-      fs.writeFileSync(manifestPath, assetsManifestCode)
-    }
+    manager.writeAssetsManifest(['ssr', 'rsc'])
   }
 
   let hasReactServerDomWebpack = false
 
   return [
+    {
+      name: 'rsc:builder-api',
+      buildApp: {
+        order: 'pre' as const,
+        async handler(builder) {
+          builder.rsc = {
+            manager,
+          }
+        },
+      },
+    },
     {
       name: 'rsc',
       async config(config, env) {
@@ -539,15 +561,17 @@ export default function vitePluginRsc(
               },
             },
           },
-          builder: {
-            sharedPlugins: true,
-            sharedConfigBuild: true,
-            async buildApp(builder) {
-              if (!rscPluginOptions.useBuildAppHook) {
-                await buildApp(builder)
-              }
-            },
-          },
+          builder: rscPluginOptions.customBuildApp
+            ? undefined
+            : {
+                sharedPlugins: true,
+                sharedConfigBuild: true,
+                async buildApp(builder) {
+                  if (!rscPluginOptions.useBuildAppHook) {
+                    await buildApp(builder)
+                  }
+                },
+              },
         }
       },
       configResolved() {
@@ -557,6 +581,9 @@ export default function vitePluginRsc(
       },
       buildApp: {
         async handler(builder) {
+          if (rscPluginOptions.customBuildApp) {
+            return
+          }
           if (rscPluginOptions.useBuildAppHook) {
             await buildApp(builder)
           }

packages/plugin-rsc/types/index.d.ts

@@ -17,6 +17,18 @@ declare module 'vite' {
     /** Options for `@vitejs/plugin-rsc` */
     rsc?: import('@vitejs/plugin-rsc').RscPluginOptions
   }
+
+  interface ViteBuilder {
+    /**
+     * RSC plugin API exposed for custom build pipelines.
+     * Available when using `rsc({ customBuildApp: true })`.
+     * @experimental
+     */
+    rsc: {
+      /** Access to internal RscPluginManager for controlling build phases */
+      manager: import('@vitejs/plugin-rsc').RscPluginManager
+    }
+  }
 }
 
 export {}