@octanejs/tanstack-start 0.1.27 → 0.1.29

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

@@ -0,0 +1,9 @@
+export { RSBUILD_ENVIRONMENT_NAMES } from './planning.js';
+export type { TanStackStartRsbuildPluginCoreOptions } from './types.js';
+export type { TanStackStartRsbuildInputConfig } from './schema.js';
+export type {
+	StartCompilerImportTransform,
+	StartCompilerTransformCandidate,
+	StartCompilerTransformContext,
+} from '../types.js';
+export { tanStackStartRsbuild } from './plugin.js';

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

@@ -0,0 +1,3 @@
+import { RSBUILD_ENVIRONMENT_NAMES } from './planning.js';
+import { tanStackStartRsbuild } from './plugin.js';
+export { RSBUILD_ENVIRONMENT_NAMES, tanStackStartRsbuild };

package/src/internal/start-plugin-core/rsbuild/normalized-client-build.d.ts

@@ -0,0 +1,20 @@
+import { RsbuildPluginAPI, Rspack } from '@rsbuild/core';
+import { NormalizedClientBuild } from '../types.js';
+type RspackCompilation = Rspack.Compilation;
+/**
+ * Normalize an rspack compilation into a NormalizedClientBuild.
+ *
+ * Iterates ALL chunks in the compilation (initial + async), not just
+ * entrypoint chunks, to ensure route-split async chunks are included.
+ */
+export declare function normalizeRspackClientBuild(
+	compilation: RspackCompilation,
+): NormalizedClientBuild;
+/**
+ * Registers a processAssets hook to capture the client build stats
+ * after compilation. Returns a getter for the captured build.
+ */
+export declare function registerClientBuildCapture(api: RsbuildPluginAPI): {
+	getClientBuild: () => NormalizedClientBuild | undefined;
+};
+export {};

package/src/internal/start-plugin-core/rsbuild/normalized-client-build.js

@@ -0,0 +1,261 @@
+import { tssHydrate } from '../hydration-constants.js';
+import { getCssAssetSource } from '../start-manifest-plugin/inlineCss.js';
+import { RSBUILD_ENVIRONMENT_NAMES } from './planning.js';
+import { tsrSplit } from '#tanstack-start/router-plugin';
+//#region src/rsbuild/normalized-client-build.ts
+/**
+ * Extract route file paths from rspack module identifiers.
+ *
+ * In rspack, module identifiers contain query params similar to Vite's moduleIds.
+ * We look for the `tsr-split` query to identify route-split chunks.
+ */
+function getRouteFilePathsFromModules(modules) {
+	let routeFilePaths;
+	let seen;
+	for (const mod of modules) {
+		const identifier = mod.identifier();
+		const lastBangIndex = identifier.lastIndexOf('!');
+		const resourcePart = lastBangIndex >= 0 ? identifier.slice(lastBangIndex + 1) : identifier;
+		const queryIndex = resourcePart.indexOf('?');
+		if (queryIndex < 0) continue;
+		const query = resourcePart.slice(queryIndex + 1);
+		if (!query.includes(tsrSplit)) continue;
+		if (!new URLSearchParams(query).has(tsrSplit)) continue;
+		const routeFilePath = mod.nameForCondition() ?? resourcePart.slice(0, queryIndex);
+		if (seen?.has(routeFilePath)) continue;
+		if (!routeFilePaths || !seen) {
+			routeFilePaths = [];
+			seen = /* @__PURE__ */ new Set();
+		}
+		routeFilePaths.push(routeFilePath);
+		seen.add(routeFilePath);
+	}
+	return routeFilePaths ?? [];
+}
+function getHydrationIdsFromModules(modules) {
+	let hydrationIds;
+	let seen;
+	for (const mod of modules) {
+		const identifier = mod.identifier();
+		const lastBangIndex = identifier.lastIndexOf('!');
+		const resourcePart = lastBangIndex >= 0 ? identifier.slice(lastBangIndex + 1) : identifier;
+		const queryIndex = resourcePart.indexOf('?');
+		if (queryIndex < 0) continue;
+		const query = resourcePart.slice(queryIndex + 1);
+		if (!query.includes('tss-hydrate')) continue;
+		const hydrationId = new URLSearchParams(query).get(tssHydrate);
+		if (!hydrationId || seen?.has(hydrationId)) continue;
+		if (!hydrationIds || !seen) {
+			hydrationIds = [];
+			seen = /* @__PURE__ */ new Set();
+		}
+		hydrationIds.push(hydrationId);
+		seen.add(hydrationId);
+	}
+	return hydrationIds ?? [];
+}
+/**
+ * Returns true for Rspack/webpack HMR runtime chunks that should never be
+ * surfaced to the Start manifest. These files are emitted on every rebuild
+ * (e.g. `index.<hash>.hot-update.mjs`) and must not be treated as the entry
+ * chunk, route preloads, or sibling imports.
+ */
+function isHotUpdateAsset(file) {
+	return file.includes('.hot-update.');
+}
+/**
+ * True for any JS/MJS asset that should be included in the manifest.
+ * Excludes HMR runtime patches.
+ */
+function isManifestJsAsset(file) {
+	if (!file.endsWith('.js') && !file.endsWith('.mjs')) return false;
+	return !isHotUpdateAsset(file);
+}
+/**
+ * Get all JS file names from a chunk.
+ */
+function getChunkJsFiles(chunk) {
+	const jsFiles = [];
+	for (const file of chunk.files) if (isManifestJsAsset(file)) jsFiles.push(file);
+	return jsFiles;
+}
+/**
+ * Compute dynamicImports for a chunk by traversing its chunk groups'
+ * childrenIterable (async/dynamic import edges).
+ *
+ * In rspack, a chunk belongs to one or more ChunkGroups. Each ChunkGroup
+ * has childrenIterable — child ChunkGroups representing dynamic import()
+ * points. The JS files from those child groups' chunks are the
+ * dynamicImports (analogous to Rollup's OutputChunk.dynamicImports).
+ */
+function computeDynamicImports(chunk) {
+	const dynamicImportFiles = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const group of chunk.groupsIterable)
+		for (const childGroup of group.childrenIterable)
+			for (const childChunk of childGroup.chunks)
+				for (const file of childChunk.files)
+					if (isManifestJsAsset(file) && !seen.has(file)) {
+						seen.add(file);
+						dynamicImportFiles.push(file);
+					}
+	return dynamicImportFiles;
+}
+/**
+ * Compute static imports (sibling chunks) for an async chunk.
+ *
+ * In rspack/webpack, an async chunk's ChunkGroup contains ALL chunks needed to
+ * satisfy that dynamic import — the async chunk itself plus any shared/vendor
+ * chunks it statically imports. This is analogous to Rollup's
+ * `OutputChunk.imports` for async chunks.
+ *
+ * We collect JS files from all sibling chunks in the group (excluding the
+ * current chunk's own file) to populate the `imports` field.
+ */
+function computeAsyncChunkImports(chunk, currentFile) {
+	const imports = [];
+	const seen = /* @__PURE__ */ new Set();
+	seen.add(currentFile);
+	for (const group of chunk.groupsIterable)
+		for (const siblingChunk of group.chunks)
+			for (const file of siblingChunk.files)
+				if (isManifestJsAsset(file) && !seen.has(file)) {
+					seen.add(file);
+					imports.push(file);
+				}
+	return imports;
+}
+/**
+ * Normalize an rspack compilation into a NormalizedClientBuild.
+ *
+ * Iterates ALL chunks in the compilation (initial + async), not just
+ * entrypoint chunks, to ensure route-split async chunks are included.
+ */
+function normalizeRspackClientBuild(compilation) {
+	const chunksByFileName = /* @__PURE__ */ new Map();
+	const chunkFileNamesByRouteFilePath = /* @__PURE__ */ new Map();
+	const cssFilesBySourcePath = /* @__PURE__ */ new Map();
+	const cssContentByFileName = /* @__PURE__ */ new Map();
+	let entryChunkFileName;
+	const entrypoint = compilation.entrypoints.get('index');
+	const initialJsFileNames = [];
+	const entryChunkSet = /* @__PURE__ */ new Set();
+	if (entrypoint)
+		for (const chunk of entrypoint.chunks) {
+			entryChunkSet.add(chunk);
+			for (const file of chunk.files) if (isManifestJsAsset(file)) initialJsFileNames.push(file);
+		}
+	for (const chunk of compilation.chunks) {
+		const modules = compilation.chunkGraph.getChunkModules(chunk);
+		const routeFilePaths = getRouteFilePathsFromModules(modules);
+		const hydrationIds = getHydrationIdsFromModules(modules);
+		const cssFiles = [];
+		const seenCssFiles = /* @__PURE__ */ new Set();
+		for (const auxFile of chunk.auxiliaryFiles)
+			if (auxFile.endsWith('.css') && !seenCssFiles.has(auxFile)) {
+				seenCssFiles.add(auxFile);
+				cssFiles.push(auxFile);
+			}
+		for (const mainFile of chunk.files)
+			if (mainFile.endsWith('.css') && !seenCssFiles.has(mainFile)) {
+				seenCssFiles.add(mainFile);
+				cssFiles.push(mainFile);
+			}
+		if (cssFiles.length > 0)
+			for (const mod of modules) {
+				const sourcePath = mod.nameForCondition();
+				if (!sourcePath) continue;
+				const existing = cssFilesBySourcePath.get(sourcePath);
+				cssFilesBySourcePath.set(
+					sourcePath,
+					existing ? appendUniqueStrings(existing, cssFiles) : cssFiles.slice(),
+				);
+			}
+		const isEntryChunk = chunk.name === 'index' && entryChunkSet.has(chunk);
+		const jsFiles = getChunkJsFiles(chunk);
+		if (jsFiles.length === 0) continue;
+		const dynamicImports = computeDynamicImports(chunk);
+		for (const file of jsFiles) {
+			const normalizedChunk = {
+				fileName: file,
+				isEntry: isEntryChunk,
+				imports: isEntryChunk
+					? initialJsFileNames.filter((f) => f !== file)
+					: computeAsyncChunkImports(chunk, file),
+				dynamicImports,
+				css: [],
+				routeFilePaths,
+				hydrationIds,
+			};
+			chunksByFileName.set(file, normalizedChunk);
+			if (isEntryChunk && !entryChunkFileName) entryChunkFileName = file;
+			for (const routeFilePath of routeFilePaths) {
+				let chunkFileNames = chunkFileNamesByRouteFilePath.get(routeFilePath);
+				if (!chunkFileNames) {
+					chunkFileNames = [];
+					chunkFileNamesByRouteFilePath.set(routeFilePath, chunkFileNames);
+				}
+				chunkFileNames.push(file);
+			}
+		}
+		for (const cssFile of cssFiles)
+			for (const file of jsFiles) {
+				const existing = chunksByFileName.get(file);
+				if (existing && !existing.css.includes(cssFile)) existing.css.push(cssFile);
+			}
+	}
+	if (!entryChunkFileName) throw new Error('No entry file found in rspack client build');
+	for (const asset of compilation.getAssets()) {
+		if (!asset.name.endsWith('.css')) continue;
+		const css = getCssAssetSource(asset.source.source());
+		if (css !== void 0) cssContentByFileName.set(asset.name, css);
+	}
+	const rscEntrypoint = compilation.entrypoints.get('rsc');
+	if (rscEntrypoint && entryChunkFileName) {
+		const mainEntryChunk = chunksByFileName.get(entryChunkFileName);
+		if (mainEntryChunk)
+			for (const rscChunk of rscEntrypoint.chunks) {
+				const allFiles = [...rscChunk.files, ...rscChunk.auxiliaryFiles];
+				for (const file of allFiles)
+					if (file.endsWith('.css') && !mainEntryChunk.css.includes(file))
+						mainEntryChunk.css.push(file);
+			}
+	}
+	return {
+		entryChunkFileName,
+		chunksByFileName,
+		chunkFileNamesByRouteFilePath,
+		cssFilesBySourcePath,
+		cssContentByFileName,
+	};
+}
+function appendUniqueStrings(target, source) {
+	const seen = new Set(target);
+	let result;
+	for (const value of source) {
+		if (seen.has(value)) continue;
+		seen.add(value);
+		if (!result) result = target.slice();
+		result.push(value);
+	}
+	return result ?? target;
+}
+/**
+ * Registers a processAssets hook to capture the client build stats
+ * after compilation. Returns a getter for the captured build.
+ */
+function registerClientBuildCapture(api) {
+	let clientBuild;
+	api.processAssets(
+		{
+			stage: 'report',
+			environments: [RSBUILD_ENVIRONMENT_NAMES.client],
+		},
+		(context) => {
+			clientBuild = normalizeRspackClientBuild(context.compilation);
+		},
+	);
+	return { getClientBuild: () => clientBuild };
+}
+//#endregion
+export { registerClientBuildCapture };

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

@@ -0,0 +1,56 @@
+import { ENTRY_POINTS } from '../constants.js';
+import { EnvironmentConfig } from '@rsbuild/core';
+import { ResolvedStartEntryPlan } from '../planning.js';
+import { RsbuildEnvironmentOverrides } from './types.js';
+import { ScriptFormat } from '@tanstack/router-core';
+export declare const RSBUILD_ENVIRONMENT_NAMES: {
+	readonly client: 'client';
+	readonly server: 'ssr';
+};
+/**
+ * Rspack layer names for the rsbuild RSC layered model.
+ * These match the canonical names from `rspack.experiments.rsc.Layers`.
+ */
+export declare const RSBUILD_RSC_LAYERS: {
+	/** React Server Components layer — uses `react-server` resolve condition */
+	readonly rsc: 'react-server-components';
+	/** Server-Side Rendering layer — standard Node resolve */
+	readonly ssr: 'server-side-rendering';
+};
+export declare const RSBUILD_CLIENT_ASSETS_DIR = 'assets';
+export type RsbuildEnvironmentName =
+	(typeof RSBUILD_ENVIRONMENT_NAMES)[keyof typeof RSBUILD_ENVIRONMENT_NAMES];
+type RsbuildDistPath = NonNullable<EnvironmentConfig['output']>['distPath'];
+export interface RsbuildResolvedEntryAliases {
+	client: string;
+	server: string;
+	start: string;
+	router: string;
+	alias: Record<(typeof ENTRY_POINTS)[keyof typeof ENTRY_POINTS], string>;
+}
+export declare function createRsbuildResolvedEntryAliases(opts: {
+	entryPaths: ResolvedStartEntryPlan['entryPaths'];
+}): RsbuildResolvedEntryAliases;
+export interface RsbuildEnvironmentPlanResult {
+	environments: Record<string, EnvironmentConfig>;
+	alias: Record<string, string>;
+}
+export declare function createRsbuildEnvironmentPlan(opts: {
+	root: string;
+	entryAliases: RsbuildResolvedEntryAliases;
+	clientOutputDirectory: string;
+	serverOutputDirectory: string;
+	publicBase: string;
+	serverFnProviderEnv: string;
+	environmentOverrides?: RsbuildEnvironmentOverrides;
+	scriptFormat?: ScriptFormat;
+	rsc?: boolean | undefined;
+	dev?: boolean | undefined;
+}): RsbuildEnvironmentPlanResult;
+export declare function resolveRsbuildOutputDirectory(opts: {
+	distPath: RsbuildDistPath | undefined;
+	rootDistPath: RsbuildDistPath | undefined;
+	fallback: string;
+	subdirectory: string;
+}): string;
+export {};

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

@@ -0,0 +1,173 @@
+import { ENTRY_POINTS } from '../constants.js';
+import { join } from 'pathe';
+import { createRequire } from 'node:module';
+import { mergeRsbuildConfig } from '@rsbuild/core';
+//#region src/rsbuild/planning.ts
+var require = createRequire(import.meta.url);
+var RSBUILD_ENVIRONMENT_NAMES = {
+	client: 'client',
+	server: 'ssr',
+};
+/**
+ * Rspack layer names for the rsbuild RSC layered model.
+ * These match the canonical names from `rspack.experiments.rsc.Layers`.
+ */
+var RSBUILD_RSC_LAYERS = {
+	/** React Server Components layer — uses `react-server` resolve condition */
+	rsc: 'react-server-components',
+	/** Server-Side Rendering layer — standard Node resolve */
+	ssr: 'server-side-rendering',
+};
+var RSBUILD_CLIENT_ASSETS_DIR = 'assets';
+function createRsbuildResolvedEntryAliases(opts) {
+	const client = normalizeEntryPath(opts.entryPaths.client);
+	const server = normalizeEntryPath(opts.entryPaths.server);
+	const start = normalizeEntryPath(opts.entryPaths.start);
+	const router = normalizeEntryPath(opts.entryPaths.router);
+	return {
+		client,
+		server,
+		start,
+		router,
+		alias: {
+			[ENTRY_POINTS.client]: client,
+			[ENTRY_POINTS.server]: server,
+			[ENTRY_POINTS.start]: start,
+			[ENTRY_POINTS.router]: router,
+		},
+	};
+}
+function createRsbuildEnvironmentPlan(opts) {
+	const alias = {
+		...opts.entryAliases.alias,
+		...(opts.rsc
+			? {
+					'react-server-dom-rspack/server$': resolveFromRoot(
+						'react-server-dom-rspack/server.node',
+						opts.root,
+					),
+				}
+			: {}),
+	};
+	const environmentOverrides = opts.environmentOverrides ?? {};
+	const clientOutputModule = (opts.scriptFormat ?? 'module') === 'module';
+	const userClientOutputModule =
+		environmentOverrides.client?.output?.module ?? environmentOverrides.all?.output?.module;
+	if (typeof userClientOutputModule === 'boolean' && userClientOutputModule !== clientOutputModule)
+		throw new Error(
+			'TanStack Start rsbuild.client.output controls environments.client.output.module. Remove environments.client.output.module or set rsbuild.client.output to match it.',
+		);
+	return {
+		environments: {
+			[RSBUILD_ENVIRONMENT_NAMES.client]: mergeRsbuildConfig(
+				{
+					source: {
+						entry: {
+							index: {
+								import: opts.entryAliases.client,
+								html: false,
+							},
+						},
+					},
+					output: {
+						target: 'web',
+						module: clientOutputModule,
+						distPath: {
+							root: opts.clientOutputDirectory,
+							js: `${RSBUILD_CLIENT_ASSETS_DIR}/js`,
+							jsAsync: `${RSBUILD_CLIENT_ASSETS_DIR}/js/async`,
+							css: `${RSBUILD_CLIENT_ASSETS_DIR}/css`,
+							cssAsync: `${RSBUILD_CLIENT_ASSETS_DIR}/css/async`,
+							svg: `${RSBUILD_CLIENT_ASSETS_DIR}/svg`,
+							font: `${RSBUILD_CLIENT_ASSETS_DIR}/font`,
+							wasm: `${RSBUILD_CLIENT_ASSETS_DIR}/wasm`,
+							image: `${RSBUILD_CLIENT_ASSETS_DIR}/image`,
+							media: `${RSBUILD_CLIENT_ASSETS_DIR}/media`,
+							assets: `${RSBUILD_CLIENT_ASSETS_DIR}/assets`,
+						},
+						assetPrefix: opts.publicBase,
+					},
+					resolve: { alias },
+					performance: {
+						chunkSplit: {
+							strategy: 'custom',
+							override: { chunks: 'async' },
+						},
+					},
+				},
+				environmentOverrides.all,
+				environmentOverrides.client,
+			),
+			[RSBUILD_ENVIRONMENT_NAMES.server]: mergeRsbuildConfig(
+				{
+					source: {
+						entry: {
+							index: {
+								import: opts.entryAliases.server,
+								html: false,
+								...(opts.rsc ? { layer: RSBUILD_RSC_LAYERS.ssr } : {}),
+							},
+						},
+					},
+					output: {
+						target: 'node',
+						...(opts.dev ? { module: false } : {}),
+						distPath: { root: opts.serverOutputDirectory },
+					},
+					resolve: { alias },
+					...(opts.rsc ? { splitChunks: { preset: 'single-vendor' } } : {}),
+				},
+				environmentOverrides.all,
+				environmentOverrides.server,
+			),
+			...(opts.serverFnProviderEnv !== RSBUILD_ENVIRONMENT_NAMES.server && !opts.rsc
+				? {
+						[opts.serverFnProviderEnv]: mergeRsbuildConfig(
+							{
+								source: {
+									entry: {
+										index: {
+											import: opts.entryAliases.server,
+											html: false,
+										},
+									},
+								},
+								output: {
+									target: 'node',
+									...(opts.dev ? { module: false } : {}),
+									distPath: { root: `${opts.serverOutputDirectory}/${opts.serverFnProviderEnv}` },
+								},
+								resolve: { alias },
+							},
+							environmentOverrides.all,
+							environmentOverrides.provider,
+						),
+					}
+				: {}),
+		},
+		alias,
+	};
+}
+function resolveRsbuildOutputDirectory(opts) {
+	if (typeof opts.distPath === 'string') return opts.distPath;
+	if (typeof opts.distPath?.root === 'string') return opts.distPath.root;
+	if (typeof opts.rootDistPath === 'string') return join(opts.rootDistPath, opts.subdirectory);
+	if (typeof opts.rootDistPath?.root === 'string')
+		return join(opts.rootDistPath.root, opts.subdirectory);
+	return opts.fallback;
+}
+function normalizeEntryPath(path) {
+	return path.includes('\\') ? path.replaceAll('\\', '/') : path;
+}
+function resolveFromRoot(specifier, root) {
+	return require.resolve(specifier, { paths: [root] });
+}
+//#endregion
+export {
+	RSBUILD_CLIENT_ASSETS_DIR,
+	RSBUILD_ENVIRONMENT_NAMES,
+	RSBUILD_RSC_LAYERS,
+	createRsbuildEnvironmentPlan,
+	createRsbuildResolvedEntryAliases,
+	resolveRsbuildOutputDirectory,
+};

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

@@ -0,0 +1,7 @@
+import { TanStackStartRsbuildPluginCoreOptions } from './types.js';
+import { RsbuildPlugin } from '@rsbuild/core';
+import { TanStackStartRsbuildInputConfig } from './schema.js';
+export declare function tanStackStartRsbuild(
+	corePluginOpts: TanStackStartRsbuildPluginCoreOptions,
+	startPluginOpts?: TanStackStartRsbuildInputConfig,
+): RsbuildPlugin;