useRouteNodeStore

useRouteNodeStore

Solid.js only. For React/Preact/Vue/Svelte/Angular use useRouteNode.

1. Overview

• Name: useRouteNodeStore
• Purpose: Subscribe to a specific route node with granular, property-level reactivity via Solid's createStore + reconcile
• When to use: When a component should update only when a named route node (and its descendants) is active or inactive, AND needs property-level tracking within that state — combining the node-scope optimization of useRouteNode with the granular reactivity of useRouteStore

2. Signature

function useRouteNodeStore(nodeName: string): RouteState

import { useRouteNodeStore } from "@real-router/solid";

Parameters

Parameter	Type	Required	Description
nodeName	string	Yes	Route node name to scope the subscription to. "" subscribes to all changes (same as useRouteStore).

3. Return value

Returns a Solid store (RouteState) scoped to the named node. The store updates only when the named node transitions between active and inactive, or when its route/previousRoute changes:

interface RouteState {
  route: State | undefined;          // defined only when nodeName is active
  previousRoute: State | undefined;
  navigator: Navigator;
}

4. Comparison with related hooks

	useRoute()	useRouteNode(name)	useRouteStore()	useRouteNodeStore(name)
Returns	Accessor<RouteState>	Accessor<RouteState>	RouteState (store)	RouteState (store)
Read syntax	state()	state()	state.route	state.route
Updates on	every navigation	node active/inactive	every navigation	node active/inactive
Property-level tracking	✗	✗	✅	✅

5. Examples

Layout component for a route subtree

import { useRouteNodeStore } from "@real-router/solid";
import { Show } from "solid-js";

function UsersLayout() {
  // Updates only when "users" or "users.*" routes activate/deactivate
  const state = useRouteNodeStore("users");

  return (
    <Show when={state.route}>
      {(route) => (
        <div>
          {/* Each field tracked independently */}
          <h1>Users — {route().params.section ?? "list"}</h1>
          <p>Previous: {state.previousRoute?.name}</p>
        </div>
      )}
    </Show>
  );
}

Fine-grained param tracking

function UserBreadcrumb() {
  const state = useRouteNodeStore("users");

  // Re-runs only when params.id changes, not on unrelated navigations
  return <span>{state.route?.params.id ?? "—"}</span>;
}

Root node — same as useRouteStore

// nodeName="" → same update frequency as useRouteStore()
const state = useRouteNodeStore("");

6. How it works

useRouteNodeStore wraps createRouteNodeSource(router, nodeName) in createStoreFromSource:

1. createRouteNodeSource is a cached source per (router, nodeName) pair — N components sharing the same node name share one router subscription
2. The source emits only when nodeName's active state changes — navigations that don't affect nodeName are silently dropped by the source's shouldUpdate guard
3. On each emit, createStoreFromSource calls setState(reconcile(source.getSnapshot())) — reconcile updates only changed paths, preserving unchanged object identity for Solid's fine-grained tracking
4. Calls onCleanup(unsubscribe) — the subscription releases when the reactive owner is disposed; if the source has no remaining listeners, it disconnects from the router automatically

7. Notes

• Must be called inside a reactive owner (component body or createRoot)
• state.route is undefined when nodeName is not active — a legitimate business state, not a lifecycle error (contrast: useRoute() throws if no active route)
• Source cache lives in @real-router/sources — auto-evicted on router GC, no local teardown needed
• previousRoute reflects the global previous route, not the node's previous state — see useRouteNode gotcha #8 in CLAUDE.md

See also

• useRouteStore — same granular store pattern, not node-scoped
• useRouteNode — accessor-based node subscription (re-renders on any node change)
• Solid Integration Guide — Store-Based Hooks