Class: TanStackReactRouterBridge

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

Defined in: play-tanstack-router/src/tanstack-router-bridge-base.ts:133

The shared TanStack Router adapter. It implements the RouterBridge protocol through RouterBridgeBase

Remarks

The class extends RouterBridgeBase, and the base class does all the common lifecycle work and synchronization work. This class adds the TanStack navigation methods and subscription methods that the React adapter and the Solid adapter share.

The bridge subscribes to router.history, not to router.subscribe(“onBeforeLoad”). Therefore it also receives a browser BACK or FORWARD navigation, which is a popstate event. The router.subscribe(“onBeforeLoad”) method works only when the Transitioner component of TanStack is mounted, which means inside a complete . This bridge works without . Therefore it subscribes to the history object directly, and this is exactly what Transitioner does internally: router.history.subscribe(router.load).

Architectural invariants:

INV-02 (Passive Infrastructure): the router reflects the actor state. It never decides
The actor checks every navigation with its guards before the URL changes

The class is concrete. You can create an instance of it directly. Each framework package re-exports it, or makes a subclass of it, only to bind the public name of the adapter. The Solid package also adds the dispose() alias.

Example

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

Extends

RouterBridgeBase

Constructors

Constructor

new TanStackReactRouterBridge(
   router,
   actor,
   routeMap,
   options?): TanStackRouterBridgeBase;

Defined in: play-tanstack-router/src/tanstack-router-bridge-base.ts:151

Creates a TanStack Router bridge

Parameters

Parameter	Type	Description
`router`	`TanStackRouterLike`	The TanStack Router instance from `createRouter`
`actor`	`RoutableActor`	The XMachines actor instance
`routeMap`	`TanStackRouteMapLike`	The bidirectional map between the state IDs and the paths
`options?`	`BasePathOptions`	-

Returns

TanStackRouterBridgeBase

Overrides

RouterBridgeBase.constructor

Accessors

basePath

Get Signature

get basePath(): string;

Defined in: play-router/src/router-bridge-base.ts:255

The resolved URL prefix that the machine of this bridge is mounted under, or "" when the machine owns the complete router.

Returns

string

The resolved URL prefix of the mount, or "" when the machine owns the complete router.

Inherited from

RouterBridgeBase.basePath

basePathParams

Get Signature

get basePathParams(): Readonly<Record<string, string>>;

Defined in: play-router/src/router-bridge-base.ts:284

The resolved values of the :param segments of the mount, or {} for a prefix without a param.

These params belong to the HOST: the host wrote the prefix and resolved the values, and they describe the route of the host and not the route of the machine. They therefore travel in NO play.route event. The machine is authoritative over its own params, and event.params holds what the pattern of the machine declares, and nothing else.

They live here instead, because a value that reached the actor on a navigation ALONE would go stale: setBasePath() can move the mount while the machine stays on the same route, no event goes out, and event.params would then contradict basePath. A read of this accessor cannot go stale.

A machine that needs the identity of its host — a machineId, a tenant — takes it through the input of the actor, where it belongs: that identity decides WHICH machine runs, and it is not a param of a route inside the machine.

Example

bridge.basePath; // "/abc123/play"
bridge.basePathParams; // { machineId: "abc123" }

Returns

Readonly<Record<string, string>>

The resolved values of the :param segments of the mount, or {} for a prefix without a param.

These params belong to the HOST, so they travel in NO play.route event — the machine is authoritative over its own params. This accessor is therefore the one way a host reads them back, and it cannot go stale: setBasePath() can move the mount while the machine stays on the same route, and no event goes out.

Inherited from

RouterBridgeBase.basePathParams

Methods

connect()

connect(): void;

Defined in: play-router/src/router-bridge-base.ts:506

Connects the router bridge to the Actor.

The method installs the TC39 Signal watcher of the direction from the actor to the router. It then starts the watch of the router changes, which each framework does in its own way.

The order of these steps is part of the contract of the bridge:

The constructor seeds lastActorRoute from actor.currentRoute, and it records no location
The method installs the actor watcher before the router subscriptions of the adapter
The first synchronization then separates a deep link from a restore, with actor.initialRoute

An adapter that needs a different behavior of the first synchronization overrides getInitialRouterPath(). It does not change the order of the steps of connect().

Returns

void

Inherited from

RouterBridgeBase.connect

disconnect()

disconnect(): void;

Defined in: play-router/src/router-bridge-base.ts:728

Disconnects the router bridge from the Actor.

The method stops the watch of the signal, and it removes the router listener of the framework.

Returns

void

Inherited from

RouterBridgeBase.disconnect

setBasePath()

setBasePath(basePath?, basePathParams?): void;

Defined in: play-router/src/router-bridge-base.ts:324

Moves the machine to a different mount point, while it stays connected.

This is the “load and unload” half of a shared router. It moves WHERE an actor is mounted, and never WHICH actor is mounted: the actor, the route map, and its LRU cache all stay, and nothing goes away.

An actor never changes identity. A prefix that IDENTIFIES the actor — a machineId that names the document it runs — therefore never moves through this method: a new identity is a new actor, and a new actor takes a new bridge, because connect() permits one bridge for each actor. The segments that move here are the ones that LOCATE: a region, a locale, a tenant, a workspace slug.

The call then brings the location in step with the NEW prefix. A location inside the new mount runs the same first-synchronization decision as connect(): it drives the actor, and a restore keeps the route of the actor. A location OUTSIDE the new mount is the old mount in practice, so the bridge writes the new one itself, and it keeps the route of the actor while it does so — nothing else moves the address bar. A call that resolves to the current prefix changes no location, and it therefore reconciles nothing.

Parameters

Parameter	Type	Description
`basePath?`	`string`	The new prefix, as a pattern or as a concrete path. An absent value, `""`, and `"/"` all remove the prefix, and they give the machine the complete router again.
`basePathParams?`	`Record`<`string`, `string` \| `number`>	The values of the `:param` segments of `basePath`.

Returns

void

Throws

For a prefix that resolves to one concrete path never.

Throws

When a :param of the prefix has no value.

Example

// The host moved this actor to another place in its URL space. `machineId` names
// WHICH document the actor runs, and it does not change: a new identity is a new
// actor, and therefore a new bridge, because one actor takes one bridge.
bridge.setBasePath("/:region/:machineId/play", { region: "us", machineId });

Inherited from

RouterBridgeBase.setBasePath