NuqsTestingAdapter: queued URL updates are flushed before dependent components mount

[iulspop]

Bug Description

When using NuqsTestingAdapter in Storybook stories, queued URL updates set by one component are flushed (cleared) before React mounts sibling/child components that depend on the updated query parameter. This causes the dependent component to initialize with null instead of the queued value.

Reproduction

We have a Storybook story where a state machine transitions from a "triage drawer" to a "fix drawer":

1. The triage drawer is opened via NuqsTestingAdapter's initial searchParams={{ 'triage-finding-id': 'finding-1' }}
2. During the triage flow, the state machine calls setFindingFixFindingId('finding-1') via useQueryState('fix-finding-id')
3. This queues a URL update for fix-finding-id
4. On the next render, NuqsTestingAdapter flushes the update queue (resets it), before the fix drawer component mounts
5. The fix drawer's useQueryState('fix-finding-id') initializes with null instead of 'finding-1'

Current Workaround

Setting resetUrlUpdateQueueOnMount={false} on NuqsTestingAdapter prevents the queue from being cleared, allowing the fix drawer to read the queued value:

<NuqsTestingAdapter
  searchParams={{ 'triage-finding-id': FINDING_ID }}
  resetUrlUpdateQueueOnMount={false}
>
  <Story />
</NuqsTestingAdapter>

However, this prop feels like a band-aid over a timing issue rather than a proper solution.

Better Alternative

We switched to using NuqsAdapter from nuqs/adapters/react-router/v7 (with storybook-addon-remix-react-router providing the React Router context) and setting initial search params via React Router's location.searchParams in the story parameters. This works correctly because nuqs reads/writes through React Router's state, which doesn't have the queue/flush timing issue.

// Decorator
<NuqsAdapter>
  <Story />
</NuqsAdapter>

// Story parameters
parameters: {
  reactRouter: {
    location: {
      searchParams: { 'triage-finding-id': FINDING_ID },
    },
  },
},

Expected Behavior

NuqsTestingAdapter should not flush queued URL updates before all dependent components have had a chance to mount and read the queued values. The queue should be drained in a way that respects React's rendering lifecycle.

Environment

• nuqs: ^2.4.3
• React: 19.1.1
• Storybook: 8.x
• React Router: ^7.12.0

[iulspop]

Additional Finding: NuqsAdapter (react-router/v7) reads from window.location instead of React Router's location

While investigating whether NuqsAdapter from nuqs/adapters/react-router/v7 could replace NuqsTestingAdapter in Storybook (where stories run inside a memory router via storybook-addon-remix-react-router), I discovered a separate issue.

In useOptimisticSearchParams() (chunk-AAU4ZYLC.js), the initial state is derived from window.location.search:

const [searchParams, setSearchParams] = useState(() => {
  if (typeof location === "undefined") {
    return serverSearchParams;
  }
  return new URLSearchParams(location.search);  // ← reads window.location, not React Router's location
});

This means NuqsAdapter ignores search params set in the memory router's initial entries and instead reads from the iframe's actual URL (http://localhost:6006/iframe.html?viewMode=story&id=...), which has no application-level search params.

The useSearchParams() hook from React Router correctly reads from the memory router (confirmed via React fiber inspection — the router context has search: "triage-finding-id=finding-1"), but nuqs bypasses it for the initial state.

This makes NuqsAdapter (react-router/v7) unusable with memory routers in Storybook or tests where window.location doesn't reflect the app's route state.

Workaround

Using NuqsTestingAdapter with searchParams prop and resetUrlUpdateQueueOnMount={false} (the original issue above).

[iulspop]

Update: confirmed the bug is deeper than the queue flush

After more debugging, we found that resetUrlUpdateQueueOnMount={false} does not fully fix the issue. The child component's useQueryState hook never receives the committed value — it stays null permanently, not just on the first render.

Our workaround

We now pass the resolved value from the parent as a prop, bypassing the duplicate useQueryState call entirely:

// Parent already has the value from its own useQueryState
{findingId && <ChildDrawer findingId={findingId} />}

// Child prefers the prop over its own useQueryState
function useChildDrawer({ findingId: findingIdProp }) {
  const { findingId: findingIdFromNuqs } = useMyQueryState()
  const findingId = findingIdProp ?? findingIdFromNuqs
  // ...
}

Minimal reproduction

import { parseAsString, useQueryState } from 'nuqs'
import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
import { useEffect, useState } from 'react'

// Parent reads query param and conditionally renders Child
const Parent = () => {
  const [drawerId, setDrawerId] = useQueryState(
    'drawer-id',
    parseAsString.withOptions({ history: 'push' })
  )

  return (
    <div>
      <button onClick={() => setDrawerId('abc')}>Open drawer</button>
      {drawerId && <Child />}
    </div>
  )
}

// Child reads the SAME query param via its own useQueryState hook
const Child = () => {
  const [drawerId] = useQueryState(
    'drawer-id',
    parseAsString.withOptions({ history: 'push' })
  )

  // BUG: drawerId is null here, even though the parent's
  // drawerId is 'abc' (which is why this component rendered).
  // It never updates — the child is stuck with null permanently.
  return <div>Child sees: {drawerId ?? 'NULL'}</div>
}

// Story / test wrapper
const App = () => (
  <NuqsTestingAdapter resetUrlUpdateQueueOnMount={false}>
    <Parent />
  </NuqsTestingAdapter>
)

Steps:

1. Click "Open drawer" → parent sets drawer-id to 'abc'
2. Parent re-renders, sees drawerId = 'abc', renders <Child />
3. Expected: Child's useQueryState('drawer-id') returns 'abc'
4. Actual: Child's useQueryState('drawer-id') returns null permanently

This happens because the parent and child create separate useQueryState hook instances. The parent's hook has the optimistic/pending value, but the child's newly-mounted hook reads from NuqsTestingAdapter's committed state, which was never updated (or was flushed before the child mounted).

With the real NuqsAdapter backed by an actual URL, this works fine because window.location.search is the shared source of truth. The issue is specific to NuqsTestingAdapter's internal state management.