@octanejs/tanstack-start 0.2.8 → 0.2.10

package/README.md

@@ -50,11 +50,31 @@ import { createServerFn } from '@octanejs/tanstack-start';
 import { createFileRoute } from '@octanejs/tanstack-router';
 ```
 
+## Compiled Router integration
+
+Use `tanstackStart({ compiled: true })` in either build plugin for routes authored
+as compiled Octane template bodies. This selects matching default Start entries,
+route scaffolds, generated route-tree imports, and lazy route imports. Existing
+custom `client.entry` and `server.entry` options retain precedence.
+
+Import routing APIs from `@octanejs/tanstack-router/compiled` throughout that
+route tree. A custom client entry uses `StartClient` and `hydrateStart` from
+`@octanejs/tanstack-start/compiled/client`; a custom server uses `StartServer`,
+`defaultStreamHandler`, or `defaultRenderHandler` from
+`@octanejs/tanstack-start/compiled/server`. The package-root server-function APIs
+remain unchanged. Do not mix the ordinary and compiled Router contexts.
+
+The compiled Start components retain the existing document hydration owner and
+ready acknowledgement. The option selects the compiled rendering boundary; it
+does not declare the entire Router or Start package Strong-compliant.
+
 ## Public entries
 
 - `@octanejs/tanstack-start`
 - `@octanejs/tanstack-start/client`
 - `@octanejs/tanstack-start/server`
+- `@octanejs/tanstack-start/compiled/client`
+- `@octanejs/tanstack-start/compiled/server`
 - `@octanejs/tanstack-start/plugin/vite`
 - `@octanejs/tanstack-start/plugin/rsbuild`
 - RPC and environment-marker entries used by the Start compiler

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/tanstack-start",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "TanStack Start for Octane, including file-route generation, server functions, SSR streaming, hydration, and Vite or Rsbuild integration.",
   "license": "MIT",
   "type": "module",
@@ -107,10 +107,13 @@
       "import": "./src/server-entry.js",
       "default": "./src/server-entry.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./compiled/client": "./src/compiled/client.ts",
+    "./compiled/server": "./src/compiled/server.ts"
   },
   "sideEffects": [
-    "./src/default-entry/client.js"
+    "./src/default-entry/client.js",
+    "./src/compiled/default-client.js"
   ],
   "dependencies": {
     "@babel/code-frame": "7.27.1",
@@ -118,7 +121,7 @@
     "@babel/template": "^7.27.2",
     "@babel/types": "^7.28.5",
     "@octanejs/rspack-plugin": "0.2.4",
-    "@octanejs/tanstack-router": "0.2.7",
+    "@octanejs/tanstack-router": "0.2.9",
     "@tanstack/router-core": "1.171.34",
     "@tanstack/router-utils": "1.162.2",
     "@tanstack/start-client-core": "1.170.34",
@@ -158,7 +161,7 @@
   "devDependencies": {
     "@rsbuild/core": "^2.1.6",
     "@types/node": "^24.13.3",
-    "octane": "0.13.2",
+    "octane": "0.13.7",
     "vite": "^8.1.5",
     "vitest": "^4.1.10"
   },

package/src/compiled/StartClient.tsrx

@@ -0,0 +1,18 @@
+'use strong';
+
+import { HYDRATION_RANGE_BOUNDARY, useEffect } from 'octane';
+import { RouterProvider } from '@octanejs/tanstack-router/compiled';
+import type { AnyRouter } from '@tanstack/router-core';
+
+export interface StartClientProps {
+	router: AnyRouter;
+}
+
+export function StartClient({ router }: StartClientProps) @{
+	useEffect(() => {
+		window.$_TSR?.h();
+	});
+	<RouterProvider router={router} />
+}
+
+StartClient[HYDRATION_RANGE_BOUNDARY] = 'passthrough';

package/src/compiled/StartServer.tsrx

@@ -0,0 +1,12 @@
+'use strong';
+
+import { RouterProvider } from '@octanejs/tanstack-router/compiled';
+import type { AnyRouter } from '@tanstack/router-core';
+
+export interface StartServerProps {
+	router: AnyRouter;
+}
+
+export function StartServer({ router }: StartServerProps) @{
+	<RouterProvider router={router} />
+}

package/src/compiled/client.ts

@@ -0,0 +1,2 @@
+export { StartClient, type StartClientProps } from './StartClient.tsrx';
+export { hydrateStart } from '../runtime/client/hydrateStart.js';

package/src/compiled/default-client.js

@@ -0,0 +1,12 @@
+import { hydrateRoot, initializeHydrationEventCapture } from 'octane';
+import { StartClient, hydrateStart } from './client.ts';
+
+initializeHydrationEventCapture();
+
+hydrateStart().then((router) => {
+	const container = document.getElementById('__app');
+	if (!container) {
+		throw new Error('TanStack Start could not find the Octane hydration root.');
+	}
+	hydrateRoot(container, StartClient, { router });
+});

package/src/compiled/default-server.js

@@ -0,0 +1,9 @@
+import { createStartHandler, defaultStreamHandler } from './server.ts';
+
+const handler = createStartHandler(defaultStreamHandler);
+
+export default {
+	async fetch(...args) {
+		return await handler(...args);
+	},
+};

package/src/compiled/server.ts

@@ -0,0 +1,15 @@
+import { defineHandlerCallback } from '@tanstack/start-server-core';
+import { renderRouterToString, renderRouterToStream } from '@octanejs/tanstack-router/ssr/server';
+import { StartServer } from './StartServer.tsrx';
+
+export { StartServer, type StartServerProps } from './StartServer.tsrx';
+export * from '@tanstack/start-server-core';
+
+export const defaultRenderHandler = defineHandlerCallback(({ router, responseHeaders }) =>
+	renderRouterToString({ router, responseHeaders, App: StartServer }),
+);
+
+export const defaultStreamHandler = defineHandlerCallback(
+	async ({ request, router, responseHeaders }) =>
+		await renderRouterToStream({ request, router, responseHeaders, App: StartServer }),
+);

package/src/default-entry-paths.d.ts

@@ -3,3 +3,5 @@ export declare const octaneStartDefaultEntryPaths: {
 	server: string;
 	start: string;
 };
+
+export declare const octaneStartCompiledEntryPaths: typeof octaneStartDefaultEntryPaths;

package/src/default-entry-paths.js

@@ -9,3 +9,9 @@ export const octaneStartDefaultEntryPaths = {
 	server: path.resolve(defaultEntryDirectory, 'server.js'),
 	start: path.resolve(defaultEntryDirectory, 'start.js'),
 };
+
+export const octaneStartCompiledEntryPaths = {
+	client: path.resolve(sourceDirectory, 'compiled/default-client.js'),
+	server: path.resolve(sourceDirectory, 'compiled/default-server.js'),
+	start: octaneStartDefaultEntryPaths.start,
+};

package/src/internal/router-generator/config.d.ts

@@ -25,6 +25,7 @@ export type TokenMatcher = z.infer<typeof tokenMatcherSchema>;
 export declare const routerFrameworks: readonly ['react', 'solid', 'vue', 'octane'];
 export declare const baseConfigSchema: z.ZodObject<
 	{
+		compiled: z.ZodOptional<z.ZodBoolean>;
 		target: z.ZodDefault<
 			z.ZodOptional<
 				z.ZodEnum<{
@@ -119,6 +120,7 @@ export declare const baseConfigSchema: z.ZodObject<
 export type BaseConfig = z.infer<typeof baseConfigSchema>;
 export declare const configSchema: z.ZodObject<
 	{
+		compiled: z.ZodOptional<z.ZodBoolean>;
 		target: z.ZodDefault<
 			z.ZodOptional<
 				z.ZodEnum<{

package/src/internal/router-generator/config.js

@@ -10,6 +10,7 @@ var tokenJsonRegexSchema = z.object({
 var tokenMatcherSchema = z.union([z.string(), z.instanceof(RegExp), tokenJsonRegexSchema]);
 var baseConfigSchema = z.object({
 	target: z.enum(['react', 'solid', 'vue', 'octane']).optional().default('react'),
+	compiled: z.boolean().optional(),
 	virtualRouteConfig: virtualRootRouteSchema.or(z.string()).optional(),
 	routeFilePrefix: z.string().optional(),
 	routeFileIgnorePrefix: z.string().optional().default('-'),

package/src/internal/router-generator/generator.js

@@ -755,6 +755,7 @@ ${acc.routeTree.map((child) => `${child.variableName}Route: typeof ${getResolved
 				filename: node.fullPath,
 				ctx: {
 					target: this.config.target,
+					compiled: this.config.compiled,
 					routeId: escapedRoutePath,
 					lazy: node._fsRouteType === 'lazy',
 				},

package/src/internal/router-generator/template.js

@@ -163,9 +163,12 @@ function getTargetTemplate(config) {
 					},
 				},
 			};
-		case 'octane':
+		case 'octane': {
+			const routerPackage = config.compiled
+				? `${OCTANE_ROUTER_PACKAGE}/compiled`
+				: OCTANE_ROUTER_PACKAGE;
 			return {
-				fullPkg: OCTANE_ROUTER_PACKAGE,
+				fullPkg: routerPackage,
 				subPkg: 'octane-router',
 				rootRoute: {
 					template: () =>
@@ -176,7 +179,7 @@ function getTargetTemplate(config) {
 							'function RootComponent() @{\n <div>Hello "%%tsrPath%%"!<Outlet /></div>\n}\n',
 						].join(''),
 					imports: {
-						tsrImports: () => `import { Outlet, createRootRoute } from '${OCTANE_ROUTER_PACKAGE}';`,
+						tsrImports: () => `import { Outlet, createRootRoute } from '${routerPackage}';`,
 						tsrExportStart: () => 'export const Route = createRootRoute(',
 						tsrExportEnd: () => ');',
 					},
@@ -190,7 +193,7 @@ function getTargetTemplate(config) {
 							'function RouteComponent() @{\n <div>Hello "%%tsrPath%%"!</div>\n}\n',
 						].join(''),
 					imports: {
-						tsrImports: () => `import { createFileRoute } from '${OCTANE_ROUTER_PACKAGE}';`,
+						tsrImports: () => `import { createFileRoute } from '${routerPackage}';`,
 						tsrExportStart: (routePath) =>
 							`export const Route = createFileRoute(${serializeRoutePath(routePath)})(`,
 						tsrExportEnd: () => ');',
@@ -205,13 +208,14 @@ function getTargetTemplate(config) {
 							'function RouteComponent() @{\n <div>Hello "%%tsrPath%%"!</div>\n}\n',
 						].join(''),
 					imports: {
-						tsrImports: () => `import { createLazyFileRoute } from '${OCTANE_ROUTER_PACKAGE}';`,
+						tsrImports: () => `import { createLazyFileRoute } from '${routerPackage}';`,
 						tsrExportStart: (routePath) =>
 							`export const Route = createLazyFileRoute(${serializeRoutePath(routePath)})(`,
 						tsrExportEnd: () => ');',
 					},
 				},
 			};
+		}
 		default:
 			throw new Error(`router-generator: Unknown target type: ${target}`);
 	}

package/src/internal/router-generator/transform/transform.js

@@ -60,7 +60,25 @@ function transform({ ctx, source, parseSource, filename, node }) {
 	const expectedCallee = getExpectedRouteConstructor(ctx.lazy);
 	const expectedRouteId = `${routeIdQuote}${ctx.routeId}${routeIdQuote}`;
 	const currentRouteId = source.slice(routeCall.routeIdArg.start, routeCall.routeIdArg.end);
-	const targetModule = getRouterPackage(ctx.target);
+	const targetModule =
+		getRouterPackage(ctx.target) + (ctx.target === 'octane' && ctx.compiled ? '/compiled' : '');
+	if (ctx.target === 'octane') {
+		const otherModule = getRouterPackage(ctx.target) + (ctx.compiled ? '' : '/compiled');
+		const mixedImport = ast.program.body.some(
+			(statement) =>
+				t.isImportDeclaration(statement) &&
+				statement.source.value === otherModule &&
+				statement.importKind !== 'type' &&
+				statement.specifiers.some((specifier) => specifier.importKind !== 'type'),
+		);
+		if (mixedImport)
+			return {
+				result: 'error',
+				error: new Error(
+					`Route ${filename ?? ctx.routeId} imports ${otherModule}, but this build uses ${targetModule}. Use the matching Router entry throughout the route tree and set tanstackStart({ compiled: ${Boolean(ctx.compiled)} }) consistently.`,
+				),
+			};
+	}
 	const imports = parseTargetImports(ast.program.body, source, targetModule);
 	const s = new MagicString(source);
 	let modified = false;

package/src/internal/router-generator/transform/types.d.ts

@@ -29,6 +29,7 @@ export type TransformResult =
 	  };
 export interface TransformContext {
 	target: Config['target'];
+	compiled?: boolean;
 	routeId: string;
 	lazy: boolean;
 }

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

@@ -253,7 +253,10 @@ function compileCodeSplitReferenceRoute(opts) {
 		return opts.codeSplitGroupings.findIndex((group) => group.includes(str));
 	}
 	const frameworkOptions = getFrameworkOptions(opts.targetFramework);
-	const PACKAGE = frameworkOptions.package;
+	const PACKAGE =
+		opts.targetFramework === 'octane' && opts.compiled
+			? `${frameworkOptions.package}/compiled`
+			: frameworkOptions.package;
 	const LAZY_ROUTE_COMPONENT_IDENT = frameworkOptions.idents.lazyRouteComponent;
 	const LAZY_FN_IDENT = frameworkOptions.idents.lazyFn;
 	const stableRouteOptionKeys = [

package/src/internal/router-plugin/core/code-splitter/plugins.d.ts

@@ -7,6 +7,7 @@ export type CompileCodeSplitReferenceRouteOptions = {
 	codeSplitGroupings: CodeSplitGroupings;
 	deleteNodes?: Set<DeletableNodes>;
 	targetFramework: Config['target'];
+	compiled?: boolean;
 	filename: string;
 	id: string;
 	addHmr?: boolean;

package/src/internal/router-plugin/core/config.d.ts

@@ -55,6 +55,7 @@ type FileRouteKeys = keyof (Parameters<CreateFileRoute<any, any, any, any, any>>
 export type DeletableNodes = FileRouteKeys | (string & {});
 export declare const configSchema: z.ZodObject<
 	{
+		compiled: z.ZodOptional<z.ZodBoolean>;
 		target: z.ZodDefault<
 			z.ZodOptional<
 				z.ZodEnum<{

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

@@ -83,6 +83,7 @@ function createRouterCodeSplitterPlugin(options = {}, routerPluginContext) {
 			code,
 			codeSplitGroupings: splitGroupings,
 			targetFramework: userConfig.target,
+			compiled: userConfig.compiled,
 			filename: id,
 			id,
 			deleteNodes: userConfig.codeSplittingOptions?.deleteNodes

package/src/internal/start-plugin-core/config-context.d.ts

@@ -13,6 +13,7 @@ export declare function createStartConfigContext<TInputConfig>(opts: {
 		opts: TInputConfig | undefined,
 		core: {
 			framework: TanStackStartCoreOptions['framework'];
+			compiled?: boolean;
 		},
 		root: string,
 	) => TanStackStartOutputConfig;

package/src/internal/start-plugin-core/config-context.js

@@ -33,7 +33,7 @@ function createStartConfigContext(opts) {
 		if (!startConfig)
 			startConfig = opts.parseConfig(
 				opts.startPluginOpts,
-				{ framework: opts.corePluginOpts.framework },
+				{ framework: opts.corePluginOpts.framework, compiled: opts.corePluginOpts.compiled },
 				requireRoot(),
 			);
 		return startConfig;

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

@@ -1741,6 +1741,7 @@ export declare function parseStartConfig(
 	opts: z.input<typeof tanstackStartRsbuildOptionsSchema>,
 	corePluginOpts: {
 		framework: CompileStartFrameworkOptions;
+		compiled?: boolean;
 	},
 	root: string,
 ): {

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

@@ -1,3 +1,4 @@
+import { composeGeneratorPlugins } from '../start-router-plugin/generator-plugins/compose-generator-plugins.js';
 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';
@@ -35,10 +36,16 @@ function registerRouterPlugins(api, opts) {
 							corePluginOpts: opts.corePluginOpts,
 						});
 					},
-					plugins: [
-						routesManifestPlugin(),
-						...(opts.startPluginOpts.prerender?.enabled === true ? [prerenderRoutesPlugin()] : []),
-					],
+					plugins: composeGeneratorPlugins({
+						frameworkPlugins: opts.corePluginOpts.routerGeneratorPlugins,
+						userPlugins: routerConfig.plugins,
+						builtInPlugins: [
+							routesManifestPlugin(),
+							...(opts.startPluginOpts.prerender?.enabled === true
+								? [prerenderRoutesPlugin()]
+								: []),
+						],
+					}),
 				},
 				routerPluginContext,
 			);

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

@@ -118,6 +118,7 @@ export declare function parseStartConfig(
 	opts: z.input<typeof tanstackStartOptionsSchema>,
 	corePluginOpts: {
 		framework: CompileStartFrameworkOptions;
+		compiled?: boolean;
 	},
 	root: string,
 ): {

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

@@ -68,6 +68,7 @@ function parseStartConfig(opts, corePluginOpts, root) {
 				{
 					...options.router,
 					target: corePluginOpts.framework,
+					compiled: corePluginOpts.compiled,
 					routesDirectory,
 					generatedRouteTree,
 				},

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

@@ -107,6 +107,7 @@ export interface NormalizedClientBuild {
 }
 export interface TanStackStartCoreOptions {
 	framework: CompileStartFrameworkOptions;
+	compiled?: boolean;
 	defaultEntryPaths: {
 		client: string;
 		server: string;

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

@@ -1720,6 +1720,7 @@ export declare function parseStartConfig(
 	opts: z.input<typeof tanstackStartViteOptionsSchema>,
 	corePluginOpts: {
 		framework: CompileStartFrameworkOptions;
+		compiled?: boolean;
 	},
 	root: string,
 ): {

package/src/plugin-rsbuild.d.ts

@@ -17,6 +17,8 @@ export type TanStackOctaneStartRsbuildInputConfig = Omit<
 	TanStackStartRsbuildInputConfig,
 	'octane'
 > & {
+	/** Use compiled route bodies and the compiled Router document boundary. */
+	compiled?: boolean;
 	octane?: OctaneCompilerOptions;
 };
 

package/src/plugin-rsbuild.js

@@ -5,7 +5,10 @@ import {
 } from '#tanstack-start/plugin-core/rsbuild';
 import { OctaneRspackPlugin } from '@octanejs/rspack-plugin';
 import { octaneRouteGeneratorPlugin } from '@octanejs/tanstack-router/generator-plugin';
-import { octaneStartDefaultEntryPaths } from './default-entry-paths.js';
+import {
+	octaneStartDefaultEntryPaths,
+	octaneStartCompiledEntryPaths,
+} from './default-entry-paths.js';
 import { validateOctaneCompilerOptions } from './validate-options.js';
 
 const clientOnlyStripLoaderPath = fileURLToPath(
@@ -13,13 +16,14 @@ const clientOnlyStripLoaderPath = fileURLToPath(
 );
 
 export function tanstackStart(options) {
-	const { octane: octaneOptions, ...startOptions } = options ?? {};
+	const { octane: octaneOptions, compiled = false, ...startOptions } = options ?? {};
 	validateOctaneCompilerOptions(octaneOptions);
 
 	const corePlugin = tanStackStartRsbuild(
 		{
 			framework: 'octane',
-			defaultEntryPaths: octaneStartDefaultEntryPaths,
+			compiled,
+			defaultEntryPaths: compiled ? octaneStartCompiledEntryPaths : octaneStartDefaultEntryPaths,
 			providerEnvironmentName: RSBUILD_ENVIRONMENT_NAMES.server,
 			ssrIsProvider: true,
 			routerGeneratorPlugins: [octaneRouteGeneratorPlugin()],

package/src/plugin-vite.d.ts

@@ -23,6 +23,8 @@ export type OctaneCompilerOptions = Omit<OctaneVitePluginOptions, 'ssr'> & {
 };
 
 export type TanStackOctaneStartViteInputConfig = TanStackStartViteInputConfig & {
+	/** Use compiled route bodies and the compiled Router document boundary. */
+	compiled?: boolean;
 	octane?: OctaneCompilerOptions;
 };
 

package/src/plugin-vite.js

@@ -2,7 +2,10 @@ import { START_ENVIRONMENT_NAMES, tanStackStartVite } from '#tanstack-start/plug
 import { octaneRouteGeneratorPlugin } from '@octanejs/tanstack-router/generator-plugin';
 import { octane } from 'octane/compiler/vite';
 import { octaneClientOnlyServerStrip } from './client-only-server-strip.js';
-import { octaneStartDefaultEntryPaths } from './default-entry-paths.js';
+import {
+	octaneStartDefaultEntryPaths,
+	octaneStartCompiledEntryPaths,
+} from './default-entry-paths.js';
 import { validateOctaneCompilerOptions } from './validate-options.js';
 
 // The Start runtime chain must be source-served. Its compiler removes
@@ -28,7 +31,7 @@ const WORKSPACE_SOURCE_INCLUDES = [
 ];
 
 export function tanstackStart(options) {
-	const { octane: octaneOptions, ...startOptions } = options ?? {};
+	const { octane: octaneOptions, compiled = false, ...startOptions } = options ?? {};
 	validateOctaneCompilerOptions(octaneOptions);
 
 	// `devtools: true` is Start's shorthand for the compiler's command-aware
@@ -47,7 +50,8 @@ export function tanstackStart(options) {
 
 	const corePluginOptions = {
 		framework: 'octane',
-		defaultEntryPaths: octaneStartDefaultEntryPaths,
+		compiled,
+		defaultEntryPaths: compiled ? octaneStartCompiledEntryPaths : octaneStartDefaultEntryPaths,
 		providerEnvironmentName: START_ENVIRONMENT_NAMES.server,
 		ssrIsProvider: true,
 		ssrResolverStrategy: { type: 'default' },