@octanejs/tanstack-start 0.1.2 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/tanstack-start",
-  "version": "0.1.2",
+  "version": "0.1.6",
   "description": "TanStack Start for Octane, including file-route generation, server functions, SSR streaming, hydration, and Vite integration.",
   "license": "MIT",
   "type": "module",
@@ -121,7 +121,7 @@
     "magic-string": "^0.30.21",
     "pathe": "^2.0.3",
     "picomatch": "^4.0.3",
-    "prettier": "^3.9.5",
+    "prettier": "^3.9.6",
     "seroval": "^1.5.4",
     "source-map": "^0.7.6",
     "srvx": "^0.11.9",
@@ -131,11 +131,11 @@
     "vitefu": "^1.1.1",
     "xmlbuilder2": "^4.0.3",
     "zod": "^4.4.3",
-    "@octanejs/tanstack-router": "0.1.12"
+    "@octanejs/tanstack-router": "0.1.16"
   },
   "peerDependencies": {
     "vite": ">=7.0.0",
-    "octane": "0.1.13"
+    "octane": "0.1.17"
   },
   "peerDependenciesMeta": {
     "vite": {
@@ -146,7 +146,7 @@
     "@types/node": "^24.13.3",
     "vite": "^8.1.5",
     "vitest": "^4.1.10",
-    "octane": "0.1.13"
+    "octane": "0.1.17"
   },
   "scripts": {
     "test": "cd ../.. && vitest run --project tanstack-start"

package/src/client-only-server-strip.js

@@ -1,22 +1,11 @@
+import MagicString from 'magic-string';
 import { compileToVolarMappings } from 'octane/compiler/volar';
 import { START_ENVIRONMENT_NAMES } from '#tanstack-start/plugin-core/vite';
 
 /**
- * Octane counterpart of the start-compiler's `handleClientOnlyJSX` babel pass:
- * on the SERVER environment, `<ClientOnly>` children are removed at compile
- * time (only the `fallback` prop may render during SSR). The upstream pass
- * operates on React JSX via babel; octane's `.tsrx` compiles its JSX away
- * before any babel-based pass could see it, so this plugin performs the strip
- * on the `.tsrx` SOURCE — replacing the children span with a `{null}` hole —
- * before `octane/compiler/vite` runs.
- *
- * Removing the children (rather than relying on the runtime `ClientOnly`,
- * which already renders nothing during SSR) matters for the STATIC graph:
- * client-only subtrees routinely reference `*.client.*` modules, and Start's
- * import-protection verifies after tree-shaking that no denied module stays
- * reachable from the server bundle. With the children intact, the octane
- * server build retained those edges and failed the build where the react
- * build passes.
+ * Remove the children of the Router ClientOnly binding before Octane compiles
+ * server TSRX. This keeps client-only imports out of the server module graph,
+ * while preserving fallback content and identically-named local components.
  */
 export function octaneClientOnlyServerStrip() {
 	return {
@@ -31,46 +20,442 @@ export function octaneClientOnlyServerStrip() {
 				code: { include: ['ClientOnly'] },
 			},
 			handler(code, id) {
-				if (!code.includes('<ClientOnly')) return undefined;
-
-				const { sourceAst } = compileToVolarMappings(code, id.split('?')[0]);
-				const spans = [];
-				const seen = new Set();
-				const elementName = (node) => node.openingElement?.name?.name ?? node.id?.name;
-				const visit = (value) => {
-					if (!value || typeof value !== 'object' || seen.has(value)) return;
-					seen.add(value);
-					if (Array.isArray(value)) {
-						for (const item of value) visit(item);
-						return;
-					}
-					const children = value.children;
-					if (
-						elementName(value) === 'ClientOnly' &&
-						Array.isArray(children) &&
-						children.length > 0
-					) {
-						const start = children[0].start;
-						const end = children[children.length - 1].end;
-						if (typeof start === 'number' && typeof end === 'number' && end > start) {
-							spans.push([start, end]);
-						}
-					}
-					for (const key in value) {
-						if (key !== 'metadata' && key !== 'loc') visit(value[key]);
-					}
-				};
-				visit(sourceAst);
-				if (spans.length === 0) return undefined;
-
-				// Replace back-to-front so earlier spans keep their offsets.
-				spans.sort((a, b) => b[0] - a[0]);
-				let out = code;
-				for (const [start, end] of spans) {
-					out = `${out.slice(0, start)}{null}${out.slice(end)}`;
+				if (!code.includes('ClientOnly')) return undefined;
+
+				const filename = id.split('?', 1)[0];
+				const { sourceAst } = compileToVolarMappings(code, filename);
+				const childReplacements = stripClientOnlyChildren(sourceAst);
+				if (childReplacements.length === 0) return undefined;
+
+				const prunedImportSpecifiers = findImportsUsedOnlyInRanges(sourceAst, childReplacements);
+				const replacements = [
+					...rewritePrunedImports(code, sourceAst, prunedImportSpecifiers),
+					...childReplacements,
+				];
+				const output = new MagicString(code);
+				for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+					output.overwrite(replacement.start, replacement.end, replacement.content);
 				}
-				return { code: out, map: null };
+
+				return {
+					code: output.toString(),
+					map: output.generateMap({
+						source: filename,
+						includeContent: true,
+						hires: true,
+					}),
+				};
 			},
 		},
 	};
 }
+
+function rewritePrunedImports(code, program, prunedImportSpecifiers) {
+	const replacements = [];
+
+	for (const statement of asNodes(program.body)) {
+		if (
+			statement.type !== 'ImportDeclaration' ||
+			!hasRange(statement) ||
+			!hasRange(statement.source)
+		) {
+			continue;
+		}
+
+		const prunedSpecifiers = prunedImportSpecifiers.get(statement);
+		if (!prunedSpecifiers?.size) continue;
+
+		const remainingSpecifiers = (statement.specifiers ?? []).filter(
+			(specifier) => !prunedSpecifiers.has(specifier),
+		);
+		replacements.push({
+			start: statement.start,
+			end: statement.end,
+			content: printRemainingImport(code, statement, remainingSpecifiers),
+		});
+	}
+
+	return replacements;
+}
+
+function findImportsUsedOnlyInRanges(program, removedRanges) {
+	const bindings = new Map();
+	for (const statement of asNodes(program.body)) {
+		if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type') {
+			continue;
+		}
+		for (const specifier of statement.specifiers ?? []) {
+			const localName = specifier.local?.name;
+			if (specifier.importKind === 'type' || !localName) continue;
+			bindings.set(localName, {
+				declaration: statement,
+				specifier,
+				removed: false,
+				live: false,
+			});
+		}
+	}
+
+	if (bindings.size === 0 || removedRanges.length === 0) return new Map();
+
+	visitImportedBindingReferences(program, bindings, removedRanges);
+
+	const result = new Map();
+	for (const usage of bindings.values()) {
+		// Keep imports that were already unused: importing may intentionally run
+		// module initialization. Only remove bindings whose uses were stripped.
+		if (!usage.removed || usage.live) continue;
+		const specifiers = result.get(usage.declaration) ?? new Set();
+		specifiers.add(usage.specifier);
+		result.set(usage.declaration, specifiers);
+	}
+	return result;
+}
+
+function visitImportedBindingReferences(program, bindings, removedRanges) {
+	const visit = (value, shadowed, parent, parentKey, bindingPattern = false) => {
+		if (!value || typeof value !== 'object') return;
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				visit(item, shadowed, parent, parentKey, bindingPattern);
+			}
+			return;
+		}
+
+		const node = value;
+		if (node.type === 'ImportDeclaration') return;
+
+		const scopedNames = scopeBindings(node);
+		const nextShadowed = scopedNames.size ? new Set([...shadowed, ...scopedNames]) : shadowed;
+
+		if (
+			!bindingPattern &&
+			isBindingReference(node, parent, parentKey) &&
+			node.name &&
+			!nextShadowed.has(node.name)
+		) {
+			const usage = bindings.get(node.name);
+			if (usage && hasRange(node)) {
+				if (isInsideRange(node, removedRanges)) usage.removed = true;
+				else usage.live = true;
+			}
+		}
+
+		for (const [key, child] of Object.entries(node)) {
+			if (key === 'metadata' || key === 'loc' || key === 'parent') continue;
+			visit(child, nextShadowed, node, key, isBindingPatternChild(node, key, bindingPattern));
+		}
+	};
+
+	visit(program, new Set());
+}
+
+function isBindingReference(node, parent, parentKey) {
+	if (node.type === 'Identifier') {
+		if (!parent) return true;
+		if (
+			(parent.type === 'MemberExpression' || parent.type === 'OptionalMemberExpression') &&
+			parentKey === 'property' &&
+			!parent.computed
+		) {
+			return false;
+		}
+		if (
+			(parent.type === 'Property' ||
+				parent.type === 'PropertyDefinition' ||
+				parent.type === 'MethodDefinition') &&
+			parentKey === 'key' &&
+			!parent.computed
+		) {
+			return Boolean(parent.shorthand);
+		}
+		if (parent.type === 'ExportSpecifier') return parentKey === 'local';
+		if (
+			(parent.type === 'LabeledStatement' ||
+				parent.type === 'BreakStatement' ||
+				parent.type === 'ContinueStatement') &&
+			parentKey === 'label'
+		) {
+			return false;
+		}
+		return true;
+	}
+
+	if (node.type !== 'JSXIdentifier' || !node.name || !parent) return false;
+	if (
+		(parent.type === 'JSXOpeningElement' || parent.type === 'JSXClosingElement') &&
+		parentKey === 'name'
+	) {
+		return true;
+	}
+	return parent.type === 'JSXMemberExpression' && parentKey === 'object';
+}
+
+function isBindingPatternChild(parent, key, parentIsBindingPattern) {
+	if (parentIsBindingPattern) {
+		if (parent.type === 'AssignmentPattern') return key === 'left';
+		if (parent.type === 'Property') {
+			return key === 'value' || (key === 'key' && !parent.computed);
+		}
+		return true;
+	}
+
+	if (parent.type === 'VariableDeclarator') return key === 'id';
+	if (isFunction(parent)) return key === 'id' || key === 'params';
+	if (parent.type === 'ClassDeclaration' || parent.type === 'ClassExpression') {
+		return key === 'id';
+	}
+	if (parent.type === 'CatchClause') return key === 'param';
+	if (parent.type === 'ImportSpecifier') return true;
+	return false;
+}
+
+function isInsideRange(node, ranges) {
+	return ranges.some((range) => range.start <= node.start && range.end >= node.end);
+}
+
+function printRemainingImport(code, statement, specifiers) {
+	const sourceNode = statement.source;
+	if (specifiers.length === 0 || !hasRange(sourceNode)) return '';
+
+	const defaultSpecifier = specifiers.find(
+		(specifier) => specifier.type === 'ImportDefaultSpecifier',
+	);
+	const namespaceSpecifier = specifiers.find(
+		(specifier) => specifier.type === 'ImportNamespaceSpecifier',
+	);
+	const namedSpecifiers = specifiers.filter((specifier) => specifier.type === 'ImportSpecifier');
+	const clauses = [];
+
+	if (defaultSpecifier && hasRange(defaultSpecifier)) {
+		clauses.push(code.slice(defaultSpecifier.start, defaultSpecifier.end));
+	}
+	if (namespaceSpecifier && hasRange(namespaceSpecifier)) {
+		clauses.push(code.slice(namespaceSpecifier.start, namespaceSpecifier.end));
+	}
+	if (namedSpecifiers.length > 0) {
+		clauses.push(
+			`{ ${namedSpecifiers
+				.filter(hasRange)
+				.map((specifier) => code.slice(specifier.start, specifier.end))
+				.join(', ')} }`,
+		);
+	}
+
+	const source = code.slice(sourceNode.start, sourceNode.end);
+	const suffix = hasRange(statement) ? code.slice(sourceNode.end, statement.end) : '';
+	return `import ${clauses.join(', ')} from ${source}${suffix}`;
+}
+
+function stripClientOnlyChildren(program) {
+	const importedNames = new Set();
+	for (const statement of asNodes(program.body)) {
+		if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type') {
+			continue;
+		}
+
+		for (const specifier of statement.specifiers ?? []) {
+			if (
+				specifier.type === 'ImportSpecifier' &&
+				specifier.importKind !== 'type' &&
+				specifier.imported?.name === 'ClientOnly' &&
+				specifier.local?.name
+			) {
+				importedNames.add(specifier.local.name);
+			}
+		}
+	}
+
+	if (importedNames.size === 0) return [];
+
+	const replacements = [];
+	const visited = new WeakSet();
+	const visit = (value, shadowed) => {
+		if (!value || typeof value !== 'object' || visited.has(value)) return;
+		visited.add(value);
+
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item, shadowed);
+			return;
+		}
+
+		const node = value;
+		const scopedNames = scopeBindings(node);
+		const nextShadowed = scopedNames.size ? new Set([...shadowed, ...scopedNames]) : shadowed;
+		const elementName = node.openingElement?.name?.name;
+
+		if (
+			node.type === 'JSXElement' &&
+			elementName &&
+			importedNames.has(elementName) &&
+			!nextShadowed.has(elementName) &&
+			node.children?.length
+		) {
+			const first = node.children[0];
+			const last = node.children[node.children.length - 1];
+			if (first && last && hasRange(first) && hasRange(last) && last.end > first.start) {
+				replacements.push({
+					start: first.start,
+					end: last.end,
+					content: '{null}',
+				});
+			}
+		}
+
+		for (const [key, child] of Object.entries(node)) {
+			if (key !== 'metadata' && key !== 'loc' && key !== 'parent') {
+				visit(child, nextShadowed);
+			}
+		}
+	};
+
+	visit(program, new Set());
+
+	// Replacing an outer ClientOnly child range also removes nested boundaries.
+	return replacements.filter(
+		(candidate, index) =>
+			!replacements.some(
+				(other, otherIndex) =>
+					otherIndex !== index && other.start <= candidate.start && other.end >= candidate.end,
+			),
+	);
+}
+
+function scopeBindings(node) {
+	const names = new Set();
+
+	if (isFunction(node)) {
+		for (const param of node.params ?? []) collectBindingNames(param, names);
+		collectBindingNames(node.id, names);
+		for (const statement of directStatements(node.body)) {
+			collectStatementBindings(statement, names);
+		}
+		collectFunctionVarBindings(node.body, names);
+	} else if (node.type === 'BlockStatement' || node.type === 'JSXCodeBlock') {
+		for (const statement of directStatements(node)) {
+			collectStatementBindings(statement, names);
+		}
+	} else if (node.type === 'CatchClause') {
+		collectBindingNames(node.param, names);
+	} else if (
+		node.type === 'ForStatement' ||
+		node.type === 'ForInStatement' ||
+		node.type === 'ForOfStatement'
+	) {
+		const declaration = node.init ?? node.left;
+		if (declaration?.type === 'VariableDeclaration' && declaration.kind !== 'var') {
+			for (const item of declaration.declarations ?? []) {
+				collectBindingNames(item.id, names);
+			}
+		}
+	} else if (node.type === 'SwitchStatement') {
+		for (const switchCase of asNodes(node.cases)) {
+			for (const statement of asNodes(switchCase.consequent)) {
+				collectStatementBindings(statement, names);
+			}
+		}
+	} else if (node.type === 'StaticBlock') {
+		for (const statement of directStatements(node)) {
+			collectStatementBindings(statement, names);
+		}
+	} else if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+		collectBindingNames(node.id, names);
+	}
+
+	return names;
+}
+
+function directStatements(node) {
+	if (Array.isArray(node)) return node;
+	if (!node || !Array.isArray(node.body)) return [];
+	return asNodes(node.body);
+}
+
+function collectStatementBindings(statement, output) {
+	const declaration =
+		statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'
+			? statement.declaration
+			: statement;
+
+	if (declaration?.type === 'VariableDeclaration') {
+		for (const item of declaration.declarations ?? []) {
+			collectBindingNames(item.id, output);
+		}
+	} else if (
+		declaration?.type === 'FunctionDeclaration' ||
+		declaration?.type === 'ClassDeclaration'
+	) {
+		collectBindingNames(declaration.id, output);
+	}
+}
+
+function collectFunctionVarBindings(value, output) {
+	const visited = new WeakSet();
+	const visit = (child, root = false) => {
+		if (!child || typeof child !== 'object' || visited.has(child)) return;
+		visited.add(child);
+
+		if (Array.isArray(child)) {
+			for (const item of child) visit(item);
+			return;
+		}
+
+		const node = child;
+		if (!root && isFunction(node)) return;
+		if (node.type === 'VariableDeclaration' && node.kind === 'var') {
+			for (const item of node.declarations ?? []) {
+				collectBindingNames(item.id, output);
+			}
+		}
+		for (const [key, nested] of Object.entries(node)) {
+			if (key !== 'metadata' && key !== 'loc' && key !== 'parent') {
+				visit(nested);
+			}
+		}
+	};
+
+	visit(value, true);
+}
+
+function collectBindingNames(pattern, output) {
+	if (!pattern) return;
+	if (pattern.type === 'Identifier' && pattern.name) {
+		output.add(pattern.name);
+		return;
+	}
+	if (pattern.type === 'RestElement') {
+		collectBindingNames(pattern.argument, output);
+		return;
+	}
+	if (pattern.type === 'AssignmentPattern') {
+		collectBindingNames(pattern.left, output);
+		return;
+	}
+	if (pattern.type === 'ArrayPattern') {
+		for (const element of asNodes(pattern.elements)) {
+			collectBindingNames(element, output);
+		}
+		return;
+	}
+	if (pattern.type === 'ObjectPattern') {
+		for (const property of asNodes(pattern.properties)) {
+			collectBindingNames(property.argument ?? property.value, output);
+		}
+	}
+}
+
+function isFunction(node) {
+	return (
+		node.type === 'FunctionDeclaration' ||
+		node.type === 'FunctionExpression' ||
+		node.type === 'ArrowFunctionExpression'
+	);
+}
+
+function hasRange(node) {
+	return typeof node?.start === 'number' && typeof node.end === 'number';
+}
+
+function asNodes(value) {
+	return Array.isArray(value) ? value : [];
+}

package/src/internal/router-plugin/core/router-code-splitter-plugin.js

@@ -34,7 +34,7 @@ function createRouterCodeSplitterPlugin(options = {}, routerPluginContext) {
 		if (typeof options === 'function') userConfig = options();
 		else userConfig = getConfig(options, ROOT);
 	}
-	const isProduction = process.env.NODE_ENV === 'production';
+	let isProduction = process.env.NODE_ENV === 'production';
 	const sharedBindingsMap = /* @__PURE__ */ new Map();
 	const getGlobalCodeSplitGroupings = () => {
 		return userConfig.codeSplittingOptions?.defaultBehavior || defaultCodeSplitGroupings;
@@ -159,6 +159,7 @@ function createRouterCodeSplitterPlugin(options = {}, routerPluginContext) {
 			},
 			vite: {
 				configResolved(config) {
+					isProduction = config.command === 'build';
 					ROOT = config.root;
 					initUserConfig();
 					validateFrameworkPluginOrder({
@@ -173,11 +174,13 @@ function createRouterCodeSplitterPlugin(options = {}, routerPluginContext) {
 					return true;
 				},
 			},
-			rspack() {
+			rspack(compiler) {
+				isProduction = compiler.options.mode === 'production';
 				ROOT = process.cwd();
 				initUserConfig();
 			},
-			webpack() {
+			webpack(compiler) {
+				isProduction = compiler.options.mode === 'production';
 				ROOT = process.cwd();
 				initUserConfig();
 			},

package/src/internal/start-plugin-core/import-protection/constants.d.ts

@@ -1,4 +1,3 @@
-export declare const SERVER_FN_LOOKUP_QUERY = '?server-fn-module-lookup';
 export declare const MOCK_MODULE_ID = 'tanstack-start-import-protection:mock';
 export declare const MOCK_BUILD_PREFIX = 'tanstack-start-import-protection:mock:build:';
 export declare const MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:';

package/src/internal/start-plugin-core/import-protection/constants.js

@@ -1,6 +1,4 @@
-import { SERVER_FN_LOOKUP } from '../constants.js';
 //#region src/import-protection/constants.ts
-var SERVER_FN_LOOKUP_QUERY = `?${SERVER_FN_LOOKUP}`;
 var MOCK_MODULE_ID = 'tanstack-start-import-protection:mock';
 var MOCK_BUILD_PREFIX = 'tanstack-start-import-protection:mock:build:';
 var MOCK_EDGE_PREFIX = 'tanstack-start-import-protection:mock-edge:';
@@ -34,6 +32,5 @@ export {
 	MOCK_EDGE_PREFIX,
 	MOCK_MODULE_ID,
 	MOCK_RUNTIME_PREFIX,
-	SERVER_FN_LOOKUP_QUERY,
 	VITE_BROWSER_VIRTUAL_PREFIX,
 };

package/src/internal/start-plugin-core/start-compiler/compiler.js

@@ -850,7 +850,7 @@ var StartCompiler = class {
 		const binding = (await this.getModuleInfo(id)).bindings.get(ident);
 		if (!binding) return 'None';
 		if (binding.resolvedKind) return binding.resolvedKind;
-		const vKey = `${cleanId(id)}:${ident}`;
+		const vKey = `${id}:${ident}`;
 		if (visited.has(vKey)) return 'None';
 		visited.add(vKey);
 		const resolvedKind = await this.resolveBindingKind(binding, id, visited);
@@ -904,7 +904,7 @@ var StartCompiler = class {
 		if (isBuildMode) this.getExportResolutionCache(moduleInfo.id).set(exportName, null);
 	}
 	async resolveBindingTarget(resolution, visited = /* @__PURE__ */ new Set()) {
-		const key = `${cleanId(resolution.moduleInfo.id)}:${resolution.localName}`;
+		const key = `${resolution.moduleInfo.id}:${resolution.localName}`;
 		if (visited.has(key)) return;
 		visited.add(key);
 		if (resolution.binding.type !== 'import') return resolution;
@@ -936,7 +936,7 @@ var StartCompiler = class {
 				const target = found ? ((await this.resolveBindingTarget(found)) ?? found) : void 0;
 				if (
 					target &&
-					cleanId(resolved.moduleInfo.id) === cleanId(target.moduleInfo.id) &&
+					resolved.moduleInfo.id === target.moduleInfo.id &&
 					resolved.localName === target.localName
 				)
 					return kind;
@@ -965,7 +965,7 @@ var StartCompiler = class {
 			return knownKind;
 		}
 		if (found.binding.resolvedKind) return found.binding.resolvedKind;
-		const vKey = `${cleanId(found.moduleInfo.id)}:${found.localName}`;
+		const vKey = `${found.moduleInfo.id}:${found.localName}`;
 		if (visited.has(vKey)) return 'None';
 		visited.add(vKey);
 		const resolvedKind = await this.resolveBindingKind(found.binding, found.moduleInfo.id, visited);

package/src/internal/start-plugin-core/start-compiler/utils.d.ts

@@ -14,6 +14,13 @@ export declare function codeFrameError(
 	},
 	message: string,
 ): Error;
+/**
+ * Converts a bundler module ID to its physical-file identity for diagnostics,
+ * filesystem matching, and file-based invalidation.
+ *
+ * Do not use this for IDs passed to resolve/load hooks or as module cache keys:
+ * virtual prefixes and queries can be part of the module's semantic identity.
+ */
 export declare function cleanId(id: string): string;
 /**
  * Strips a method call by replacing it with its callee object.

package/src/internal/start-plugin-core/start-compiler/utils.js

@@ -15,6 +15,13 @@ function codeFrameError(code, loc, message) {
 	);
 	return new Error(frame);
 }
+/**
+ * Converts a bundler module ID to its physical-file identity for diagnostics,
+ * filesystem matching, and file-based invalidation.
+ *
+ * Do not use this for IDs passed to resolve/load hooks or as module cache keys:
+ * virtual prefixes and queries can be part of the module's semantic identity.
+ */
 function cleanId(id) {
 	if (id.startsWith('\0')) id = id.slice(1);
 	const queryIndex = id.indexOf('?');

package/src/internal/start-plugin-core/vite/import-protection-plugin/plugin.js

@@ -1,9 +1,8 @@
-import { TRANSFORM_ID_REGEX, VITE_ENVIRONMENT_NAMES } from '../../constants.js';
+import { SERVER_FN_LOOKUP, TRANSFORM_ID_REGEX, VITE_ENVIRONMENT_NAMES } from '../../constants.js';
 import { escapeRegExp, resolveViteId } from '../../utils.js';
 import {
 	IMPORT_PROTECTION_DEBUG,
 	MOCK_BUILD_PREFIX,
-	SERVER_FN_LOOKUP_QUERY,
 	VITE_BROWSER_VIRTUAL_PREFIX,
 } from '../../import-protection/constants.js';
 import {
@@ -64,6 +63,7 @@ import {
 	resolveInternalVirtualModuleId,
 	resolvedMarkerVirtualModuleId,
 } from './virtualModules.js';
+import { hasIdQueryFlag } from '../module-id.js';
 import { dirname, relative } from 'pathe';
 import { writeFileSync } from 'node:fs';
 import { normalizePath } from 'vite';
@@ -694,7 +694,7 @@ function importProtectionPlugin(opts) {
 		let merged = null;
 		if (keySet)
 			for (const k of keySet) {
-				if (k.includes(SERVER_FN_LOOKUP_QUERY)) continue;
+				if (hasIdQueryFlag(k, SERVER_FN_LOOKUP)) continue;
 				const imports = env.postTransformImports.get(k);
 				if (imports)
 					if (!merged) merged = new Set(imports);
@@ -721,7 +721,7 @@ function importProtectionPlugin(opts) {
 		let anyVariantCached = false;
 		if (keySet)
 			for (const k of keySet) {
-				if (k.includes(SERVER_FN_LOOKUP_QUERY)) continue;
+				if (hasIdQueryFlag(k, SERVER_FN_LOOKUP)) continue;
 				const imports = env.postTransformImports.get(k);
 				if (imports) {
 					anyVariantCached = true;
@@ -1091,7 +1091,7 @@ function importProtectionPlugin(opts) {
 					}
 					if (source.startsWith('\0') || source.startsWith('virtual:')) return;
 					const normalizedImporter = normalizeFilePath(importer);
-					const isDirectLookup = importer.includes(SERVER_FN_LOOKUP_QUERY);
+					const isDirectLookup = hasIdQueryFlag(importer, SERVER_FN_LOOKUP);
 					if (config.command === 'serve' && config.bundledDev && envType === 'client') {
 						if (
 							isInsideDirectory(normalizedImporter, normalizePath(`${config.srcDirectory}/routes`))
@@ -1432,7 +1432,7 @@ function importProtectionPlugin(opts) {
 					}
 					const cacheKey = normalizePath(id);
 					const envState = getEnv(envName);
-					const isServerFnLookup = id.includes(SERVER_FN_LOOKUP_QUERY);
+					const isServerFnLookup = hasIdQueryFlag(id, SERVER_FN_LOOKUP);
 					if (isServerFnLookup) envState.serverFnLookupModules.add(file);
 					const result = {
 						code,

package/src/internal/start-plugin-core/vite/module-id.d.ts

@@ -0,0 +1,6 @@
+/** Checks for a query parameter without rewriting the opaque module ID. */
+export declare function hasIdQueryFlag(id: string, flag: string): boolean;
+/** Appends an owned query flag without normalizing the existing query. */
+export declare function appendIdQueryFlag(id: string, flag: string): string;
+/** Removes the owned query flag appended by {@link appendIdQueryFlag}. */
+export declare function removeIdQueryFlag(id: string, flag: string): string;

package/src/internal/start-plugin-core/vite/module-id.js

@@ -0,0 +1,23 @@
+//#region src/vite/module-id.ts
+/** Checks for a query parameter without rewriting the opaque module ID. */
+function hasIdQueryFlag(id, flag) {
+	const queryIndex = id.indexOf('?');
+	if (queryIndex === -1) return false;
+	return new URLSearchParams(id.slice(queryIndex + 1)).has(flag);
+}
+/** Appends an owned query flag without normalizing the existing query. */
+function appendIdQueryFlag(id, flag) {
+	if (!id.includes('?')) return `${id}?${flag}`;
+	const separator = id.endsWith('&') ? '' : '&';
+	return `${id}${separator}${flag}`;
+}
+/** Removes the owned query flag appended by {@link appendIdQueryFlag}. */
+function removeIdQueryFlag(id, flag) {
+	for (const separator of ['?', '&']) {
+		const suffix = `${separator}${flag}`;
+		if (id.endsWith(suffix)) return id.slice(0, -suffix.length);
+	}
+	return id;
+}
+//#endregion
+export { appendIdQueryFlag, hasIdQueryFlag, removeIdQueryFlag };

package/src/internal/start-plugin-core/vite/start-compiler-plugin/plugin.js

@@ -15,6 +15,7 @@ import {
 	MissingHydrateSourceError,
 	createHydrateCompilerPlugin,
 } from '../../hydrate-when-transform.js';
+import { appendIdQueryFlag, removeIdQueryFlag } from '../module-id.js';
 import {
 	createViteDevServerFnModuleSpecifierEncoder,
 	decodeViteDevServerModuleSpecifier,
@@ -184,7 +185,7 @@ function startCompilerPlugin(opts) {
 								const code = await loadViteModuleFromEnvironment(this.environment, id, {
 									load: (options) => this.load(options),
 									error: (message) => this.error(message),
-									devId: `${id}?${SERVER_FN_LOOKUP}`,
+									devId: appendIdQueryFlag(id, SERVER_FN_LOOKUP),
 								});
 								if (code !== void 0)
 									compiler.ingestModule({
@@ -195,7 +196,12 @@ function startCompilerPlugin(opts) {
 							resolveId: async (source, importer) => {
 								const r = await this.resolve(source, importer);
 								if (r) {
-									if (!r.external) return cleanId(r.id);
+									if (!r.external) {
+										// Keep the resolved ID intact because it is passed back to
+										// Vite's load hook. Virtual-module prefixes and queries are
+										// part of that load identity, not compiler-only metadata.
+										return r.id;
+									}
 								}
 								return null;
 							},
@@ -288,7 +294,7 @@ function startCompilerPlugin(opts) {
 				handler(code, id) {
 					compilers.get(this.environment.name)?.ingestModule({
 						code,
-						id: cleanId(id),
+						id: removeIdQueryFlag(id, SERVER_FN_LOOKUP),
 					});
 				},
 			},

package/src/plugin-vite.d.ts

@@ -12,7 +12,15 @@ export type OctaneRendererDescriptor = Exclude<OctaneRendererRegistryEntry, stri
 export type OctaneRendererBoundary = OctaneRendererBoundaryOptions;
 export type OctaneRendererRule = OctaneRendererRuleOptions;
 export type OctaneRendererConfig = OctaneRendererConfigOptions;
-export type OctaneCompilerOptions = Omit<OctaneVitePluginOptions, 'ssr'>;
+export type OctaneCompilerOptions = Omit<OctaneVitePluginOptions, 'ssr'> & {
+	/**
+	 * Shorthand for the compiler's command-aware profiling signal (mirrors
+	 * `@octanejs/vite-plugin`'s `devtools` option): enables profiling in `vite
+	 * dev` only, fully compiled out of `vite build`. An explicit `profile`
+	 * always takes precedence over `devtools`.
+	 */
+	devtools?: boolean;
+};
 
 export type TanStackOctaneStartViteInputConfig = TanStackStartViteInputConfig & {
 	octane?: OctaneCompilerOptions;

package/src/plugin-vite.js

@@ -31,6 +31,20 @@ export function tanstackStart(options) {
 	const { octane: octaneOptions, ...startOptions } = options ?? {};
 	validateOctaneCompilerOptions(octaneOptions);
 
+	// `devtools: true` is Start's shorthand for the compiler's command-aware
+	// profiling signal (mirrors `@octanejs/vite-plugin`'s `devtools` option): an
+	// explicit `profile` always wins, otherwise `devtools` maps to `'auto'`
+	// (profiling on in `vite dev`, compiled out of `vite build`). `octane()`
+	// itself only understands `profile`, so this is resolved before the plugin
+	// is created and the `devtools` key never reaches it.
+	const resolvedOctaneOptions = octaneOptions ? { ...octaneOptions } : octaneOptions;
+	if (resolvedOctaneOptions) {
+		if (resolvedOctaneOptions.profile === undefined && resolvedOctaneOptions.devtools === true) {
+			resolvedOctaneOptions.profile = 'auto';
+		}
+		delete resolvedOctaneOptions.devtools;
+	}
+
 	const corePluginOptions = {
 		framework: 'octane',
 		defaultEntryPaths: octaneStartDefaultEntryPaths,
@@ -44,7 +58,7 @@ export function tanstackStart(options) {
 		// Must run before the octane compiler: strips <ClientOnly> children on
 		// the server (the octane analogue of start-compiler handleClientOnlyJSX).
 		octaneClientOnlyServerStrip(),
-		octane(octaneOptions),
+		octane(resolvedOctaneOptions),
 		{
 			name: 'octanejs-tanstack-start:workspace-source-deps',
 			configEnvironment(environmentName, environmentOptions) {