Rsbuild Compiler Architecture

This document explains the TanStack Start compiler integration for Rsbuild and Rspack. It focuses on server-function discovery, Rspack cache interaction, and the resolver virtual module.

Goals

The Rsbuild integration has to do three things at the same time:

• Compile Start-specific source patterns such as server functions, isomorphic functions, middleware, and compiler virtual modules.
• Keep server-function metadata available when Rspack restores modules from its persistent cache and skips transforms.
• Generate the #tanstack-start-server-fn-resolver virtual module after the server-function registry is complete for the current compilation.

The important point is that server-function discovery is a side effect of compilation. If Rspack restores a transformed module from persistent cache, the transform side effect does not run. We therefore store the discovered metadata on the Rspack module itself and replay it from module.buildInfo.

Main Files

• plugin.ts wires the Rsbuild plugin phases, virtual modules, RSC hooks, compiler ordering, and resolver rebuild hooks.
• start-compiler-host.ts registers the Start compiler transforms, captures server-function metadata, writes metadata to Rspack buildInfo, and replays cached metadata.
• start-compiler-metadata.ts defines the string keys and types used by the metadata loader.
• start-compiler-metadata-loader.ts is the real Rspack loader that writes server-function metadata to the current module's buildInfo.
• virtual-modules.ts owns the resolver virtual module and writes updated virtual module content per Rsbuild environment.
• ../start-compiler/handleCreateServerFn.ts discovers server functions while compiling caller modules.
• ../start-compiler/server-fn-resolver-module.ts generates the resolver module from the current server-function registry.

Environments

Start registers compiler work for each Rsbuild environment that can affect server-function metadata:

• client discovers functions referenced from browser code and marks them client-accessible.
• ssr discovers functions reachable from the server-rendered route graph.
• A separate provider environment is included when server-function providers are not compiled in ssr and RSC is not enabled.

The shared registry is serverFnsById. It is passed to virtual-modules.ts, which uses it to generate resolver module content.

Cold Transform Path

registerStartCompilerTransforms() registers an api.transform({ order: 'pre' }) transform for each Start compiler environment.

When a matching module is compiled normally:

1. Rsbuild runs the Start transform in the pre-loader phase.
2. The transform checks compiler virtual modules first.
3. It runs cheap code filters to skip files that cannot contain Start compiler patterns.
4. It lazily creates one StartCompiler per environment.
5. It detects which compiler features are present in the current code.
6. It serializes access to the per-environment StartCompiler through runCompilerTask().
7. It calls compiler.compile({ id, code, detectedKinds }).
8. During compile, handleCreateServerFn() reports discovered server functions through onServerFnsById.
9. The transform stores the discovered server functions for this module in the environment's pending metadata map.

The module ID used for transform metadata is ctx.resource. The metadata loader later reads this.resource. Using the same Rspack resource string keeps the handoff stable across resource queries.

Server-Function Discovery

Server functions are discovered in caller modules, not in provider modules. In handleCreateServerFn(), each discovered function records:

• functionName, the generated handler export name.
• functionId, the stable server-function ID.
• filename, the caller module ID.
• extractedFilename, the provider module ID with the server-function split query.
• isClientReferenced, whether client-origin calls are allowed.

onServerFnsById merges discoveries into the shared serverFnsById registry. While a compile task is active, it also merges the same discoveries into that module's activeServerFnMetadata object. After compile finishes, that object becomes the metadata payload for the module.

Per-environment compiler tasks are serialized because StartCompiler owns mutable module caches and because activeServerFnMetadata must only describe the module currently being compiled in that environment.

Loading And Resolving Modules

The compiler sometimes needs to read or resolve imported modules while compiling a source file.

start-compiler-host.ts uses two native Rsbuild/Rspack surfaces for this:

• ctx.resolve() from the active Rsbuild transform context resolves module IDs.
• compiler.inputFileSystem reads source through Rspack's input filesystem.

An AsyncLocalStorage value binds loadModule and resolveId back to the active transform context. That lets the compiler add dependencies to the current Rspack module without reaching into Rspack private resolver internals.

Why A Real Loader Is Used

Rsbuild api.transform() is implemented as a loader, but its callback only exposes the transform context. It does not expose the current NormalModule or module.buildInfo.

Rspack persists custom module.buildInfo fields. To write metadata there, Start installs a small real loader after the transform:

1. start-compiler-host.ts adds a rule with enforce: 'post' for Start transformable modules.
2. The rule points to the emitted start-compiler-metadata-loader.js file.
3. The loader receives the environment's pending metadata map through loader options.
4. A public NormalModule.getCompilationHooks(compilation).loader hook adds a setter to the loader context.
5. The loader reads metadata for this.resource and calls the setter.
6. The setter writes to module.buildInfo['tanstack.start.serverFns'].

Only string-keyed, JSON-serializable buildInfo fields are used. Rspack persists those fields with the module cache. Symbol keys and private cache internals are intentionally avoided.

Cache-Enabled And Cache-Disabled Behavior

The metadata loader is installed regardless of performance.buildCache.

When persistent cache is enabled, Rspack may later restore a module without rerunning the Start transform or the metadata loader. The buildInfo payload is then replayed from the cached module.

When persistent cache is disabled, the same loader path still runs during normal compilation and writes in-memory buildInfo. Keeping one path avoids conditional behavior and keeps cold, watch, cache-disabled, and cache-enabled builds aligned. The overhead is one small post loader for modules that already match the Start transform test.

The cache-specific part is not the loader itself. The cache-specific part is that Rspack can persist and later restore the buildInfo field.

Stale Metadata Clearing

If a module previously contained server functions and then no longer produces metadata, the metadata loader writes an empty payload:

{ version: 1, serverFnsById: {} }

This prevents stale server-function entries from surviving on a cached module's buildInfo after a file edit removes or renames server functions.

Warm Cache Replay

Each relevant compiler installs a finishMake hook at stage -20.

At that point Rspack has built or restored the module graph for the environment, and module buildInfo is available. The hook:

1. Iterates over compilation.modules.
2. Reads module.buildInfo['tanstack.start.serverFns'].
3. Validates the payload with the versioned schema.
4. Merges valid module metadata into an environment snapshot.
5. Stores the snapshot in serverFnsByEnvironment.
6. Rebuilds the shared serverFnsById registry from all environment snapshots.
7. Notifies virtual modules that resolver content may have changed.

The shared registry is rebuilt from snapshots instead of being append-only. This is what lets deleted or renamed server functions disappear after watch rebuilds or warm-cache restores.

The pending transform-to-loader metadata maps are cleared on each Rspack compile hook. That prevents metadata discovered in an earlier compilation from being written to a later module when the transform no longer runs or no longer discovers server functions.

Why Snapshots Are Per Environment

Each Rsbuild environment can see different information for the same file. For example, client and SSR caller environments can mark functions as client-accessible, while server and provider environments own server execution details. The merged registry preserves the broadest known access information.

A single global replay pass would either drop another environment's metadata or keep stale metadata too long. The model is therefore:

• Build one current snapshot per environment.
• Replace the shared registry with the union of all available snapshots.
• Regenerate resolver content from that shared registry.

This keeps the global registry convergent while allowing Rspack environments to finish independently.

Resolver Rebuild Ordering

The resolver virtual module must be rebuilt after cached metadata has been replayed.

The ordering is:

1. finishMake stage -20: replay buildInfo into environment snapshots and rebuild serverFnsById.
2. finishMake stage -10: write resolver virtual module content and rebuild modules that import the resolver.

For non-RSC builds, each server-like environment that needs the resolver installs the stage -10 rebuild hook.

For RSC builds, the server environment installs the RSC resolver rebuild hook at stage -10. It generates provider-style resolver content because RSC server actions run inside the server/RSC environment and do not need the client-reference check in that resolver layer.

Compiler Ordering

Non-RSC Rsbuild uses Rspack MultiCompiler.setDependencies() to make resolver-owning environments wait for metadata-producing environments.

The intended order is:

• client runs before every server-like environment.
• If a separate provider environment exists, the provider runs after client.
• If a separate provider environment exists, ssr runs after both client and the provider.

That ordering prevents the ssr resolver module from being finalized before provider metadata is available.

RSC builds intentionally do not add these dependencies. Rspack's native RSC coordinator interleaves server and client compilation phases. Adding MultiCompiler dependencies on top of it can deadlock the build.

Native APIs Used

The implementation uses Rsbuild/Rspack integration points instead of cache internals:

• Rsbuild api.transform() for source transforms.
• Rsbuild transform ctx.resolve() for module resolution.
• Rspack compiler.inputFileSystem for source reads.
• Rspack loaders for access to the loader pipeline.
• Rspack NormalModule.getCompilationHooks(compilation).loader to extend loader context.
• Rspack module.buildInfo for module-scoped persisted metadata.
• Rspack compiler.hooks.finishMake for module graph replay and resolver rebuild ordering.
• Rspack compilation.rebuildModule() through the local rebuildModulesContaining() helper.
• Rspack MultiCompiler.setDependencies() for non-RSC compiler ordering.
• Rspack experiments.VirtualModulesPlugin for virtual module content.

The implementation avoids private persistent-cache files, direct cache mutation, direct _module access from loaders, global handoff state, and disabling module caching with this.cacheable(false).

When A New Server Function Is Compiled

For a new server function in a normal cold compile:

1. Rsbuild sends the source module through the Start pre transform.
2. StartCompiler.compile() rewrites the caller module and discovers the server function.
3. onServerFnsById merges the function into serverFnsById and the active module metadata object.
4. The transform stores { version: 1, serverFnsById: discoveredServerFnsById } in the environment metadata map under the module resource.
5. The post metadata loader runs for the same resource.
6. The loader writes that payload into module.buildInfo['tanstack.start.serverFns'].
7. Rspack owns the module from there. If persistent cache is enabled, Rspack persists the module and its string-keyed buildInfo with its normal cache machinery.
8. At finishMake -20, Start reads current module buildInfo and rebuilds the environment snapshot.
9. At finishMake -10, Start rewrites and rebuilds the resolver virtual module so runtime lookups can find the new function.