Class: TanStackReactRouterBridge

Documentation / @xmachines/play-tanstack-react-router / TanStackReactRouterBridge

Defined in: play-tanstack-react-router/src/tanstack-router-bridge.ts:78

TanStack React Router adapter implementing RouterBridge protocol via RouterBridgeBase

Remarks

Extends RouterBridgeBase to handle all common lifecycle and sync logic. Only 3 TanStack-specific methods are implemented here.

Subscribes to router.history (not router.subscribe(“onBeforeLoad”)) so that back/forward browser navigation (popstate events) are also captured. The router.subscribe(“onBeforeLoad”) approach only works when TanStack’s Transitioner component is mounted (i.e. inside a full ). Since this bridge is used without , we must subscribe to the underlying history object directly — which is exactly what Transitioner does internally: router.history.subscribe(router.load).

Architectural Invariants:

INV-02 (Passive Infrastructure): Router reflects actor state, never decides
Actor validates all navigation via guards before URL changes

Example

const bridge = new TanStackReactRouterBridge(router, actor, routeMap);
bridge.connect();
return () => bridge.disconnect();

Extends

RouterBridgeBase

Constructors

Constructor

new TanStackReactRouterBridge(
   router,
   actor,
   routeMap): TanStackReactRouterBridge;

Defined in: play-tanstack-react-router/src/tanstack-router-bridge.ts:88

Create TanStack React Router bridge

Parameters

Parameter	Type	Description
`router`	`TanStackRouterLike`	TanStack React Router instance
`actor`	`AbstractActor`<`AnyActorLogic`> & `Routable`	XMachines actor instance
`routeMap`	`RouteMap`	Bidirectional mapping between state IDs and paths

Returns

TanStackReactRouterBridge

Overrides

RouterBridgeBase.constructor

Properties

Property	Modifier	Type	Description	Inherited from	Defined in
`actor`	`readonly`	`AbstractActor`<`AnyActorLogic`> & `Routable`	Actor with currentRoute signal and send method	`RouterBridgeBase`.`actor`	play-router/dist/router-bridge-base.d.ts:55
`hasConnectedOnce`	`protected`	`boolean`	-	`RouterBridgeBase`.`hasConnectedOnce`	play-router/dist/router-bridge-base.d.ts:61
`isConnected`	`protected`	`boolean`	-	`RouterBridgeBase`.`isConnected`	play-router/dist/router-bridge-base.d.ts:60
`isProcessingNavigation`	`protected`	`boolean`	-	`RouterBridgeBase`.`isProcessingNavigation`	play-router/dist/router-bridge-base.d.ts:63
`lastSyncedPath`	`protected`	`string`	-	`RouterBridgeBase`.`lastSyncedPath`	play-router/dist/router-bridge-base.d.ts:62
`routeMap`	`readonly`	`object`	Bidirectional route map for stateId ↔ path resolution	`RouterBridgeBase`.`routeMap`	play-router/dist/router-bridge-base.d.ts:56
`routeMap.getPathByStateId`	`public`	`string` \| `null` \| `undefined`	-	-	play-router/dist/router-bridge-base.d.ts:58
`routeMap.getStateIdByPath`	`public`	`string` \| `null` \| `undefined`	-	-	play-router/dist/router-bridge-base.d.ts:57
`routeWatcher`	`protected`	\| `Watcher` \| `null`	-	`RouterBridgeBase`.`routeWatcher`	play-router/dist/router-bridge-base.d.ts:64

Methods

connect()

connect(): void;

Defined in: play-router/dist/router-bridge-base.d.ts:81

Connect the router bridge to the Actor.

Sets up the TC39 Signal watcher for actor → router direction and starts watching router changes (framework-specific).

Returns

void

Inherited from

RouterBridgeBase.connect

disconnect()

disconnect(): void;

Defined in: play-router/dist/router-bridge-base.d.ts:87

Disconnect the router bridge from the Actor.

Stops signal watching and unregisters framework-specific router listener.

Returns

void

Inherited from

RouterBridgeBase.disconnect

extractParams()

protected extractParams(pathname, stateId): Record<string, string>;

Defined in: play-router/dist/router-bridge-base.d.ts:134

Extract path parameters from URL using the URLPattern API.

Accesses globalThis.URLPattern at runtime — no polyfill is imported by this library. If URLPattern is unavailable (Node.js < 24, older browsers without a polyfill), this method returns {} silently (graceful degradation — routing still works, params will be empty).

Parameters

Parameter	Type	Description
`pathname`	`string`	The actual URL path (e.g., ‘/profile/john’)
`stateId`	`string`	The matched state ID for looking up route pattern

Returns

Record<string, string>

Extracted path parameters, or empty object if URLPattern is unavailable or no match

Inherited from

RouterBridgeBase.extractParams

extractQuery()

protected extractQuery(search): Record<string, string>;

Defined in: play-router/dist/router-bridge-base.d.ts:141

Extract query parameters from URL search string.

Parameters

Parameter	Type	Description
`search`	`string`	URL search string (e.g., ‘?tab=security&page=1’)

Returns

Record<string, string>

Extracted query parameters or empty object

Inherited from

RouterBridgeBase.extractQuery

getInitialRouterPath()

protected getInitialRouterPath(): string | null;

Defined in: play-tanstack-react-router/src/tanstack-router-bridge.ts:110

Read the router’s current pathname for initial sync.

Called once in connect() to handle cold-load / deep-link scenarios where the URL differs from the actor’s initial state.

Returns

string | null

Overrides

RouterBridgeBase.getInitialRouterPath

navigateRouter()

protected navigateRouter(path): void;

Defined in: play-tanstack-react-router/src/tanstack-router-bridge.ts:100

Navigate the framework router to the given path.

Called when actor’s currentRoute signal changes to a new path. Must trigger the framework router’s navigation (e.g., router.navigate(path)).

Parameters

Parameter	Type
`path`	`string`

Returns

void

Overrides

RouterBridgeBase.navigateRouter

syncActorFromRouter()

protected syncActorFromRouter(pathname, search?): void;

Defined in: play-router/dist/router-bridge-base.d.ts:101

Sync actor state when router location changes.

Sends play.route event to actor with resolved stateId, params, and query. Prevents circular updates via isProcessingNavigation flag.

Parameters

Parameter	Type
`pathname`	`string`
`search?`	`string`

Returns

void

Inherited from

RouterBridgeBase.syncActorFromRouter

syncRouterFromActor()

protected syncRouterFromActor(route): void;

Defined in: play-router/dist/router-bridge-base.d.ts:94

Sync router location when actor route signal changes.

Calls navigateRouter() for framework-specific navigation. Prevents circular updates via isProcessingNavigation flag.

Parameters

Parameter	Type
`route`	`unknown`

Returns

void

Inherited from

RouterBridgeBase.syncRouterFromActor

unwatchRouterChanges()

protected unwatchRouterChanges(): void;

Defined in: play-tanstack-react-router/src/tanstack-router-bridge.ts:131

Stop watching for router location changes.

Called by disconnect(). Should clean up the framework-specific subscription.

Returns

void

Overrides

RouterBridgeBase.unwatchRouterChanges

watchRouterChanges()

protected watchRouterChanges(): void;

Defined in: play-tanstack-react-router/src/tanstack-router-bridge.ts:123

Subscribe to ALL navigation events via router.history.

router.history.subscribe fires for PUSH, POP, BACK, FORWARD, REPLACE, and GO — covering both link clicks and browser back/forward button presses.

The subscriber callback receives { location, action } where location is the new history location with pathname and search already updated.

Returns

void

Overrides

RouterBridgeBase.watchRouterChanges