fix(start-plugin-core): release the start compiler when a build bundle closes

.changeset/start-compiler-release-after-build.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/start-plugin-core': patch
+---
+
+Release each environment's Start compiler when its build bundle closes. `vite build` builds the client, SSR and server environments once each in one process, so the compiler kept from an earlier environment, and the finished module graph its load/resolve closures held, stayed in memory for the rest of the build and could push large apps past the heap limit.

packages/start-plugin-core/src/vite/start-compiler-plugin/plugin.ts

@@ -409,6 +409,16 @@ export function startCompilerPlugin(
           compilers.delete(this.environment.name)
         }
       },
+      closeBundle() {
+        if (this.environment.mode === 'build') {
+          // `vite build` bundles each environment once, in one process, so the
+          // reset in buildStart never runs again for this environment. Drop the
+          // compiler now: its load/resolve closures hold this hook context and,
+          // through it, the finished module graph, which would otherwise stay
+          // alive while the remaining environments build.
+          compilers.delete(this.environment.name)
+        }
+      },
       async watchChange(id) {
         if (bundledDev && this.environment.mode === 'dev') {
           if (environment.type === 'server') {

packages/start-plugin-core/tests/vite/start-compiler-release.test.ts

@@ -0,0 +1,77 @@
+import { setFlagsFromString } from 'node:v8'
+import { runInNewContext } from 'node:vm'
+import { describe, expect, test } from 'vitest'
+import { VITE_ENVIRONMENT_NAMES } from '../../src/constants'
+import { startCompilerPlugin } from '../../src/vite/start-compiler-plugin/plugin'
+
+// Expose `gc()` without the process-wide `--expose-gc` flag, then turn the flag
+// off again once we hold a reference to it.
+setFlagsFromString('--expose-gc')
+const collectGarbage = runInNewContext('gc') as () => void
+setFlagsFromString('--no-expose-gc')
+
+function createClientPlugin() {
+  const plugins = (
+    startCompilerPlugin({
+      framework: 'react',
+      environments: [{ name: VITE_ENVIRONMENT_NAMES.client, type: 'client' }],
+      providerEnvName: VITE_ENVIRONMENT_NAMES.server,
+    }) as Array<any>
+  ).flat()
+
+  return plugins.find(
+    (plugin) =>
+      plugin.name ===
+      `tanstack-start-core::server-fn:${VITE_ENVIRONMENT_NAMES.client}`,
+  )
+}
+
+// Runs one transform in a fresh hook context, the way a build's plugin driver
+// does, and hands back only a weak reference to that context.
+async function transformInFreshContext(plugin: any) {
+  const context = {
+    environment: {
+      name: VITE_ENVIRONMENT_NAMES.client,
+      mode: 'build',
+      config: { experimental: {} },
+    },
+    load: () => Promise.resolve(null),
+    resolve: () => Promise.resolve(null),
+    error: (message: string) => {
+      throw new Error(message)
+    },
+    warn: () => {},
+  }
+
+  await plugin.transform.handler.call(
+    context,
+    'export const value = 1',
+    '/project/src/value.ts',
+  )
+
+  return new WeakRef(context)
+}
+
+describe('startCompilerPlugin in a build', () => {
+  test('releases the hook context once the environment bundle closes', async () => {
+    const plugin = createClientPlugin()
+    plugin.buildStart.call({
+      environment: { name: VITE_ENVIRONMENT_NAMES.client, mode: 'build' },
+    })
+
+    const contextRef = await transformInFreshContext(plugin)
+
+    plugin.closeBundle?.call({
+      environment: { name: VITE_ENVIRONMENT_NAMES.client, mode: 'build' },
+    })
+
+    // One collection is not guaranteed to reclaim the target, and a WeakRef
+    // keeps it alive until the current job ends, so yield before each pass.
+    for (let attempt = 0; attempt < 10 && contextRef.deref(); attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 0))
+      collectGarbage()
+    }
+
+    expect(contextRef.deref()).toBeUndefined()
+  })
+})