Persisting query state across navigation

[ha1fstack]

There are similar discussions asking how to preserve query params on page navigation.

This was my solution, hope it might help someone.
idk if it would work on any adapter or environment but it works for me :)
The search cache is stored in-memory in my example. It saves all search queries regardless of actual usage, you might want to add filtering if it isn't what you want.
I guess it could be integrated with the library itself with some modifications and additional context provider, what do you think?

import { useRouter } from 'next/router';
import {
  renderQueryString,
  unstable_createAdapterProvider as createAdapterProvider,
  type unstable_AdapterInterface as AdapterInterface,
} from 'nuqs/adapters/custom';
import { useNuqsNextPagesRouterAdapter } from 'nuqs/dist/_tsup-dts-rollup'; // you should patch the library or copy paste the implementation
import { createContext, MutableRefObject, useContext, useEffect, useInsertionEffect, useRef } from 'react';

export function createNuqsAdapterWithCache() {
  const MountContext = createContext<MutableRefObject<boolean> | null>(null);
  const searchParamsCache = { current: new URLSearchParams() };

  function useNuqsAdapter(): AdapterInterface {
    const { searchParams, updateUrl, rateLimitFactor } = useNuqsNextPagesRouterAdapter(); // refer to internal implementation

    const mountRef = useContext(MountContext)!;

    if (mountRef.current) {
      return { searchParams, updateUrl, rateLimitFactor };
    }

    searchParamsCache.current.forEach((value, key) => {
      searchParams.set(key, value);
    });

    return { searchParams, updateUrl, rateLimitFactor };
  }

  function MountContextProvider({ children }: { children: React.ReactNode }) {
    const mountRef = useRef(false);

    return <MountContext.Provider value={mountRef}>{children}</MountContext.Provider>;
  }

  function UpdateSearchOnMount() {
    const mountRef = useContext(MountContext)!;

    useInsertionEffect(() => {
      if (mountRef.current) {
        return;
      }
      mountRef.current = true;

      const searchParams = new URLSearchParams(window.location.search);
      searchParamsCache.current.forEach((value, key) => {
        searchParams.set(key, value);
      });

      updateSearch(searchParamsCache);
    }, [mountRef]);

    return null;
  }

  function SyncSearchCacheBeforeUnmount() {
    const router = useRouter();

    const searchBeforeUnmount = useRef<string | null>(null);


    useEffect(() => {
      // needs framework-specific implementation
      const handler = () => {
        searchBeforeUnmount.current = window.location.search;
      };
      router.events.on('routeChangeStart', handler);
      return () => {
        router.events.off('routeChangeStart', handler);
      };
    }, [router]);

    useEffect(() => {
      return () => {
        if (searchBeforeUnmount.current == null) {
          return;
        }
        searchParamsCache.current = new URLSearchParams(searchBeforeUnmount.current);
      };
    }, []);

    return null;
  }

  const NuqsAdapterImpl = createAdapterProvider(useNuqsAdapter);
  function NuqsAdapterWithCache({ children, ...props }: React.ComponentProps<typeof NuqsAdapterImpl>) {
    return (
      <MountContextProvider>
        <UpdateSearchOnMount />
        <SyncSearchCacheBeforeUnmount />
        <NuqsAdapterImpl {...props}>{children}</NuqsAdapterImpl>
      </MountContextProvider>
    );
  }

  return NuqsAdapterWithCache;
}

function updateSearch(search: URLSearchParams) {
  const url = new URL(location.href);
  url.search = renderQueryString(search);
  window.history.replaceState(history.state, '', url);
}

usage

const NuqsAdapterWithCache = createNuqsAdapterWithCache();
export default function Page() {
  return <NuqsAdapterWithCache>{/* your app */}</NuqsAdapterWithCache>;
}

The adapter context should be placed for each interests (eg. for each page). You can keep the global adapter if you wish.
It saves the query to cache when the adapter unmounts and reloads from the cache on mount.