@octanejs/tanstack-router 0.2.6 → 0.2.8

package/README.md

@@ -134,3 +134,51 @@ package's `status.json`).
 - **Native DOM events** — link callbacks receive browser events rather than React
   synthetic events.
 - Router devtools are distributed separately and are not part of this binding.
+
+## Compiled code routes
+
+Use `@octanejs/tanstack-router/compiled` for a tree whose selected route, pending,
+error and not-found components are compiled Octane `@{ ... }` bodies. Its
+`CompiledRouterProvider`, `CompiledOutlet`, and `lazyCompiledRouteComponent`
+avoid retaining the descriptor renderer merely to select a route at runtime.
+TanStack still owns the matching, loading, navigation, history and render
+acknowledgements.
+
+```tsx
+import {
+  BaseRootRoute, BaseRoute, createRouter, createBrowserHistory,
+  CompiledRouterProvider, CompiledOutlet, lazyCompiledRouteComponent, useParams,
+} from '@octanejs/tanstack-router/compiled';
+
+const root = new BaseRootRoute({ component: Layout });
+const item = new BaseRoute({
+  getParentRoute: () => root,
+  path: 'items/$id',
+  component: lazyCompiledRouteComponent(() => import('./Item')),
+});
+const router = createRouter({
+  routeTree: root.addChildren([item]),
+  history: createBrowserHistory(),
+});
+
+function Layout() @{
+  <main><CompiledOutlet /></main>
+}
+function App() @{
+  <CompiledRouterProvider router={router} />
+}
+```
+
+Import read/navigation hooks (`useMatch`, `useParams`, `useSearch`,
+`useLoaderData`, `useLoaderDeps`, `useRouteContext`, `useLocation`,
+`useMatches`, `useParentMatches`, `useChildMatches`, `useNavigate`,
+`useCanGoBack`, `useRouter`, and `useRouterState`) from the same `/compiled`
+entry. It owns a separate pair of non-callable contexts. Base route factories
+come directly from router-core: use the free hooks in the route components,
+rather than route-bound hooks or `Route.Link` from the normal Octane entry.
+
+The first compiled contract excludes `Wrap`, `InnerWrap`, and
+`shellComponent`; the provider reports a diagnostic if they are configured.
+For returned JSX, host strings, renderable wrappers or mixed route trees, retain
+`RouterProvider`, `Outlet` and `lazyRouteComponent` from the ordinary entry.
+SSR and client builds must select the same entry for a tree.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/tanstack-router",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -37,6 +37,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./history": "./src/history.ts",
+    "./compiled": "./src/compiled.ts",
     "./ssr/server": {
       "types": "./src/ssr/server.ts",
       "default": "./src/ssr/server.ts"
@@ -58,13 +59,13 @@
     "isbot": "^5.1.22"
   },
   "peerDependencies": {
-    "octane": "^0.12.0"
+    "octane": "^0.13.0"
   },
   "devDependencies": {
     "@tanstack/react-router": "1.170.41",
     "@tsrx/react": "^0.4.5",
     "esbuild": "^0.28.1",
-    "octane": "0.12.0",
+    "octane": "0.13.6",
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "vitest": "^4.1.10"

package/src/Matches.tsrx

@@ -32,7 +32,7 @@ export function Matches() @{
 	useLayoutEffect(() => {
 		if (router.options.scrollRestoration) setupScrollRestoration(router);
 	}, [router]);
-	useTransitioner();
+	useTransitioner(router);
 
 	<InnerWrap>
 		<Suspense fallback={pendingElement}>

package/src/Transitioner.tsrx

@@ -19,7 +19,7 @@
 //      restoration, devtools) fire.
 import { useLayoutEffect, useState, startTransition } from 'octane';
 import { getLocationChangeInfo, trimPathRight } from '@tanstack/router-core';
-import { useRouter } from './context.ts';
+import type { AnyRouter } from '@tanstack/router-core';
 
 // Resolve the pending render acknowledgement with whether the expected matches
 // rendered, then clear the slot. `owner` is `router._rendered`: `[expected, resolve]`.
@@ -29,8 +29,8 @@ export function settleOwner(owner: Array<any>, rendered: boolean) {
 	settle?.(rendered);
 }
 
-export function useTransitioner() {
-	const router = useRouter() as any;
+export function useTransitioner(routerInstance: AnyRouter) {
+	const router = routerInstance as any;
 	const [, forceRender] = useState<object>();
 
 	const acknowledgement: Array<any> = (router._rendered ??= []);

package/src/compiled/Matches.tsrx

@@ -0,0 +1,266 @@
+import {
+	CompiledOutlet as CompiledComponent,
+	CompiledContext,
+	useContext,
+	useLayoutEffect,
+	useRef,
+} from 'octane';
+import type { NotFoundError } from '@tanstack/router-core';
+import { hasKeys, isNotFound, rootRouteId, setupScrollRestoration } from '@tanstack/router-core';
+import { getScrollRestorationScriptForRouter } from '@tanstack/router-core/scroll-restoration-script';
+import { isServer } from '@tanstack/router-core/isServer';
+import { routerContext, matchContext, useRouter } from './bindings';
+import { useStore } from '../useStore';
+import { useTransitioner, settleOwner } from '../Transitioner.tsrx';
+import { useHydrated } from '../ClientOnly.tsrx';
+import { ErrorComponent } from '../CatchBoundary.tsrx';
+import { createLazyRouteLoader } from '../lazyRouteLoader';
+import type { RouterProps } from '../RouterProvider.tsrx';
+
+export function CompiledRouterProvider(props: RouterProps) @{
+	const { router, ...rest } = props;
+	if (hasKeys(rest)) {
+		router.update({
+			...router.options,
+			...rest,
+			context: { ...router.options.context, ...rest.context },
+		});
+	}
+	if (router.options.Wrap || router.options.InnerWrap) {
+		throw new Error(
+			'CompiledRouterProvider does not accept Wrap or InnerWrap. Use RouterProvider for renderable wrappers.',
+		);
+	}
+	<CompiledContext context={routerContext} value={router}>
+		<CompiledMatches />
+	</CompiledContext>
+}
+
+function CompiledMatches() @{
+	const router = useRouter();
+	const rootRoute = (router.routesById as any)[rootRouteId];
+	useLayoutEffect(() => {
+		if (router.options.scrollRestoration) setupScrollRestoration(router);
+	}, [router]);
+	useTransitioner(router);
+	@try {
+		<CompiledMatchesInner />
+	} @pending {
+		<CompiledPending route={rootRoute} />
+	} @catch (error, reset) {
+		if (router.options.disableGlobalCatchBoundary) throw error;
+		<CompiledFailure error={error} reset={reset} route={rootRoute} global={true} />
+	}
+}
+
+function CompiledMatchesInner() @{
+	const router = useRouter();
+	const acknowledgement: Array<any> = ((router as any)._rendered ??= []);
+	const matches = useStore(router.stores.matches, (m: any) => acknowledgement[0] ?? m);
+	const rootMatch = matches[0];
+	useLayoutEffect(() => {
+		if (acknowledgement[0] === matches) settleOwner(acknowledgement, true);
+	}, [acknowledgement, matches]);
+	@if (rootMatch) {
+		<CompiledMatch routeId={rootMatch.routeId} />
+	}
+}
+
+function CompiledMatch(props: { routeId: string }) @{
+	const router = useRouter();
+	const store = router.stores.getMatchStore(props.routeId);
+	const ssr = useStore(store, (match: any) => match.ssr);
+	const route = (router.routesById as Record<string, any>)[props.routeId];
+	if (route.isRoot && route.options.shellComponent) {
+		throw new Error(
+			'CompiledRouterProvider does not accept shellComponent. Use RouterProvider for renderable document shells.',
+		);
+	}
+	const pending = route.options.pendingComponent ?? router.options.defaultPendingComponent;
+	const errorComponent = route.options.errorComponent ?? router.options.defaultErrorComponent;
+	const noSsr = ssr === false || ssr === 'data-only';
+	const hasSuspense =
+		(!route.isRoot || route.options.wrapInSuspense || noSsr) &&
+		((route.options.wrapInSuspense ?? pending ?? errorComponent?.preload) || noSsr);
+	<CompiledContext context={matchContext} value={props.routeId}>
+		@if (hasSuspense) {
+			@try {
+				<CompiledMatchContent route={route} routeId={props.routeId} noSsr={noSsr} />
+			} @pending {
+				<CompiledPending route={route} />
+			}
+		} @else {
+			<CompiledMatchContent route={route} routeId={props.routeId} noSsr={noSsr} />
+		}
+		@if (route.parentRoute?.id === rootRouteId && router.options.scrollRestoration) {
+			<CompiledScrollRestoration />
+		}
+	</CompiledContext>
+}
+
+// Without a configured Suspense boundary, both lazy imports and loader promises
+// pass through to the next ancestor boundary. The match still owns its errors.
+function CompiledMatchContent(props: { route: any; routeId: string; noSsr: boolean }) @{
+	@try {
+		<CompiledMatchInner routeId={props.routeId} noSsr={props.noSsr} />
+	} @catch (error, reset) {
+		<CompiledFailure error={error} reset={reset} route={props.route} />
+	}
+}
+
+function CompiledMatchInner(props: { routeId: string; noSsr: boolean }) @{
+	const router = useRouter();
+	const match = useStore(router.stores.getMatchStore(props.routeId), (m: any) => m);
+	const route = (router.routesById as Record<string, any>)[props.routeId];
+	const hydrated = useHydrated();
+	const Comp = route.options.component ?? router.options.defaultComponent;
+	const remountFn = route.options.remountDeps ?? router.options.defaultRemountDeps;
+	const remountDeps = remountFn?.({
+		routeId: props.routeId,
+		loaderDeps: match.loaderDeps,
+		params: match._strictParams,
+		search: match._strictSearch,
+	});
+	const key = remountDeps ? JSON.stringify(remountDeps) : undefined;
+	if (match.status === 'pending' && !props.noSsr && (router as any)._tx) {
+		throw (router as any)._tx[5];
+	}
+	@if ((props.noSsr && !hydrated) || match.status === 'pending') {
+		<CompiledPending route={route} />
+	} @else if (match.status === 'notFound') {
+		<CompiledNotFound route={route} error={match.error} />
+	} @else if (match.status === 'error') {
+		@if (isServer ?? (router as any).isServer) {
+			<CompiledComponent
+				component={
+					route.options.errorComponent ?? router.options.defaultErrorComponent ?? ErrorComponent
+				}
+				props={{ error: match.error, reset: undefined, info: { componentStack: '' } }}
+			/>
+		} @else {
+			throw match.error;
+			<></>
+		}
+	} @else if (Comp) {
+		<CompiledComponent key={key} component={Comp} props={{}} />
+	} @else {
+		<CompiledOutlet />
+	}
+}
+
+// Reads exactly the next TanStack match, preserving nearest-match contexts and
+// fuzzy/root not-found placement. This is distinct from octane's component outlet.
+export function CompiledOutlet() @{
+	const router = useRouter();
+	const routeId = useContext(matchContext)!;
+	const store = router.stores.getMatchStore(routeId);
+	const notFound = useStore(
+		store,
+		(m: any) => ({ global: !!m?._notFound, error: m?.error }),
+		(a, b) => a.global === b.global && a.error === b.error,
+	);
+	const childId = useStore(router.stores.ids, (ids: Array<string>) => {
+		const i = ids.indexOf(routeId);
+		return i >= 0 ? ids[i + 1] : undefined;
+	});
+	@if (notFound.global) {
+		<CompiledNotFound route={(router.routesById as any)[routeId]} error={notFound.error} />
+	} @else if (childId) {
+		@if (routeId === rootRouteId) {
+			@try {
+				<CompiledMatch routeId={childId} />
+			} @pending {
+				<CompiledPending />
+			}
+		} @else {
+			<CompiledMatch routeId={childId} />
+		}
+	}
+}
+
+function CompiledPending(props: { route?: any }) @{
+	const router = useRouter();
+	const Pending = props.route?.options.pendingComponent ?? router.options.defaultPendingComponent;
+	@if (Pending) {
+		<CompiledComponent component={Pending} props={{}} />
+	}
+}
+
+function CompiledNotFound(props: { route: any; error?: NotFoundError }) @{
+	const router = useRouter();
+	const NotFound = props.route.options.notFoundComponent ?? router.options.defaultNotFoundComponent;
+	@if (NotFound) {
+		<CompiledComponent component={NotFound} props={props.error ?? {}} />
+	} @else {
+		<p>Not Found</p>
+	}
+}
+
+function CompiledFailure(props: { error: any; reset: () => void; route: any; global?: boolean }) @{
+	const router = useRouter();
+	const errorComponent = props.global
+		? ErrorComponent
+		: (props.route.options.errorComponent ?? router.options.defaultErrorComponent);
+	const notFoundComponent = props.route.isRoot
+		? (props.route.options.notFoundComponent ?? router.options.notFoundRoute?.options.component)
+		: props.route.options.notFoundComponent;
+	const isMissing = isNotFound(props.error);
+	if (isMissing) {
+		const missing = props.error as NotFoundError;
+		missing.routeId ??= props.route.id;
+		if (!notFoundComponent || missing.routeId !== props.route.id) throw missing;
+	} else if (!errorComponent) {
+		throw props.error;
+	}
+
+	// Report an error only at the boundary that owns it and retry after its
+	// TanStack match identity changes, just like the normal binding.
+	const reported = useRef<unknown>(null);
+	if (!isMissing && !props.global && reported.current !== props.error) {
+		reported.current = props.error;
+		const onCatch = props.route.options.onCatch ?? router.options.defaultOnCatch;
+		onCatch?.(props.error, { componentStack: '' });
+	}
+	const store = router.stores.getMatchStore(props.route.id);
+	const match = useStore(store, (m: any) => m);
+	const firstMatch = useRef(match);
+	useLayoutEffect(() => {
+		if (firstMatch.current !== match) {
+			firstMatch.current = match;
+			props.reset();
+		}
+	}, [match]);
+
+	@if (isMissing) {
+		<CompiledComponent component={notFoundComponent} props={props.error} />
+	} @else {
+		<CompiledComponent
+			component={errorComponent}
+			props={{ error: props.error, reset: props.reset, info: { componentStack: '' } }}
+		/>
+	}
+}
+
+function CompiledScrollRestoration() @{
+	const router = useRouter();
+	const hydrated = useHydrated();
+	const option = router.options.scrollRestoration;
+	const script = getScrollRestorationScriptForRouter(router);
+	const rendersScript = typeof option !== 'function' || option({ location: router.latestLocation });
+	@if ((script !== null || rendersScript) && ((isServer ?? router.isServer) || !hydrated)) {
+		<script
+			nonce={router.options.ssr?.nonce}
+			suppressHydrationWarning
+			dangerouslySetInnerHTML={{ __html: script ?? '' }}
+		/>
+	}
+}
+
+export function lazyCompiledRouteComponent(importer: () => Promise<any>, exportName?: string) {
+	const loader = createLazyRouteLoader(importer, exportName);
+	function Lazy(props: any) @{
+		<CompiledComponent component={loader.read()} props={props} />
+	}
+	Lazy.preload = loader.preload;
+	return Lazy;
+}

package/src/compiled/bindings.ts

@@ -0,0 +1,40 @@
+import { createCompiledContext, useContext } from 'octane';
+import type { AnyRouter, RegisteredRouter } from '@tanstack/router-core';
+import { createRouterHooks } from '../hookBindings';
+import { createUseRouterState } from '../routerStateBinding';
+
+// The normal contexts remain callable providers. These contexts belong only to
+// the opt-in compiled tree so that using it never imports a generic provider.
+export const routerContext = createCompiledContext<AnyRouter | undefined>(undefined);
+export const matchContext = createCompiledContext<string | undefined>(undefined);
+
+export function useRouter<TRouter extends AnyRouter = RegisteredRouter>(opts?: {
+	router?: TRouter;
+	warn?: boolean;
+}): TRouter;
+export function useRouter(...args: unknown[]): AnyRouter {
+	const opts = (args.length && typeof args[0] !== 'symbol' ? args[0] : undefined) as
+		{ router?: AnyRouter; warn?: boolean } | undefined;
+	const router = opts?.router ?? useContext(routerContext);
+	if (!router && opts?.warn !== false) {
+		throw new Error('Use compiled router hooks inside <CompiledRouterProvider>.');
+	}
+	return router as AnyRouter;
+}
+
+export const {
+	useMatch,
+	useParams,
+	useSearch,
+	useLoaderData,
+	useLoaderDeps,
+	useRouteContext,
+	useLocation,
+	useMatches,
+	useParentMatches,
+	useChildMatches,
+	useNavigate,
+	useCanGoBack,
+} = createRouterHooks(useRouter, () => useContext(matchContext));
+
+export const useRouterState = createUseRouterState(useRouter);

package/src/compiled.ts

@@ -0,0 +1,32 @@
+// Opt-in source-owned renderer for code routes with compiled bodies only.
+import './frameworkTypes';
+export * from '@tanstack/router-core';
+export { Router, createRouter } from './router';
+export {
+	createHistory,
+	createBrowserHistory,
+	createHashHistory,
+	createMemoryHistory,
+} from './history';
+export {
+	useRouter,
+	useRouterState,
+	useMatch,
+	useParams,
+	useSearch,
+	useLoaderData,
+	useLoaderDeps,
+	useRouteContext,
+	useLocation,
+	useMatches,
+	useParentMatches,
+	useChildMatches,
+	useNavigate,
+	useCanGoBack,
+} from './compiled/bindings';
+export type { UseRouterStateOptions, UseRouterStateResult } from './routerStateBinding';
+export {
+	CompiledRouterProvider,
+	CompiledOutlet,
+	lazyCompiledRouteComponent,
+} from './compiled/Matches.tsrx';

package/src/fileRoute.ts

@@ -1,4 +1,5 @@
 import { createRoute } from './route';
+import type { Route } from './route';
 import {
 	useLoaderData,
 	useLoaderDeps,
@@ -22,7 +23,6 @@ import type {
 	Register,
 	RegisteredRouter,
 	ResolveParams,
-	Route,
 	RouteById,
 	RouteConstraints,
 	RouteIds,
@@ -268,7 +268,8 @@ export function createLazyRoute<
 
 export function createLazyFileRoute<
 	TFilePath extends keyof FileRoutesByPath,
-	TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],
+	TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'] & AnyRoute =
+		FileRoutesByPath[TFilePath]['preLoaderRoute'],
 >(id: TFilePath): (opts: LazyRouteOptions) => LazyRoute<TRoute> {
 	if (typeof id === 'object') {
 		return new LazyRoute<TRoute>(id) as any;

package/src/frameworkTypes.ts

@@ -30,13 +30,16 @@ declare module '@tanstack/router-core' {
 	}
 
 	interface RouteExtensions<in out TId extends string, in out TFullPath extends string> {
-		useMatch: UseMatchRoute<TId>;
-		useRouteContext: UseRouteContextRoute<TId>;
-		useSearch: UseSearchRoute<TId>;
-		useParams: UseParamsRoute<TId>;
-		useLoaderDeps: UseLoaderDepsRoute<TId>;
-		useLoaderData: UseLoaderDataRoute<TId>;
-		useNavigate: () => UseNavigateResult<TFullPath>;
-		Link: LinkComponentRoute<TFullPath>;
+		// Core base routes are also valid in compiled trees and do not own bound
+		// renderer hooks. The ordinary binding's concrete Route classes provide
+		// each of these members as required properties.
+		useMatch?: UseMatchRoute<TId>;
+		useRouteContext?: UseRouteContextRoute<TId>;
+		useSearch?: UseSearchRoute<TId>;
+		useParams?: UseParamsRoute<TId>;
+		useLoaderDeps?: UseLoaderDepsRoute<TId>;
+		useLoaderData?: UseLoaderDataRoute<TId>;
+		useNavigate?: () => UseNavigateResult<TFullPath>;
+		Link?: LinkComponentRoute<TFullPath>;
 	}
 }