Use a router

Keep the URL and the Model in sync without calling navigate from views.

The router owns the URL. The Model keeps a copy of the parts it needs, such as a filter or a selected id. Values move between the two in two directions, and each direction has one place in the code.

Direction When How
URL to Model The page loads The route's value goes into init
URL to Model The URL changes later useInbound turns the new value into a Message
Model to URL The user clicks a link The router's <Link> changes the URL, which comes back through useInbound
Model to URL update decides to move update returns a Command that calls the router

Views never call navigate directly. Navigation is a side effect, so it belongs in a Command, like a fetch. That keeps update pure, and a test sees the navigation in update's result without a router.

The examples below come from the todo demo, which uses TanStack Router.

Read the URL into the Model

Validate the search with the same Schema the Model uses:

// routes/examples/todo.tsx
export const Route = createFileRoute("/examples/todo")({
	validateSearch: TodoSearch.pipe(Schema.toStandardSchemaV1),
	component: Todo,
})

The route component passes the first value to init. useInbound sends every later change as a Message:

const todoRoute = getRouteApi("/examples/todo")

function SyncFilter({ filter, children }: { readonly filter: Filter; readonly children: React.ReactNode }) {
	useInbound(filter, (next) => Message.ChangedFilter({ filter: next }))
	return children
}

export function Todo() {
	const { filter } = todoRoute.useSearch()

	return (
		<Provider init={() => init({ filter })}>
			<SyncFilter filter={filter}>
				<View />
			</SyncFilter>
		</Provider>
	)
}

useInbound skips the first value, because init already has it. Back and forward buttons work with no extra code, because they change the search too.

update stores the new value like any other Message:

ChangedFilter: ({ filter }) => ({ model: modifyFields(model, { filter: () => filter }) }),

A user click needs no Message of its own. Render the router's <Link>, and the change comes back through useInbound:

<Link to="/examples/todo" search={{ filter: "active" }} />

Change the URL from update

Keep one router instance in its own module, so a Command can reach it. On the server, build a new router for each request instead. Server rendering handles requests at the same time, and a shared router would mix their state:

// router.tsx
let router: AppRouter | undefined

export function getRouter(): AppRouter {
	if (typeof window === "undefined") return createAppRouter()
	router ??= createAppRouter()
	return router
}

Commands run only in the browser, so they always get the shared router.

Define a Command that calls navigate:

const NavigateFilter = Command.define("NavigateFilter", {
	args: { filter: Filter },
	messages: [Message.CompletedNavigateFilter],
	execute: ({ filter }) =>
		Effect.promise(() =>
			getRouter().navigate({
				to: "/examples/todo",
				search: { filter },
				replace: true,
			})
		).pipe(Effect.as(Message.CompletedNavigateFilter())),
})

Then return it from update. Set the Model in the same step, so the view doesn't wait for the URL:

return {
	model: modifyFields(next, { filter: (): Filter => "all" }),
	commands: [NavigateFilter({ filter: "all" })],
}

The new URL then comes back through useInbound as ChangedFilter. The Model already holds that value, so the Message changes nothing.

Allow the router file in the lint rule

The no-navigate-outside-commands rule from the ESLint presets reports navigate calls outside a Command. Files that set up the router are allowed to call it. List them in urlBridgePaths:

// eslint.config.js
export default [
	...recommendedConfig,
	{
		settings: {
			"react-foldkit": {
				urlBridgePaths: ["**/router.tsx", "**/routes/**"],
			},
		},
	},
]

Use another router

The same pattern works with any router that has a navigate function you can call outside a component. Read the URL in the route component, send changes with useInbound, and call navigate from a Command.