Hydration Issue with baseUrl in QueryKey

[buffalom]

Issue

After migrating my Next.js app to use the new @hey-api/client-fetch client, the experimental parser and the @tanstack/react-query plugin, I was having issues with my Cypress test. Locally, everything was fine, but in CI some of them kept failing with the following error:

Minified React error #418; visit https://react.dev/errors/418 for the full message or use the non-minified dev environment for full errors and additional helpful warnings.

Details

After debugging for a while, I found the issue in the generated react-query.gen.ts.

This is what it is usually generated as:

react-query.gen.ts (default)

export const someRequestOptions = (options: Options) => {
    return queryOptions({
        queryFn: async ({ queryKey, signal }) => {
            const { data } = await someRequest({
                ...options,
                ...queryKey[0],
                signal,
                throwOnError: true
            });
            return data;
        },
        queryKey: someRequestQueryKey(options)
    });
};

Like this, it was still failing:

react-query.gen.ts (still failing)

export const someRequestOptions = (options: Options) => {
    const baseQueryKey = someRequestQueryKey(options);
    return queryOptions({
        queryFn: async ({ queryKey, signal }) => {
            const { data } = await someRequest({
                ...options,
                ...someRequestQueryKey(options),
                signal,
                throwOnError: true
            });
            return data;
        },
        queryKey: baseQueryKey
    });
};

But when removing the baseUrl from the query key, it did not result in a hydration mismatch anymore:
(Note that I am regenerating the query key for the actual request, so the issue really is in the query key and not in it being passed on to the request)

react-query.gen.ts (this works)

export const someRequestOptions = (options: Options) => {
    const baseQueryKey = someRequestQueryKey(options);
    delete baseQueryKey[0].baseUrl;
    return queryOptions({
        queryFn: async ({ queryKey, signal }) => {
            const { data } = await someRequest({
                ...options,
                ...someRequestQueryKey(options),
                signal,
                throwOnError: true
            });
            return data;
        },
        queryKey: baseQueryKey
    });
};

Solution (not really)

Unfortunately, I was unable to make this issue fully reproducible and still don't exactly know what the issue with the baseUrl in the query key is. That's why I am opening it here as a discussion instead of an issue. Maybe someone has an idea what exactly the issue could be.

For now, I am just removing the baseUrl from the createQueryKey function entirely, as I do not see a need for it in my case. However, perhaps one of you has a better idea and can propose an actual fix.

Thanks, and have a lovely day :)

[mrlubos]

Hey @buffalom, would you be able to print out the offending value (baseUrl)? I suspect in CI it will be somehow undefined. If you could confirm that, it might point us in the right direction

[buffalom]

const createQueryKey = <TOptions extends Options>(id: string, options?: TOptions, infinite?: boolean): QueryKey<TOptions>[0] => {
    console.log({
        baseUrl: (options?.client ?? client).getConfig().baseUrl
    })

I'm not sure it is undefined. At least server-side it seems to be set:

As context:

In CI, I am running the app using GitHub Service Containers. The API is running as a separate service container next to it. This means, for it work I am setting the API url server-side (http://host.docker.internal:5128) differently compared to client-side (http://api.test:5128). Something along this line:

    services:
      api.test:
        image: api-image
        ports:
          - 5128:5128
      app.test:
        image: app-image
        ports:
          - 3000:3000
        options: --add-host=host.docker.internal:host-gateway
        env:
          NEXT_PUBLIC_API_BASE_URL: http://api.test:5128
          API_BASE_URL: http://host.docker.internal:5128

[mrlubos]

I think that might be the problem. Hydration issues occur when there's a mismatch between the server-rendered and the client-rendered content. Are you actually calling the generated client on the server? What happens if you set the generated client to use the same URL on the server?

[buffalom]

That was it! I did not consider the queryKey as content. But actually, it makes a lot of sense that it has to match both on the server and the client. Thanks so much for your help.

[jamesarosen]

I wrote this utility function for this:

import { type DefaultError, type QueryKey, type UseQueryOptions } from '@tanstack/react-query';

const BASE_URL_KEY = 'baseUrl' as const;

/**
 * Removes `baseUrl` from the `queryKey` of the provided query options.
 * This is useful for avoiding hydration mismatches since the Hey API clients in
 * the BFF and the browser have different base URLs.
 *
 * @see https://github.com/orgs/hey-api/discussions/1261
 * @license MIT
 */
export function queryOptionsWithoutBaseUrl<
  TQueryFnData = unknown,
  TError = DefaultError,
  TData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey,
>(
  options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
): UseQueryOptions<TQueryFnData, TError, TData, TQueryKey> {
  return {
    ...options,
    // @ts-expect-error removing `baseUrl` from the queryKey changes the type,
    // but not in a way that should break any contracts
    queryKey: options.queryKey.map((key) => {
      if (typeof key === 'object' && key !== null && BASE_URL_KEY in key) {
        const { [BASE_URL_KEY]: _, ...rest } = key;
        return rest;
      }
      return key;
    }),
  };
}

I tried mapping the TQueryKey type, but couldn't get it to work. If there are any TS wizards out there who want to fix this, I welcome the assist!