@tanstack/react-query-devtools v5.0.0 doesn't work out-of-the-box on Next.js

[rtrembecky]

Describe the bug

The server error issue is raised when running yarn dev of Next.js when importing ReactQueryDevtools:

ReferenceError: document is not defined
    at template (file:///Users/my_user/my_project/node_modules/@tanstack/query-devtools/build/esm/index.mjs:809:13)
    at file:///Users/my_user/my_project/node_modules/@tanstack/query-devtools/build/esm/index.mjs:5042:31
    at ModuleJob.run (node:internal/modules/esm/module_job:193:25)
    at async Promise.all (index 0)
    at async ESMLoader.import (node:internal/modules/esm/loader:526:24)
    at async importModuleDynamicallyWrapper (node:internal/vm/module:438:15) {

This is raised because there's no document on the server side. This can be currently worked around by using dynamic import:

import dynamic from 'next/dynamic'

const ReactQueryDevtools = dynamic(
  () => import('@tanstack/react-query-devtools').then(({ReactQueryDevtools}) => ReactQueryDevtools),
  {
    ssr: false,
  },
)

ReactQueryDevtools could be imported in next.js normally and without issue in v4.

Your minimal, reproducible example

Steps to reproduce

in a next.js app:

1. run yarn add @tanstack/[email protected]
2. add import {ReactQueryDevtools} from '@tanstack/react-query-devtools' to _app.tsx
3. add <ReactQueryDevtools /> to the render
4. run yarn dev
5. open the localhost app
6. see the error

Expected behavior

no error

How often does this bug happen?

Every time

Screenshots or Videos

Platform

macOS, Chrome. shouldn't matter

Tanstack Query adapter

react-query

TanStack Query version

5.0.0-alpha.26 for query, 5.0.0-alpha.30 for devtools

TypeScript version

5.0.4

Additional context

No response

[lachlancollins]

Hi @ardeora , I've troubleshooted this a bit.

It seems like the solidjs build adds its own internal library logic at the top of the build output, followed by your package's logic which starts at ~line 5000. The specific document reference which is causing an error is one added by solid rather than your code. You can reproduce this in development in the examples/react/nextjs example which uses the local monorepo build output.

Since I don't get this issue in the svelte adapter, this could probably be fixed at the react adapter level. I'm not sure if there's something as easy as esm-env which works with react/nextjs?

[TkDodo]

I hit that in my live-stream yesterday as well 😅

[lachlancollins]

@ardeora @TkDodo I wonder if this SSR workaround is an unavoidable change that will need to be made for Next.js and other React SSR metaframework users - I can confirm the next/dynamic solution works. The Solid compiler is always going to put server-breaking document and window in, and I don't think there's a built-in React way to disable running on a server ("use client" still hydrates on the server right? The package already uses this anyway)

[ardeora]

Thanks @lachlancollins I think there are two options here.

• One is that we can use SolidJS.lazy https://www.solidjs.com/docs/latest/api#lazy that will lazily load the framework agnostic devtools on mount. This will put all the document and window related code in a separate entry file that will not run on the server.
• Second approach is to implement the we implement the lazy load on the framework adapter level. So just like Svelte Query devtools imports them on the client, we can do the same for React Query devtools. I have a working prototype for it lying around somewhere that I'll try to dig up today/tomorrow

Both approach seems fine I feel the lazy import on the framework agnostic devtools might make it easier to create other framework adapters but I cant think what other side effects it might have. Would love to hear your thoughts on this

[TkDodo]

Yeah option 1 sounds good 👍

[lachlancollins]

@ardeora I agree, building it into the agnostic adapter sounds better 👍

I did try using React.lazy within the react adapter and that didn't work, but solidjs might do things differently!

[lachlancollins]

This is fixed in #5527 🎉 thanks @ardeora ! I think there are some things that throw errors in Next.js but it doesn't crash the app, I'll close this issue and they can be looked into separately.