Principle:Langgenius Dify ShallowRouting
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, Navigation |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
Shallow Routing is the principle of updating the URL without triggering a full page navigation or server-side data refetch, using Next.js shallow routing capabilities exposed through the nuqs library.
Description
In Next.js applications, changing the URL typically triggers the full routing lifecycle, including server-side data fetching, layout re-rendering, and loading state transitions. For UI state changes like updating a filter or switching a tab, this full navigation cycle is unnecessary and creates a jarring user experience with loading indicators and content flashes. The Shallow Routing principle in Dify addresses this by updating the URL in a way that modifies the browser's address bar and history without triggering the Next.js router's data fetching and re-rendering pipeline.
The Dify frontend achieves shallow routing through the nuqs library, which uses the window.history API (pushState and replaceState) to modify the URL without causing a full navigation event. When a user changes a filter or updates a query parameter, nuqs updates the URL and the corresponding React state simultaneously, keeping them in sync without triggering the Next.js router. This means the component tree re-renders based on the state change alone, and the URL updates silently in the background. The nuqs library also supports configurable history modes, allowing developers to choose between push (adds a history entry) and replace (modifies the current entry) based on the semantic significance of the state change.
This principle is important for performance and user experience. Without shallow routing, every query parameter change would trigger a full page transition, including server round trips, loading states, and potential layout shifts. For interactive features like search-as-you-type, real-time filtering, and tab switching, this overhead is unacceptable. Shallow routing enables URL updates at the same frequency as state updates without the performance penalty of full navigation, making the URL a live reflection of the application state.
Usage
Use this principle when:
- Updating URL query parameters in response to user interactions that do not require new data from the server
- Implementing search-as-you-type or real-time filtering features that should be reflected in the URL
- Choosing between push and replace history modes for different types of URL state changes
Theoretical Basis
This principle leverages the History API (pushState and replaceState) introduced in HTML5, which enables URL manipulation without triggering navigation. In the context of Next.js, it works around the framework's assumption that URL changes correspond to route transitions. The principle applies the Optimistic Update pattern, where the UI state is updated immediately based on client-side data while the URL is updated as a side effect. The distinction between push and replace modes follows the Command Pattern with undo semantics, where push operations create reversible history entries and replace operations modify in place.