fix: optimistic state flicker

packages/e2e/next/cypress/e2e/shared/repro-1099.cy.ts

@@ -0,0 +1,25 @@
+import { testRepro1099 } from 'e2e-shared/specs/repro-1099.cy'
+
+testRepro1099({
+  path: '/app/repro-1099/useQueryState',
+  hook: 'useQueryState',
+  nextJsRouter: 'app'
+})
+
+testRepro1099({
+  path: '/app/repro-1099/useQueryStates',
+  hook: 'useQueryStates',
+  nextJsRouter: 'app'
+})
+
+testRepro1099({
+  path: '/pages/repro-1099/useQueryState',
+  hook: 'useQueryState',
+  nextJsRouter: 'pages'
+})
+
+testRepro1099({
+  path: '/pages/repro-1099/useQueryStates',
+  hook: 'useQueryStates',
+  nextJsRouter: 'pages'
+})

packages/e2e/next/next.config.mjs

@@ -5,6 +5,7 @@ const basePath =
 const config = {
   basePath,
   productionBrowserSourceMaps: true,
+  reactStrictMode: false,
   experimental: {
     clientRouterFilter: false,
     ...(process.env.REACT_COMPILER === 'true' ? { reactCompiler: true } : {}),

packages/e2e/next/src/app/app/repro-1099/useQueryState/page.tsx

@@ -0,0 +1,10 @@
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <Suspense>
+      <Repro1099UseQueryState />
+    </Suspense>
+  )
+}

packages/e2e/next/src/app/app/repro-1099/useQueryStates/page.tsx

@@ -0,0 +1,10 @@
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <Suspense>
+      <Repro1099UseQueryStates />
+    </Suspense>
+  )
+}

packages/e2e/next/src/pages/pages/repro-1099/useQueryState.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryState

packages/e2e/next/src/pages/pages/repro-1099/useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryStates

packages/e2e/react-router/v6/cypress/e2e/shared/repro-1099.cy.ts

@@ -0,0 +1,11 @@
+import { testRepro1099 } from 'e2e-shared/specs/repro-1099.cy'
+
+testRepro1099({
+  path: '/repro-1099/useQueryState',
+  hook: 'useQueryState'
+})
+
+testRepro1099({
+  path: '/repro-1099/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/react-router/v6/src/react-router.tsx

@@ -72,9 +72,11 @@ const router = createBrowserRouter(
       <Route path="render-count/:hook/:shallow/:history/:startTransition/async-loader"  lazy={load(import('./routes/render-count.$hook.$shallow.$history.$startTransition.async-loader'))} />
 
       {/* Reproductions */}
-      <Route path="repro-359" lazy={load(import('./routes/repro-359'))} />
-      <Route path="repro-839" lazy={load(import('./routes/repro-839'))} />
-      <Route path="repro-982" lazy={load(import('./routes/repro-982'))} />
+      <Route path="repro-359"                 lazy={load(import('./routes/repro-359'))} />
+      <Route path="repro-839"                 lazy={load(import('./routes/repro-839'))} />
+      <Route path="repro-982"                 lazy={load(import('./routes/repro-982'))} />
+      <Route path="repro-1099/useQueryState"  lazy={load(import('./routes/repro-1099.useQueryState'))} />
+      <Route path="repro-1099/useQueryStates" lazy={load(import('./routes/repro-1099.useQueryStates'))} />
     </Route>
   ))
 

packages/e2e/react-router/v6/src/routes/repro-1099.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryState

packages/e2e/react-router/v6/src/routes/repro-1099.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryStates

packages/e2e/react-router/v7/app/routes.ts

@@ -53,8 +53,10 @@ export default [
     route('/render-count/:hook/:shallow/:history/:startTransition/async-loader', './routes/render-count.$hook.$shallow.$history.$startTransition.async-loader.tsx'),
 
     // Reproductions
-    route('/repro-359', './routes/repro-359.tsx'),
-    route('/repro-839', './routes/repro-839.tsx'),
-    route('/repro-982', './routes/repro-982.tsx'),
+    route('/repro-359',                 './routes/repro-359.tsx'),
+    route('/repro-839',                 './routes/repro-839.tsx'),
+    route('/repro-982',                 './routes/repro-982.tsx'),
+    route('/repro-1099/useQueryState',  './routes/repro-1099.useQueryState.tsx'),
+    route('/repro-1099/useQueryStates', './routes/repro-1099.useQueryStates.tsx'),
   ])
 ] satisfies RouteConfig

packages/e2e/react-router/v7/app/routes/repro-1099.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryState

packages/e2e/react-router/v7/app/routes/repro-1099.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryStates

packages/e2e/react-router/v7/cypress/e2e/shared/repro-1099.cy.ts

@@ -0,0 +1,11 @@
+import { testRepro1099 } from 'e2e-shared/specs/repro-1099.cy'
+
+testRepro1099({
+  path: '/repro-1099/useQueryState',
+  hook: 'useQueryState'
+})
+
+testRepro1099({
+  path: '/repro-1099/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/react/cypress/e2e/shared/repro-1099.cy.ts

@@ -0,0 +1,13 @@
+import { testRepro1099 } from 'e2e-shared/specs/repro-1099.cy'
+
+testRepro1099({
+  path: '/repro-1099/useQueryState',
+  hook: 'useQueryState',
+  shallowOptions: [true]
+})
+
+testRepro1099({
+  path: '/repro-1099/useQueryStates',
+  hook: 'useQueryStates',
+  shallowOptions: [true]
+})

packages/e2e/react/src/routes.tsx

@@ -54,8 +54,10 @@ const routes: Record<string, React.LazyExoticComponent<() => JSX.Element>> = {
   '/render-count/useQueryStates/false/push/true':     lazy(() => import('./routes/render-count')),
 
   // Reproductions
-  '/repro-359': lazy(() => import('./routes/repro-359')),
-  '/repro-982': lazy(() => import('./routes/repro-982')),
+  '/repro-359':                 lazy(() => import('./routes/repro-359')),
+  '/repro-982':                 lazy(() => import('./routes/repro-982')),
+  '/repro-1099/useQueryState':  lazy(() => import('./routes/repro-1099.useQueryState')),
+  '/repro-1099/useQueryStates': lazy(() => import('./routes/repro-1099.useQueryStates')),
 }
 
 export function Router() {

packages/e2e/react/src/routes/repro-1099.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryState

packages/e2e/react/src/routes/repro-1099.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryStates

packages/e2e/remix/app/routes/repro-1099.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryState

packages/e2e/remix/app/routes/repro-1099.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+
+export default Repro1099UseQueryStates

packages/e2e/remix/cypress/e2e/shared/repro-1099.cy.ts

@@ -0,0 +1,11 @@
+import { testRepro1099 } from 'e2e-shared/specs/repro-1099.cy'
+
+testRepro1099({
+  path: '/repro-1099/useQueryState',
+  hook: 'useQueryState'
+})
+
+testRepro1099({
+  path: '/repro-1099/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/shared/components/null-detector.tsx

@@ -4,23 +4,27 @@ type NullDetectorProps = {
   state: ReactNode
   id?: string
   throwOnNull?: boolean
+  enabled?: boolean
 }
 
 export function NullDetector({
   state,
   id = 'null-detector',
-  throwOnNull = false
+  throwOnNull = false,
+  enabled = true
 }: NullDetectorProps) {
-  const [hasBeenNullAtSomePoint, set] = useState(() => state === null)
+  const [hasBeenNullAtSomePoint, set] = useState(() =>
+    enabled ? state === null : false
+  )
   useEffect(() => {
-    if (state !== null) {
+    if (state !== null || !enabled) {
       return
     }
     if (throwOnNull) {
       throw new Error(`Null detected in <NullDetector id="${id}">`)
     }
     console.error(`<NullDetector id="${id}">: NULL DETECTED`)
     set(true)
-  }, [state])
+  }, [enabled, state])
   return <pre id={id}>{hasBeenNullAtSomePoint ? 'fail' : 'pass'}</pre>
 }

packages/e2e/shared/lib/options.ts

@@ -2,13 +2,14 @@ import {
   createLoader,
   createSerializer,
   parseAsBoolean,
-  parseAsStringLiteral
+  parseAsStringLiteral,
+  useQueryStates
 } from 'nuqs'
 
 export const optionsSearchParams = {
   shallow: parseAsBoolean.withDefault(true),
   history: parseAsStringLiteral(['replace', 'push']).withDefault('replace')
 }
-
+export const useOptions = () => useQueryStates(optionsSearchParams)[0]
 export const getOptionsUrl = createSerializer(optionsSearchParams)
 export const loadOptions = createLoader(optionsSearchParams)

packages/e2e/shared/specs/life-and-death.tsx

@@ -36,7 +36,7 @@ function ChildComponentUseQueryState() {
         Clear
       </button>
       <Display environment="client" target="useQueryState" state={test} />
-      <NullDetector throwOnNull id="null-detector-useQueryState" state={test} />
+      <NullDetector id="null-detector-useQueryState" state={test} />
     </>
   )
 }
@@ -63,11 +63,7 @@ function ChildComponentUseQueryStates() {
         Clear
       </button>
       <Display environment="client" target="useQueryStates" state={test} />
-      <NullDetector
-        throwOnNull
-        id="null-detector-useQueryStates"
-        state={test}
-      />
+      <NullDetector id="null-detector-useQueryStates" state={test} />
     </>
   )
 }

packages/e2e/shared/specs/repro-1099.cy.ts

@@ -0,0 +1,33 @@
+import { createTest, type TestConfig } from '../create-test'
+import { getOptionsUrl } from '../lib/options'
+
+type TestRepro1099Options = TestConfig & {
+  shallowOptions?: boolean[]
+  historyOptions?: ('replace' | 'push')[]
+}
+
+export function testRepro1099({
+  shallowOptions = [true, false],
+  historyOptions = ['replace', 'push'],
+  ...options
+}: TestRepro1099Options) {
+  const factory = createTest('repro-1099', ({ path }) => {
+    for (const shallow of shallowOptions) {
+      for (const history of historyOptions) {
+        it(`should not emit null during updates with { shallow: ${shallow}, history: '${history}' }`, () => {
+          cy.visit(getOptionsUrl(path, { history, shallow }), {
+            onBeforeLoad(win) {
+              win.localStorage.setItem('debug', 'nuqs')
+            }
+          })
+          cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
+          cy.get('#null-detector').should('have.text', 'pass')
+          cy.get('button').click()
+          cy.location('search').should('match', /test=pass$/)
+          cy.get('#null-detector').should('have.text', 'pass')
+        })
+      }
+    }
+  })
+  return factory(options)
+}

packages/e2e/shared/specs/repro-1099.tsx

@@ -0,0 +1,68 @@
+'use client'
+
+import { parseAsString, useQueryState, useQueryStates } from 'nuqs'
+import { useEffect, useState } from 'react'
+import { NullDetector } from '../components/null-detector'
+import { useOptions } from '../lib/options'
+
+export function Repro1099UseQueryState() {
+  const { shallow, history } = useOptions()
+  const [state, setState] = useQueryState('test', { shallow, history })
+  const [isNullDetectorEnabled, setIsNullDetectorEnabled] = useState(false)
+  useStateUpdateInEffect(state)
+  return (
+    <>
+      <button
+        onClick={() => {
+          setIsNullDetectorEnabled(true)
+          setState('pass')
+        }}
+      >
+        Test
+      </button>
+      <NullDetector state={state} enabled={isNullDetectorEnabled} />
+    </>
+  )
+}
+
+export function Repro1099UseQueryStates() {
+  const { shallow, history } = useOptions()
+  const [{ state }, setSearchParams] = useQueryStates(
+    {
+      state: parseAsString
+    },
+    {
+      shallow,
+      history,
+      urlKeys: {
+        state: 'test'
+      }
+    }
+  )
+  const [isNullDetectorEnabled, setIsNullDetectorEnabled] = useState(false)
+  useStateUpdateInEffect(state)
+  return (
+    <>
+      <button
+        onClick={() => {
+          setIsNullDetectorEnabled(true)
+          setSearchParams({ state: 'pass' })
+        }}
+      >
+        Test
+      </button>
+      <NullDetector state={state} enabled={isNullDetectorEnabled} />
+    </>
+  )
+}
+
+function useStateUpdateInEffect(trigger: unknown) {
+  const [, setCount] = useState(0)
+  useEffect(() => {
+    if (!trigger) {
+      return
+    }
+    console.log('[repro-1099] trigger other state update')
+    setCount(x => x + 1)
+  }, [trigger])
+}

packages/e2e/tanstack-router/cypress/e2e/shared/repro-1099.cy.ts

@@ -0,0 +1,11 @@
+import { testRepro1099 } from 'e2e-shared/specs/repro-1099.cy'
+
+testRepro1099({
+  path: '/repro-1099/useQueryState',
+  hook: 'useQueryState'
+})
+
+testRepro1099({
+  path: '/repro-1099/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/tanstack-router/src/routes/repro-1099.useQueryState.tsx

@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { Repro1099UseQueryState } from 'e2e-shared/specs/repro-1099'
+
+export const Route = createFileRoute('/repro-1099/useQueryState')({
+  component: Repro1099UseQueryState
+})

packages/e2e/tanstack-router/src/routes/repro-1099.useQueryStates.tsx

@@ -0,0 +1,6 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { Repro1099UseQueryStates } from 'e2e-shared/specs/repro-1099'
+
+export const Route = createFileRoute('/repro-1099/useQueryStates')({
+  component: Repro1099UseQueryStates
+})

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

@@ -64,7 +64,10 @@ export function createReactRouterBasedAdapter({
     const searchParams = useOptimisticSearchParams(watchKeys)
     const updateUrl = useCallback(
       (search: URLSearchParams, options: AdapterOptions) => {
-        startTransition(() => {
+        const maybeTransition = options.shallow
+          ? (callback: () => void) => callback()
+          : startTransition
+        maybeTransition(() => {
           emitter.emit('update', search)
         })
         const url = new URL(location.href)