fix: React Router stale values after remount

packages/e2e/shared/specs/conditional-rendering.cy.ts

@@ -18,5 +18,14 @@ export const testConditionalRendering = createTest(
       cy.get('button#mount').click()
       cy.get('#state').should('have.text', 'pass')
     })
+    it('should keep the correct state after unmounting and remounting with a different state', () => {
+      cy.visit(path + '?test=init')
+      cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
+      cy.get('button#mount').click()
+      cy.get('button#set').click()
+      cy.get('button#unmount').click()
+      cy.get('button#mount').click()
+      cy.get('#state').should('have.text', 'pass')
+    })
   }
 )

packages/nuqs/src/adapters/lib/react-router.ts

@@ -1,10 +1,11 @@
 import mitt from 'mitt'
 import { startTransition, useCallback, useEffect, useState } from 'react'
 import { renderQueryString } from '../../url-encoding'
+import { createAdapterProvider } from './context'
 import type { AdapterInterface, AdapterOptions } from './defs'
 import {
+  patchHistory as applyHistoryPatch,
   historyUpdateMarker,
-  patchHistory,
   type SearchParamsSyncEmitter
 } from './patch-history'
 
@@ -24,11 +25,17 @@ type UseSearchParams = (initial: URLSearchParams) => [URLSearchParams, {}]
 
 // --
 
-export function createReactRouterBasedAdapter(
-  adapter: string,
-  useNavigate: UseNavigate,
+type CreateReactRouterBasedAdapterArgs = {
+  adapter: string
+  useNavigate: UseNavigate
   useSearchParams: UseSearchParams
-) {
+}
+
+export function createReactRouterBasedAdapter({
+  adapter,
+  useNavigate,
+  useSearchParams
+}: CreateReactRouterBasedAdapterArgs) {
   const emitter: SearchParamsSyncEmitter = mitt()
   function useNuqsReactRouterBasedAdapter(): AdapterInterface {
     const navigate = useNavigate()
@@ -78,11 +85,23 @@ export function createReactRouterBasedAdapter(
   }
   function useOptimisticSearchParams() {
     const [serverSearchParams] = useSearchParams(
+      // Note: this will only be taken into account the first time the hook is called,
+      // and cached for subsequent calls, causing problems when mounting components
+      // after shallow updates have occurred.
       typeof location === 'undefined'
         ? new URLSearchParams()
         : new URLSearchParams(location.search)
     )
-    const [searchParams, setSearchParams] = useState(serverSearchParams)
+    const [searchParams, setSearchParams] = useState(() => {
+      if (typeof location === 'undefined') {
+        // We use this on the server to SSR with the correct search params.
+        return serverSearchParams
+      }
+      // Since useSearchParams isn't reactive to shallow changes,
+      // it doesn't pick up changes in the URL on mount, so we need to initialise
+      // the reactive state with the current URL instead.
+      return new URLSearchParams(location.search)
+    })
     useEffect(() => {
       function onPopState() {
         setSearchParams(new URLSearchParams(location.search))
@@ -100,19 +119,18 @@ export function createReactRouterBasedAdapter(
     return searchParams
   }
   /**
-   * Opt-in to syncing shallow updates of the URL with the useOptimisticSearchParams hook.
+   * Sync shallow updates of the URL with the useOptimisticSearchParams hook.
    *
    * By default, the useOptimisticSearchParams hook will only react to internal nuqs updates.
    * If third party code updates the History API directly, use this function to
    * enable useOptimisticSearchParams to react to those changes.
+   *
+   * Note: this is actually required in React Router frameworks to follow Link navigations.
    */
-  function enableHistorySync() {
-    patchHistory(emitter, adapter)
-  }
+  applyHistoryPatch(emitter, adapter)
 
   return {
-    useNuqsReactRouterBasedAdapter,
-    useOptimisticSearchParams,
-    enableHistorySync
+    NuqsAdapter: createAdapterProvider(useNuqsReactRouterBasedAdapter),
+    useOptimisticSearchParams
   }
 }

packages/nuqs/src/adapters/react-router/v6.ts

@@ -1,19 +1,9 @@
 import { useNavigate, useSearchParams } from 'react-router-dom'
-import { createAdapterProvider } from '../lib/context'
 import { createReactRouterBasedAdapter } from '../lib/react-router'
 
-const {
-  enableHistorySync,
-  useNuqsReactRouterBasedAdapter: useNuqsReactRouterV6Adapter,
-  useOptimisticSearchParams
-} = createReactRouterBasedAdapter(
-  'react-router-v6',
-  useNavigate,
-  useSearchParams
-)
-
-export { useOptimisticSearchParams }
-
-export const NuqsAdapter = createAdapterProvider(useNuqsReactRouterV6Adapter)
-
-enableHistorySync()
+export const { NuqsAdapter, useOptimisticSearchParams } =
+  createReactRouterBasedAdapter({
+    adapter: 'react-router-v6',
+    useNavigate,
+    useSearchParams
+  })

packages/nuqs/src/adapters/react-router/v7.ts

@@ -1,19 +1,9 @@
 import { useNavigate, useSearchParams } from 'react-router'
-import { createAdapterProvider } from '../lib/context'
 import { createReactRouterBasedAdapter } from '../lib/react-router'
 
-const {
-  enableHistorySync,
-  useNuqsReactRouterBasedAdapter: useNuqsReactRouterV7Adapter,
-  useOptimisticSearchParams
-} = createReactRouterBasedAdapter(
-  'react-router-v7',
-  useNavigate,
-  useSearchParams
-)
-
-export { useOptimisticSearchParams }
-
-export const NuqsAdapter = createAdapterProvider(useNuqsReactRouterV7Adapter)
-
-enableHistorySync()
+export const { NuqsAdapter, useOptimisticSearchParams } =
+  createReactRouterBasedAdapter({
+    adapter: 'react-router-v7',
+    useNavigate,
+    useSearchParams
+  })

packages/nuqs/src/adapters/remix.ts

@@ -1,15 +1,9 @@
 import { useNavigate, useSearchParams } from '@remix-run/react'
-import { createAdapterProvider } from './lib/context'
 import { createReactRouterBasedAdapter } from './lib/react-router'
 
-const {
-  enableHistorySync,
-  useNuqsReactRouterBasedAdapter: useNuqsRemixAdapter,
-  useOptimisticSearchParams
-} = createReactRouterBasedAdapter('remix', useNavigate, useSearchParams)
-
-export { useOptimisticSearchParams }
-
-export const NuqsAdapter = createAdapterProvider(useNuqsRemixAdapter)
-
-enableHistorySync()
+export const { NuqsAdapter, useOptimisticSearchParams } =
+  createReactRouterBasedAdapter({
+    adapter: 'remix',
+    useNavigate,
+    useSearchParams
+  })