Infinite Loop (React Error 185) with useQueryStates + localStorage Wrapper

[codingwithdidem]

Issue

Getting "Maximum update depth exceeded" (React Error 185) in production and app crashes with client side error message when users navigate to our meetings page perform searches or paginate to another page. The error is extremely difficult to reproduce locally and on production (Only some of the users able to reproduce multiple times a day), suggesting it only occurs under specific race conditions. I'm not sure if its OK to use nuqs with localstorage any help is appreciated

Setup

We created a custom hook that wraps useQueryStates to sync URL params with localStorage for persistent filters:

Custom Hook Structure:

import {
  useQueryStates,
  type Values,
  type UseQueryStatesKeysMap,
  type Parser,
  type UseQueryStatesOptions,
} from 'nuqs';
import { useEffect, useState, useCallback, useRef } from 'react';

/**
 * A custom hook that synchronizes URL query parameters with localStorage.
 * This allows for:
 * 1. Persisting filter states across page refreshes within the same tab
 * 2. Maintaining URL parameters for shareable links
 * 3. Each tab maintains its own independent filter state (no cross-tab sync)
 *
 * @param states - The state configuration object that defines how each parameter should be parsed
 * @param localStorageKey - The key to use for storing the state in localStorage
 * @param options - Additional options for the useQueryStates hook
 */
export const useQueryStatesWithLocalStorage = <T extends UseQueryStatesKeysMap>(
  states: T,
  localStorageKey: string,
  options?: UseQueryStatesOptions<T>,
): [
  Values<T>,
  (value: Partial<Values<T>> | null) => Promise<URLSearchParams>,
] => {
  // Track if we're running on the client side (not SSR)
  const [isClient, setIsClient] = useState(false);

  // Use a ref to prevent circular updates and infinite loops
  const isUpdatingRef = useRef(false);

  // Manual localStorage state management (no automatic cross-tab sync)
  const [localStorageStates, setLocalStorageStates] = useState<{
    data: Values<T>;
  }>({ data: {} as Values<T> });

  // Initialize localStorage state from localStorage on mount
  useEffect(() => {
    if (typeof window !== 'undefined') {
      try {
        const stored = localStorage.getItem(localStorageKey);
        if (stored) {
          const parsed = JSON.parse(stored);
          setLocalStorageStates(parsed);
        }
      } catch (error) {
        console.error('Error reading from localStorage:', error);
      }
      setIsClient(true);
    }
  }, [localStorageKey]);

  // Initialize URL query parameters with values from localStorage if they exist
  // This ensures that the URL reflects the persisted state
  const [queryStates, setQueryStates] = useQueryStates<T>(
    Object.entries(states).reduce((acc, [key, value]) => {
      // Get the value from localStorage if we're on the client side
      const localStorageValue = isClient
        ? localStorageStates?.data?.[key]
        : undefined;
      const parser = value as Parser<unknown> & {
        withDefault: (value: unknown) => Parser<unknown>;
        defaultValue: unknown;
      };
      // Use the localStorage value if it exists, otherwise use the parser's default value
      (acc as Record<string, unknown>)[key] = parser.withDefault(
        localStorageValue ?? parser.defaultValue,
      );
      return acc;
    }, {} as T),
    {
      ...options,
      clearOnDefault: true, // This ensures that default values are not shown in the URL
    },
  );

  // Sync localStorage with URL parameters whenever they change
  useEffect(() => {
    if (!isClient || isUpdatingRef.current) return;

    const currentValue = JSON.stringify(queryStates);
    const currentLocalStorage = JSON.stringify(localStorageStates.data);

    if (currentLocalStorage === currentValue) return;

    isUpdatingRef.current = true;
    const newState = { data: queryStates };
    setLocalStorageStates(newState);

    // Manually update localStorage without triggering cross-tab events
    try {
      localStorage.setItem(localStorageKey, JSON.stringify(newState));
    } catch (error) {
      console.error('Error writing to localStorage:', error);
    }

    isUpdatingRef.current = false;
  }, [queryStates, localStorageStates, localStorageKey, isClient]);

  // Wrap setQueryStates to handle the clear case
  const wrappedSetQueryStates = useCallback(
    async (value: Partial<Values<T>> | null) => {
      if (value === null) {
        isUpdatingRef.current = true;

        const defaultValues = Object.entries(states).reduce(
          (acc, [key, value]) => {
            const parser = value as Parser<unknown> & { defaultValue: unknown };
            (acc as Record<string, unknown>)[key] = parser.defaultValue;
            return acc;
          },
          {} as Values<T>,
        );

        try {
          const newState = { data: defaultValues };
          setLocalStorageStates(newState);
          localStorage.setItem(localStorageKey, JSON.stringify(newState));
          const result = await setQueryStates(defaultValues);
          return result;
        } finally {
          isUpdatingRef.current = false;
        }
      }

      isUpdatingRef.current = true;
      try {
        const newState = { data: value as Values<T> };
        setLocalStorageStates(newState);
        localStorage.setItem(localStorageKey, JSON.stringify(newState));
        const result = await setQueryStates(value);
        return result;
      } finally {
        isUpdatingRef.current = false;
      }
    },
    [setQueryStates, states, localStorageKey],
  );

  return [queryStates, wrappedSetQueryStates];
};

Usage In Another Hook:

import dayjs, { type Dayjs } from 'dayjs';
import utc from 'dayjs/plugin/utc';
import {
  parseAsArrayOf,
  parseAsInteger,
  parseAsIsoDateTime,
  parseAsString,
  parseAsStringEnum,
  useQueryState,
} from 'nuqs';
import { useTransition } from 'react';
import { useQueryStatesWithLocalStorage } from './useQueryStatesWithLocalStorage';

dayjs.extend(utc);

const getDefaultDateFilter = () =>
  [
    dayjs().subtract(1, 'month').startOf('day').toDate(),
    dayjs().endOf('day').toDate(),
  ] as Date[];

export const useMeetingsTableParams = () => {
  const [isPending, startTransition] = useTransition();

  const [page, setPageState] = useQueryState(
    'page',
    parseAsInteger.withDefault(1),
  );

  const [dateFilter, setDateFilterState] = useQueryState(
    'within',
    parseAsArrayOf(parseAsIsoDateTime).withDefault(getDefaultDateFilter()),
  );

  const defaultFilters = {
    search: '',
    searchTarget: 'meetingName' as const,
    participantsFilter: [] as string[],
    meetingTypeFilter: [] as string[],
    companyFilter: [] as string[],
    dealFilter: [] as string[],
    tagFilter: [] as string[],
    sourceFilter: [] as string[],
    statusFilter: [] as string[],
    languageFilter: [] as string[],
    sort: '',
  };

  const [params, setParams] = useQueryStatesWithLocalStorage(
    {
      search: parseAsString.withDefault(defaultFilters.search),
      searchTarget: parseAsStringEnum([
        'meetingName',
        'meetingTranscript',
      ]).withDefault(defaultFilters.searchTarget),
      participantsFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.participantsFilter,
      ),
      meetingTypeFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.meetingTypeFilter,
      ),
      companyFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.companyFilter,
      ),
      dealFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.dealFilter,
      ),
      tagFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.tagFilter,
      ),
      sourceFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.sourceFilter,
      ),
      statusFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.statusFilter,
      ),
      languageFilter: parseAsArrayOf(parseAsString).withDefault(
        defaultFilters.languageFilter,
      ),
      sort: parseAsString.withDefault(defaultFilters.sort),
    },
    'meetingsTableFilters',
    {
      clearOnDefault: true,
      urlKeys: {
        search: 'q',
        searchTarget: 'searchTarget',
        participantsFilter: 'participants',
        meetingTypeFilter: 'meetingType',
        companyFilter: 'companies',
        dealFilter: 'deals',
        tagFilter: 'tags',
        sourceFilter: 'sources',
        statusFilter: 'statuses',
        languageFilter: 'languages',
        sort: 'sort',
      },
    },
  );

  const setDateFilter = (newDateFilter: [Dayjs | null, Dayjs | null]) => {
    if (!newDateFilter[0] || !newDateFilter[1]) {
      setDateFilterState([]); // Clear the filter if either date is null
      return;
    }

    setDateFilterState([
      newDateFilter[0].startOf('day').toDate(),
      newDateFilter[1].endOf('day').toDate(),
    ]);
  };

  const setPage = (newPage: number) => {
    setPageState(newPage);
  };

  const clearFilters = () => {
    setParams(null);
    setDateFilterState(getDefaultDateFilter());
    setPageState(1);
  };

  return {
    isPending,
    params: {
      ...params,
      dateFilter,
      page,
    },
    setParams,
    setDateFilter,
    setPage,
    clearFilters,
  };
};

Finally our searchbar:

import { SearchOutlined } from '@ant-design/icons';
import { useMeetingsTableParams } from '@lib/hooks/useMeetingsTableParams';
import { Dropdown, Input, type MenuProps } from 'antd';
import type { SearchProps } from 'antd/es/input/Search';
import { useTranslations } from 'next-intl';
import { useCallback } from 'react';
import { usePostHog } from 'posthog-js/react';
import useCurrentUser from '@/lib/hooks/tanstack/useCurrentUser';
export default function SearchBar(props: Omit<SearchProps, 'onChange'>) {
  const {
    params: { search },
    setParams,
    setPage,
  } = useMeetingsTableParams();
  const t = useTranslations('meetings');
  const posthog = usePostHog();
  const { currentUser } = useCurrentUser();

  const handleInputChange = useCallback(
    (e: React.ChangeEvent<HTMLInputElement>) => {
      const newValue = e.target.value;

      // Track meeting search input changes
      if (newValue.length > 0) {
        posthog.capture('meeting_search_performed', {
          user_id: currentUser?.id,
          company_id: currentUser?.company?.id,
          search_term: newValue,
          search_term_length: newValue.length,
        });
      }

      setParams({ search: newValue });
      setPage(1);
    },
    [setParams, setPage, posthog, currentUser],
  );

  const items: MenuProps['items'] = [
    {
      key: 'search-in-meeting-name',
      type: 'group',
      label: t('Search.InMeetingName'),
      children: [
        {
          key: 'meetingName',
          label: search,
          onClick: () => {
            setParams({ searchTarget: 'meetingName' });
            setPage(1);
          },
        },
      ],
    },
    {
      key: 'search-in-transcript',
      type: 'group',
      label: t('Search.InTranscript'),
      children: [
        {
          key: 'meetingTranscript',
          label: search,
          onClick: () => {
            setParams({ searchTarget: 'meetingTranscript' });
            setPage(1);
          },
        },
      ],
    },
  ];

  return (
    <Dropdown
      menu={{
        items: search ? items : [],
      }}
      placement="bottom"
    >
      <Input
        value={search}
        className="shadow-none w-[255px]"
        placeholder={t('Search.Placeholder')}
        onChange={handleInputChange}
        prefix={<SearchOutlined className="text-[#D9D9D9]" />}
        data-testid="meeting-search-input"
        {...props}
      />
    </Dropdown>
  );
}

Environment: nuqs 2.4.3, React 19.1.0, Next.js 15.4.7 (App Router)

[franky47]

It's kind of hard to wrap your head around the whole thing, but I think this could be a source of issues:

      isUpdatingRef.current = true;
      try {
        // ...
        const result = await setQueryStates(value);
        return result;
      } finally {
        isUpdatingRef.current = false;
      }

Since the Promise returned by nuqs' state updater functions resolves once the URL has been updated, and this depends on the state of the throttle queue, this could be the source of your hard-to-reproduce race conditions.

If you're only tracking the internal optimistic state update, that one is synchronous.