@octanejs/tanstack-start 0.1.27 → 0.1.29

package/src/internal/start-plugin-core/rsbuild/start-router-plugin.js

@@ -0,0 +1,69 @@
+import { routesManifestPlugin } from '../start-router-plugin/generator-plugins/routes-manifest-plugin.js';
+import { prerenderRoutesPlugin } from '../start-router-plugin/generator-plugins/prerender-routes-plugin.js';
+import { buildRouteTreeFileFooterFromConfig } from '../start-router-plugin/route-tree-footer.js';
+import { RSBUILD_ENVIRONMENT_NAMES } from './planning.js';
+import path from 'pathe';
+import { createRouterPluginContext } from '#tanstack-start/router-plugin/context';
+import {
+	TanStackRouterCodeSplitterRspack,
+	TanStackRouterGeneratorRspack,
+} from '#tanstack-start/router-plugin/rspack';
+//#region src/rsbuild/start-router-plugin.ts
+/**
+ * Registers the TanStack Router generator and code-splitter plugins
+ * as rspack plugins via `modifyRspackConfig`.
+ *
+ * The router-plugin package exports rspack-compatible unplugin wrappers:
+ * - TanStackRouterGeneratorRspack: file-based route generation
+ * - TanStackRouterCodeSplitterRspack: route code splitting
+ */
+function registerRouterPlugins(api, opts) {
+	const routerPluginContext = createRouterPluginContext();
+	api.modifyRspackConfig((config, utils) => {
+		const envName = utils.environment.name;
+		const { startConfig } = opts.getConfig();
+		const routerConfig = startConfig.router;
+		if (envName === RSBUILD_ENVIRONMENT_NAMES.client) {
+			const generatorPlugin = TanStackRouterGeneratorRspack(
+				{
+					...routerConfig,
+					target: opts.corePluginOpts.framework,
+					routeTreeFileFooter: () => {
+						return buildRouteTreeFileFooterFromConfig({
+							generatedRouteTreePath: path.resolve(routerConfig.generatedRouteTree),
+							getConfig: opts.getConfig,
+							corePluginOpts: opts.corePluginOpts,
+						});
+					},
+					plugins: [
+						routesManifestPlugin(),
+						...(opts.startPluginOpts.prerender?.enabled === true ? [prerenderRoutesPlugin()] : []),
+					],
+				},
+				routerPluginContext,
+			);
+			utils.appendPlugins(generatorPlugin);
+		}
+		if (
+			envName === RSBUILD_ENVIRONMENT_NAMES.client ||
+			envName === RSBUILD_ENVIRONMENT_NAMES.server
+		) {
+			const isClient = envName === RSBUILD_ENVIRONMENT_NAMES.client;
+			const splitterPlugin = TanStackRouterCodeSplitterRspack(
+				{
+					...routerConfig,
+					target: opts.corePluginOpts.framework,
+					codeSplittingOptions: {
+						...routerConfig.codeSplittingOptions,
+						deleteNodes: isClient ? ['ssr', 'server', 'headers'] : void 0,
+						addHmr: isClient,
+					},
+				},
+				routerPluginContext,
+			);
+			utils.appendPlugins(splitterPlugin);
+		}
+	});
+}
+//#endregion
+export { registerRouterPlugins };

package/src/internal/start-plugin-core/rsbuild/swc-rsc.d.ts

@@ -0,0 +1,17 @@
+import { ModifyRspackConfigFn } from '@rsbuild/core';
+type RspackConfig = Parameters<ModifyRspackConfigFn>[0];
+/**
+ * Walk the rspack config's module.rules and inject
+ * `rspackExperiments.reactServerComponents: true` into SWC loaders.
+ *
+ * Recurses into `oneOf` arrays because rsbuild nests the main SWC loader
+ * inside a `oneOf` rule (e.g. separate branches for asset/source vs
+ * javascript/auto). Without recursion, only the mimetype-based fallback
+ * SWC rule gets the flag, leaving most .js/.ts files without RSC
+ * directive detection.
+ */
+export declare function enableSwcReactServerComponents(
+	config: RspackConfig,
+	scope: 'all' | 'rsc-subtree',
+): void;
+export {};

package/src/internal/start-plugin-core/rsbuild/swc-rsc.js

@@ -0,0 +1,118 @@
+import { RSBUILD_RSC_LAYERS } from './planning.js';
+//#region src/rsbuild/swc-rsc.ts
+/**
+ * Walk the rspack config's module.rules and inject
+ * `rspackExperiments.reactServerComponents: true` into SWC loaders.
+ *
+ * Recurses into `oneOf` arrays because rsbuild nests the main SWC loader
+ * inside a `oneOf` rule (e.g. separate branches for asset/source vs
+ * javascript/auto). Without recursion, only the mimetype-based fallback
+ * SWC rule gets the flag, leaving most .js/.ts files without RSC
+ * directive detection.
+ */
+function enableSwcReactServerComponents(config, scope) {
+	const isRspackRule = (rule) => !!rule && rule !== '...';
+	const getRuleLoaders = (rule) => {
+		const { use } = rule;
+		if (!use) return [];
+		return typeof use === 'function' ? [] : Array.isArray(use) ? use : [use];
+	};
+	const getLoaderPath = (loader) => (typeof loader === 'string' ? loader : loader.loader);
+	const cloneLoader = (loader) => {
+		if (typeof loader === 'string') return loader;
+		const options = loader.options;
+		return {
+			...loader,
+			...(options && typeof options === 'object' && !Array.isArray(options)
+				? {
+						options: {
+							...options,
+							...(options.rspackExperiments &&
+							typeof options.rspackExperiments === 'object' &&
+							!Array.isArray(options.rspackExperiments)
+								? { rspackExperiments: { ...options.rspackExperiments } }
+								: {}),
+						},
+					}
+				: {}),
+		};
+	};
+	const cloneRuleUse = (use) => {
+		if (!use || typeof use === 'function') return use;
+		if (Array.isArray(use)) return use.map((loader) => cloneLoader(loader));
+		return cloneLoader(use);
+	};
+	const cloneRspackRule = (rule) => {
+		return {
+			...rule,
+			use: cloneRuleUse(rule.use),
+			resolve: rule.resolve ? { ...rule.resolve } : rule.resolve,
+			oneOf: Array.isArray(rule.oneOf)
+				? rule.oneOf.map((childRule) =>
+						isRspackRule(childRule) ? cloneRspackRule(childRule) : childRule,
+					)
+				: rule.oneOf,
+		};
+	};
+	const rootRules = (config.module.rules ??= []).filter(isRspackRule);
+	function processRules(rules = rootRules) {
+		for (const rule of rules) {
+			processRules(Array.isArray(rule.oneOf) ? rule.oneOf.filter(isRspackRule) : []);
+			if (
+				!getRuleLoaders(rule).some((loader) =>
+					Boolean(getLoaderPath(loader)?.includes('swc-loader')),
+				)
+			)
+				continue;
+			const enableReactServerComponentsOnRule = (nextRule) => {
+				for (const loader of getRuleLoaders(nextRule)) {
+					if (typeof loader === 'string') continue;
+					const loaderPath = getLoaderPath(loader);
+					if (!loaderPath || !loaderPath.includes('swc-loader')) continue;
+					const options =
+						loader.options && typeof loader.options === 'object'
+							? loader.options
+							: (loader.options = {});
+					const experiments =
+						options.rspackExperiments && typeof options.rspackExperiments === 'object'
+							? options.rspackExperiments
+							: (options.rspackExperiments = {});
+					const current = experiments.reactServerComponents;
+					experiments.reactServerComponents =
+						current === true || current == null
+							? {}
+							: typeof current === 'object' && current !== null && !Array.isArray(current)
+								? { ...current }
+								: {};
+				}
+			};
+			if (scope === 'all') {
+				enableReactServerComponentsOnRule(rule);
+				continue;
+			}
+			const originalRule = cloneRspackRule(rule);
+			const providerRule = cloneRspackRule(originalRule);
+			providerRule.resourceQuery = /(?:^|[?&])tss-serverfn-split(?:&|$)/;
+			enableReactServerComponentsOnRule(providerRule);
+			const routeSplitRule = cloneRspackRule(originalRule);
+			routeSplitRule.resourceQuery = /(?:^|[?&])tsr-split(?:=|&|$)/;
+			const routeSplitConditionNames = originalRule.resolve?.conditionNames;
+			routeSplitRule.resolve = {
+				...originalRule.resolve,
+				conditionNames: Array.isArray(routeSplitConditionNames)
+					? routeSplitConditionNames.includes('...')
+						? [...routeSplitConditionNames]
+						: ['...', ...routeSplitConditionNames]
+					: ['...'],
+			};
+			const subtreeRule = cloneRspackRule(originalRule);
+			subtreeRule.issuerLayer = RSBUILD_RSC_LAYERS.rsc;
+			enableReactServerComponentsOnRule(subtreeRule);
+			for (const key of Object.keys(rule)) delete rule[key];
+			rule.oneOf = [providerRule, routeSplitRule, subtreeRule, originalRule];
+		}
+	}
+	processRules();
+}
+//#endregion
+export { enableSwcReactServerComponents };

package/src/internal/start-plugin-core/rsbuild/types.d.ts

@@ -0,0 +1,17 @@
+import { EnvironmentConfig } from '@rsbuild/core';
+import { TanStackStartCoreOptions } from '../types.js';
+export interface RsbuildEnvironmentOverrides {
+	all?: EnvironmentConfig | undefined;
+	client?: EnvironmentConfig | undefined;
+	server?: EnvironmentConfig | undefined;
+	provider?: EnvironmentConfig | undefined;
+}
+export interface RsbuildCoreOptions {
+	environments?: RsbuildEnvironmentOverrides | undefined;
+}
+export type TanStackStartRsbuildPluginCoreOptions = TanStackStartCoreOptions & {
+	providerEnvironmentName: string;
+	ssrIsProvider: boolean;
+	rsbuild?: RsbuildCoreOptions | undefined;
+	rsc?: boolean | undefined;
+};

package/src/internal/start-plugin-core/rsbuild/virtual-modules.d.ts

@@ -0,0 +1,60 @@
+import { RsbuildPluginAPI, rspack as rspackNamespaceType } from '@rsbuild/core';
+import { GetConfigFn, NormalizedClientBuild, SerializationAdapterConfig } from '../types.js';
+import { ServerFn } from '../start-compiler/types.js';
+import { ScriptFormat } from '@tanstack/router-core';
+type RspackNamespace = typeof rspackNamespaceType;
+type RspackVirtualModulesPlugin = InstanceType<
+	RspackNamespace['experiments']['VirtualModulesPlugin']
+>;
+export declare const START_MANIFEST_PLACEHOLDER = '__TSS_START_MANIFEST_PLACEHOLDER__';
+export interface VirtualModuleState {
+	/** Call to update manifest content after client build completes */
+	updateManifest: (clientBuild: NormalizedClientBuild) => void;
+	/** Call to update server fn resolver content after compilation discovers fns */
+	updateServerFnResolver: () => void;
+	/** Try to write explicit resolver content now; queues if env not ready */
+	tryUpdateServerFnResolver: (content: string) => void;
+	/** Get the virtual path for a given module ID */
+	getVirtualPath: (moduleId: string) => string;
+	/** Generate resolver module content from current serverFnsById state.
+	 *  When forProvider=true, generates without isClientReferenced checks (RSC layer). */
+	generateCurrentResolverContent: (forProvider?: boolean) => string;
+	/** The absolute virtual path of the server fn resolver module */
+	serverFnResolverPath: string;
+	/** The absolute virtual path of the manifest module */
+	manifestPath: string;
+	/** Generate manifest module content from a given client build */
+	generateManifestContent: (clientBuild: NormalizedClientBuild) => string;
+	/** Generate the serialized manifest value literal for asset patching */
+	generateManifestValueLiteral: (clientBuild: NormalizedClientBuild) => string;
+	/** VirtualModulesPlugin instances keyed by environment name */
+	vmPlugins: Record<string, RspackVirtualModulesPlugin>;
+}
+export interface RegisterVirtualModulesOptions {
+	root: string;
+	getConfig: GetConfigFn;
+	serverFnsById: Record<string, ServerFn>;
+	providerEnvName: string;
+	ssrIsProvider: boolean;
+	serializationAdapters: Array<SerializationAdapterConfig> | undefined;
+	/**
+	 * Get the URL at which the rsbuild dev server serves the client entry JS.
+	 * Called lazily inside modifyRspackConfig when getConfig() is available.
+	 * Example return: '/assets/js/index.js'
+	 */
+	getDevClientEntryUrl: (publicBase: string) => string;
+	/** Whether RSC virtual modules should be registered. */
+	rscEnabled?: boolean | undefined;
+	scriptFormat: ScriptFormat;
+}
+/**
+ * Registers virtual modules for the rsbuild adapter using VirtualModulesPlugin.
+ *
+ * Creates one VirtualModulesPlugin per environment and registers them via
+ * `modifyBundlerChain`. Provides update functions to refresh content dynamically.
+ */
+export declare function registerVirtualModules(
+	api: RsbuildPluginAPI,
+	opts: RegisterVirtualModulesOptions,
+): VirtualModuleState;
+export {};

package/src/internal/start-plugin-core/rsbuild/virtual-modules.js

@@ -0,0 +1,359 @@
+import { escapeRegExp } from '../utils.js';
+import { generateServerFnResolverModule } from '../start-compiler/server-fn-resolver-module.js';
+import { buildStartManifest } from '../start-manifest-plugin/manifestBuilder.js';
+import { generateSerializationAdaptersModule } from '../serialization-adapters-module.js';
+import { RSBUILD_ENVIRONMENT_NAMES } from './planning.js';
+import { VIRTUAL_MODULES } from '@tanstack/start-server-core';
+//#region src/rsbuild/virtual-modules.ts
+var RSC_RUNTIME_VIRTUAL_ID = 'virtual:tanstack-rsc-runtime';
+var RSC_HMR_VIRTUAL_ID = 'virtual:tanstack-rsc-hmr';
+var RSC_BROWSER_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-browser-decode';
+var RSC_SSR_DECODE_VIRTUAL_ID = 'virtual:tanstack-rsc-ssr-decode';
+var START_MANIFEST_PLACEHOLDER = '__TSS_START_MANIFEST_PLACEHOLDER__';
+var DEV_START_MANIFEST_GLOBAL = '__TSS_DEV_START_MANIFEST__';
+/**
+ * VirtualModulesPlugin resolves module paths relative to compiler.context.
+ * Prefix them under the app root so they are unique and watcher-friendly.
+ */
+function virtualPath(root, moduleId) {
+	return `${root}/node_modules/.virtual/${moduleId.replace(/[:#]/g, '_')}.js`;
+}
+function getScriptFormatProperty(scriptFormat) {
+	return scriptFormat === 'iife' ? `  scriptFormat: 'iife',\n` : '';
+}
+function getEntryScriptAttrs(entryUrl, scriptFormat) {
+	return scriptFormat === 'module'
+		? `{ type: 'module', async: true, src: '${entryUrl}' }`
+		: `{ async: true, src: '${entryUrl}' }`;
+}
+function generateManifestModuleDev(devClientEntryUrl, scriptFormat) {
+	return `const fallbackManifest = {
+${getScriptFormatProperty(scriptFormat)}  routes: {
+    __root__: {
+      preloads: ['${devClientEntryUrl}'],
+      scripts: [{ attrs: ${getEntryScriptAttrs(devClientEntryUrl, scriptFormat)} }],
+    },
+  },
+}
+export const tsrStartManifest = () => globalThis[${JSON.stringify(DEV_START_MANIFEST_GLOBAL)}] ?? fallbackManifest`;
+}
+function buildStartManifestData(clientBuild, publicBase, inlineCss, scriptFormat) {
+	const routeTreeRoutes = globalThis.TSS_ROUTES_MANIFEST;
+	return buildStartManifest({
+		clientBuild,
+		routeTreeRoutes,
+		basePath: publicBase,
+		inlineCss,
+		scriptFormat,
+	});
+}
+function serializeStartManifestData(clientBuild, publicBase, inlineCss, scriptFormat) {
+	return JSON.stringify(buildStartManifestData(clientBuild, publicBase, inlineCss, scriptFormat));
+}
+function generateManifestModuleBuild(
+	clientBuild,
+	publicBase,
+	_devClientEntryUrl,
+	inlineCss,
+	scriptFormat,
+) {
+	if (!clientBuild)
+		return `const tsrStartManifestData = ${JSON.stringify(START_MANIFEST_PLACEHOLDER)}
+export const tsrStartManifest = () => tsrStartManifestData`;
+	return `export const tsrStartManifest = () => (${serializeStartManifestData(clientBuild, publicBase, inlineCss, scriptFormat)})`;
+}
+/**
+ * Generate virtual:tanstack-rsc-runtime content.
+ * In the RSC layer this re-exports from react-server-dom-rspack/server.
+ * In other layers it provides stubs that throw.
+ */
+function generateRscRuntimeModule(isRscLayer) {
+	if (isRscLayer)
+		return `export { renderToReadableStream, createTemporaryReferenceSet, decodeReply, decodeAction, decodeFormState } from 'react-server-dom-rspack/server'
+export function createFromReadableStream() { throw new Error('createFromReadableStream is not available in RSC environment (use SSR or browser decode instead)'); }
+// loadServerAction is provided by the RSC entry, not react-server-dom-rspack
+import { getServerFnById } from '#tanstack-start-server-fn-resolver'
+export const loadServerAction = async (id) => getServerFnById(id, { origin: 'server' })`;
+	return `
+export function renderToReadableStream() { throw new Error('renderToReadableStream can only be used in RSC environment'); }
+export function createFromReadableStream() { throw new Error('createFromReadableStream can only be used in RSC environment'); }
+export function createTemporaryReferenceSet() { throw new Error('createTemporaryReferenceSet can only be used in RSC environment'); }
+export function decodeReply() { throw new Error('decodeReply can only be used in RSC environment'); }
+export function loadServerAction() { throw new Error('loadServerAction can only be used in RSC environment'); }
+export function decodeAction() { throw new Error('decodeAction can only be used in RSC environment'); }
+export function decodeFormState() { throw new Error('decodeFormState can only be used in RSC environment'); }
+`;
+}
+/**
+ * Generate virtual:tanstack-rsc-hmr content.
+ * In the client env during dev, listens for rsc:update WebSocket events
+ * and invalidates the router. In all other contexts, exports nothing.
+ */
+function generateRscHmrModule(isClientEnv, isDev) {
+	if (!isClientEnv || !isDev) return 'export function setupRscHmr() {}';
+	return `
+// RSC HMR listener for rsbuild dev server
+// Listens for 'rsc:update' custom events sent via sockWrite
+export function setupRscHmr() {
+  let __invalidateQueued = false
+
+  function __queueInvalidate() {
+    if (__invalidateQueued) return
+    __invalidateQueued = true
+    queueMicrotask(async () => {
+      __invalidateQueued = false
+      try {
+        const router = window.__TSR_ROUTER__
+        if (!router) {
+          console.warn('[rsc:hmr] No router found on window.__TSR_ROUTER__')
+          return
+        }
+        await router.invalidate()
+      } catch (e) {
+        console.warn('[rsc:hmr] Failed to invalidate router:', e)
+      }
+    })
+  }
+
+  if (import.meta.webpackHot) {
+    import.meta.webpackHot.on('rsc:update', () => {
+      __queueInvalidate()
+    })
+  }
+}
+`;
+}
+/**
+ * Registers virtual modules for the rsbuild adapter using VirtualModulesPlugin.
+ *
+ * Creates one VirtualModulesPlugin per environment and registers them via
+ * `modifyBundlerChain`. Provides update functions to refresh content dynamically.
+ */
+function registerVirtualModules(api, opts) {
+	const isDev = api.context.action === 'dev';
+	const root = opts.root;
+	const paths = {
+		manifest: virtualPath(root, VIRTUAL_MODULES.startManifest),
+		serverFnResolver: virtualPath(root, VIRTUAL_MODULES.serverFnResolver),
+		pluginAdapters: virtualPath(root, VIRTUAL_MODULES.pluginAdapters),
+	};
+	const rscPaths = opts.rscEnabled
+		? {
+				rscRuntime: virtualPath(root, RSC_RUNTIME_VIRTUAL_ID),
+				rscHmr: virtualPath(root, RSC_HMR_VIRTUAL_ID),
+				rscBrowserDecode: virtualPath(root, RSC_BROWSER_DECODE_VIRTUAL_ID),
+				rscSsrDecode: virtualPath(root, RSC_SSR_DECODE_VIRTUAL_ID),
+			}
+		: null;
+	const vmPlugins = {};
+	const readyVmPlugins = {};
+	const pendingWrites = /* @__PURE__ */ new Map();
+	let clientBuild;
+	const lastResolverContentByEnvironment = {};
+	const hasSeparateProviderEnvironment =
+		!opts.rscEnabled && opts.providerEnvName !== RSBUILD_ENVIRONMENT_NAMES.server;
+	const hasSerializationAdapters = Boolean(opts.serializationAdapters?.length);
+	function isProviderEnvironment(environmentName) {
+		return environmentName === opts.providerEnvName;
+	}
+	function needsServerFnResolver(environmentName) {
+		return (
+			environmentName === RSBUILD_ENVIRONMENT_NAMES.server ||
+			(hasSeparateProviderEnvironment && isProviderEnvironment(environmentName))
+		);
+	}
+	function generateResolverContent(environmentName) {
+		return generateServerFnResolverModule({
+			serverFnsById: opts.serverFnsById,
+			includeClientReferencedCheck: !isProviderEnvironment(environmentName),
+			useStaticImports: Boolean(opts.rscEnabled && isDev),
+		});
+	}
+	function writeResolverContent(environmentName, content) {
+		if (!isDev || content !== lastResolverContentByEnvironment[environmentName]) {
+			lastResolverContentByEnvironment[environmentName] = content;
+			tryWriteModule(environmentName, paths.serverFnResolver, content);
+		}
+	}
+	function queuePendingWrite(environmentName, filePath, content) {
+		let writes = pendingWrites.get(environmentName);
+		if (!writes) {
+			writes = /* @__PURE__ */ new Map();
+			pendingWrites.set(environmentName, writes);
+		}
+		writes.set(filePath, content);
+	}
+	function tryWriteModule(environmentName, filePath, content) {
+		const vmPlugin = vmPlugins[environmentName];
+		if (!vmPlugin || !readyVmPlugins[environmentName]) {
+			queuePendingWrite(environmentName, filePath, content);
+			return false;
+		}
+		vmPlugin.writeModule(filePath, content);
+		return true;
+	}
+	function flushPendingWrites(environmentName) {
+		if (!readyVmPlugins[environmentName]) return;
+		const writes = pendingWrites.get(environmentName);
+		if (!writes?.size) return;
+		for (const [filePath, content] of writes) {
+			if (!tryWriteModule(environmentName, filePath, content)) return;
+			writes.delete(filePath);
+		}
+		if (writes.size === 0) pendingWrites.delete(environmentName);
+	}
+	function getInitialContent(environmentName) {
+		const { resolvedStartConfig, startConfig } = opts.getConfig();
+		const isServerEnv = environmentName === RSBUILD_ENVIRONMENT_NAMES.server;
+		const isClientEnv = environmentName === RSBUILD_ENVIRONMENT_NAMES.client;
+		const content = {};
+		if (isServerEnv) {
+			const devClientEntryUrl = opts.getDevClientEntryUrl(resolvedStartConfig.basePaths.publicBase);
+			content[paths.manifest] = isDev
+				? generateManifestModuleDev(devClientEntryUrl, opts.scriptFormat)
+				: generateManifestModuleBuild(
+						clientBuild,
+						resolvedStartConfig.basePaths.publicBase,
+						devClientEntryUrl,
+						startConfig.server.build.inlineCss,
+						opts.scriptFormat,
+					);
+		} else content[paths.manifest] = 'export default {}';
+		if (needsServerFnResolver(environmentName))
+			content[paths.serverFnResolver] = generateResolverContent(environmentName);
+		else content[paths.serverFnResolver] = 'export {}';
+		if (hasSerializationAdapters)
+			content[paths.pluginAdapters] = generateSerializationAdaptersModule({
+				adapters: opts.serializationAdapters,
+				runtime: environmentName === RSBUILD_ENVIRONMENT_NAMES.client ? 'client' : 'server',
+			});
+		if (rscPaths) {
+			if (isServerEnv) content[rscPaths.rscRuntime] = generateRscRuntimeModule(true);
+			else content[rscPaths.rscRuntime] = generateRscRuntimeModule(false);
+			content[rscPaths.rscHmr] = generateRscHmrModule(isClientEnv, isDev);
+			content[rscPaths.rscBrowserDecode] = isClientEnv
+				? `export * from '@tanstack/react-start/rsbuild/browser-decode'`
+				: `export function createFromReadableStream() { throw new Error('RSC browser decode is only available in the client environment') }
+export function createFromFetch() { throw new Error('RSC browser decode is only available in the client environment') }`;
+			content[rscPaths.rscSsrDecode] = isServerEnv
+				? `export { setOnClientReference, createFromReadableStream } from '@tanstack/react-start/rsbuild/ssr-decode'`
+				: `export function setOnClientReference() {}
+export function createFromReadableStream() { throw new Error('RSC SSR decode is only available in the server environment') }`;
+		}
+		return content;
+	}
+	const aliasMap = {
+		[VIRTUAL_MODULES.startManifest]: paths.manifest,
+		[VIRTUAL_MODULES.serverFnResolver]: paths.serverFnResolver,
+	};
+	if (hasSerializationAdapters) aliasMap[VIRTUAL_MODULES.pluginAdapters] = paths.pluginAdapters;
+	if (rscPaths) {
+		aliasMap[RSC_RUNTIME_VIRTUAL_ID] = rscPaths.rscRuntime;
+		aliasMap[RSC_HMR_VIRTUAL_ID] = rscPaths.rscHmr;
+		aliasMap[RSC_BROWSER_DECODE_VIRTUAL_ID] = rscPaths.rscBrowserDecode;
+		aliasMap[RSC_SSR_DECODE_VIRTUAL_ID] = rscPaths.rscSsrDecode;
+	}
+	api.modifyRspackConfig((config, utils) => {
+		const envName = utils.environment.name;
+		const initialContent = getInitialContent(envName);
+		const VMP = utils.rspack.experiments.VirtualModulesPlugin;
+		const vmPlugin = new VMP(initialContent);
+		vmPlugins[envName] = vmPlugin;
+		readyVmPlugins[envName] = false;
+		config.plugins.push(vmPlugin);
+		config.plugins.push({
+			apply(compiler) {
+				compiler.hooks.thisCompilation.tap('TanStackStartFlushPendingVirtualModules', () => {
+					readyVmPlugins[envName] = true;
+					flushPendingWrites(envName);
+				});
+			},
+		});
+		for (const [moduleId, virtualFilePath] of Object.entries(aliasMap)) {
+			const NMR = utils.rspack.NormalModuleReplacementPlugin;
+			config.plugins.push(new NMR(new RegExp(`^${escapeRegExp(moduleId)}$`), virtualFilePath));
+		}
+		const resolve = config.resolve;
+		const resolveAlias = (resolve.alias ??= {});
+		resolveAlias[VIRTUAL_MODULES.serverFnResolver] = paths.serverFnResolver;
+		if (hasSerializationAdapters)
+			resolveAlias[VIRTUAL_MODULES.pluginAdapters] = paths.pluginAdapters;
+		if (rscPaths) {
+			resolveAlias[RSC_RUNTIME_VIRTUAL_ID] = rscPaths.rscRuntime;
+			resolveAlias[RSC_HMR_VIRTUAL_ID] = rscPaths.rscHmr;
+			resolveAlias[RSC_BROWSER_DECODE_VIRTUAL_ID] = rscPaths.rscBrowserDecode;
+			resolveAlias[RSC_SSR_DECODE_VIRTUAL_ID] = rscPaths.rscSsrDecode;
+		}
+	});
+	return {
+		serverFnResolverPath: paths.serverFnResolver,
+		manifestPath: paths.manifest,
+		vmPlugins,
+		generateCurrentResolverContent(forProvider) {
+			return generateResolverContent(
+				forProvider ? opts.providerEnvName : RSBUILD_ENVIRONMENT_NAMES.server,
+			);
+		},
+		generateManifestContent(newClientBuild) {
+			const { resolvedStartConfig, startConfig } = opts.getConfig();
+			const devClientEntryUrl = opts.getDevClientEntryUrl(resolvedStartConfig.basePaths.publicBase);
+			return generateManifestModuleBuild(
+				newClientBuild,
+				resolvedStartConfig.basePaths.publicBase,
+				devClientEntryUrl,
+				!isDev
+					? startConfig.server.build.inlineCss
+					: {
+							enabled: false,
+							transformAssets: false,
+						},
+				opts.scriptFormat,
+			);
+		},
+		generateManifestValueLiteral(newClientBuild) {
+			const { resolvedStartConfig, startConfig } = opts.getConfig();
+			return serializeStartManifestData(
+				newClientBuild,
+				resolvedStartConfig.basePaths.publicBase,
+				!isDev
+					? startConfig.server.build.inlineCss
+					: {
+							enabled: false,
+							transformAssets: false,
+						},
+				opts.scriptFormat,
+			);
+		},
+		updateManifest(newClientBuild) {
+			clientBuild = newClientBuild;
+			const { resolvedStartConfig } = opts.getConfig();
+			if (isDev)
+				globalThis[DEV_START_MANIFEST_GLOBAL] = buildStartManifestData(
+					clientBuild,
+					resolvedStartConfig.basePaths.publicBase,
+					{
+						enabled: false,
+						transformAssets: false,
+					},
+					opts.scriptFormat,
+				);
+		},
+		updateServerFnResolver() {
+			const updateEnvironment = (environmentName) => {
+				if (!needsServerFnResolver(environmentName)) return;
+				writeResolverContent(environmentName, generateResolverContent(environmentName));
+			};
+			updateEnvironment(RSBUILD_ENVIRONMENT_NAMES.server);
+			if (hasSeparateProviderEnvironment) updateEnvironment(opts.providerEnvName);
+		},
+		tryUpdateServerFnResolver(content) {
+			lastResolverContentByEnvironment[RSBUILD_ENVIRONMENT_NAMES.server] = content;
+			tryWriteModule(RSBUILD_ENVIRONMENT_NAMES.server, paths.serverFnResolver, content);
+		},
+		getVirtualPath(moduleId) {
+			return virtualPath(root, moduleId);
+		},
+	};
+}
+//#endregion
+export { START_MANIFEST_PLACEHOLDER, registerVirtualModules };

package/src/plugin-rsbuild.d.ts

@@ -0,0 +1,25 @@
+import type { OctaneRspackPluginOptions } from '@octanejs/rspack-plugin';
+import type { RsbuildPlugin } from '@rsbuild/core';
+import type { TanStackStartRsbuildInputConfig } from '#tanstack-start/plugin-core/rsbuild';
+
+export type OctaneCompilerOptions = Omit<
+	OctaneRspackPluginOptions,
+	'environment' | 'root' | 'transpile'
+> & {
+	/**
+	 * Enables profiling during `rsbuild dev` and compiles it out of production
+	 * builds. An explicit `profile` option takes precedence.
+	 */
+	devtools?: boolean;
+};
+
+export type TanStackOctaneStartRsbuildInputConfig = Omit<
+	TanStackStartRsbuildInputConfig,
+	'octane'
+> & {
+	octane?: OctaneCompilerOptions;
+};
+
+export declare function tanstackStart(
+	options?: TanStackOctaneStartRsbuildInputConfig,
+): RsbuildPlugin;