Function: deriveRoute()

Documentation / @xmachines/play-xstate / deriveRoute

function deriveRoute(stateMeta): string | null;

Defined in: packages/play-xstate/src/routing/derive-route.ts:90

Derive route from XState state metadata

Extracts route URL template from meta.route in the active state’s metadata. Supports both string routes ("/about") and object routes with path property ({ path: "/about" }). Returns null for states without route metadata (not all states need to be routable).

Architectural Context: Implements Actor Authority (INV-01) by extracting routing information from state machine definitions rather than external configuration. The route is determined by the Actor’s current state, not by infrastructure decisions.

Parameters

Parameter	Type	Description
stateMeta	Record<string, unknown>	State metadata from snapshot.getMeta()

Returns

string | null

Route path template (may include :params) or null if no route found

Examples

Basic route extraction

import { deriveRoute } from "@xmachines/play-xstate";
import { setup } from "xstate";

const machine = setup({}).createMachine({
  states: {
    about: {
      meta: { route: "/about", view: { component: "AboutPage" } },
    },
  },
});

const actor = createActor(machine);
actor.start();
const snapshot = actor.getSnapshot();
const meta = snapshot.getMeta();

const route = deriveRoute(meta);
console.log(route); // "/about"

Route with parameters

const machine = setup({}).createMachine({
  states: {
    profile: {
      meta: {
        route: "/profile/:userId",
        view: { component: "ProfilePage", userId: (ctx) => ctx.userId },
      },
    },
  },
});

const route = deriveRoute(snapshot.getMeta());
console.log(route); // "/profile/:userId" (template, before substitution)

Route object format

const machine = setup({}).createMachine({
  states: {
    dashboard: {
      meta: {
        route: { path: "/dashboard" },
        view: { component: "Dashboard" },
      },
    },
  },
});

const route = deriveRoute(snapshot.getMeta());
console.log(route); // "/dashboard"

See

• RFC Play v1
• buildRouteUrl for URL construction with parameter substitution
• isAbsoluteRoute for checking path absoluteness

Remarks

This function checks meta.route for route definitions. States with route: {} config are routable. Parameter substitution happens via buildRouteUrl, not in this function (deriveRoute returns templates).

Non-routable States: States without meta.route return null. This is intentional— not all states need routes. For example, intermediate loading states or substates may not correspond to distinct URLs.