feat(react-query-next-experimental): support Next.js 16 #9868
Conversation
🦋 Changeset detectedLatest commit: 36f351e The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
WalkthroughAdds Next.js 16 support via a changeset and dependency bumps; upgrades an example to Next 16 / React 19, adjusts scripts and TypeScript includes, removes Next ambient type refs, re-enables ESLint during builds for the example, and adds a .gitignore for that example. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Dev as Developer
participant Build as Next Build
participant ESLint as ESLint
participant TS as TypeScript
Dev->>Build: run dev / build (scripts include --webpack)
Build->>ESLint: invoke lint during build (previously ignored)
alt ESLint passes
ESLint-->>Build: OK
Build->>TS: type-check / compile (includes .next/dev types)
TS-->>Build: OK
Build-->>Dev: serve or emit build artifacts
else ESLint fails
ESLint-->>Build: errors
Build-->>Dev: fail build with lint errors
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.changeset/old-plants-beg.md(1 hunks)packages/react-query-next-experimental/package.json(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-02T17:57:33.184Z
Learnt from: TkDodo
Repo: TanStack/query PR: 9612
File: packages/query-async-storage-persister/src/asyncThrottle.ts:0-0
Timestamp: 2025-09-02T17:57:33.184Z
Learning: When importing from tanstack/query-core in other TanStack Query packages like query-async-storage-persister, a workspace dependency "tanstack/query-core": "workspace:*" needs to be added to the package.json.
Applied to files:
packages/react-query-next-experimental/package.json
🔇 Additional comments (2)
packages/react-query-next-experimental/package.json (1)
59-70: Verify React 19.2 compatibility (shipped with Next.js 16).Next.js 16 ships with React 19.2, which introduces new features like
useEffectEvent()and<Activity/>. Ensure that the hydration utilities in react-query-next-experimental are compatible with these new React features and haven't been affected by any React 19.2 internal changes..changeset/old-plants-beg.md (1)
1-5: Changeset format is correct, but dependent on package.json validation.The changeset entry is well-formed and the
minorversion bump is semantically appropriate for adding a new feature (Next.js 16 support). However, this changeset should only be merged after the peer dependency update inpackage.jsonhas been validated against Next.js 16.Merge this changeset only after confirming that
react-query-next-experimentalhas been tested with Next.js 16 and all tests pass.
|
To better confirm the changes, I also updated the Not related to the experimental package, but I created locally a |
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (5)
examples/react/nextjs-suspense-streaming/next-env.d.ts(1 hunks)examples/react/nextjs-suspense-streaming/next.config.js(0 hunks)examples/react/nextjs-suspense-streaming/package.json(1 hunks)examples/react/nextjs-suspense-streaming/tsconfig.json(2 hunks)packages/react-query-next-experimental/package.json(1 hunks)
💤 Files with no reviewable changes (1)
- examples/react/nextjs-suspense-streaming/next.config.js
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-02T17:57:33.184Z
Learnt from: TkDodo
Repo: TanStack/query PR: 9612
File: packages/query-async-storage-persister/src/asyncThrottle.ts:0-0
Timestamp: 2025-09-02T17:57:33.184Z
Learning: When importing from tanstack/query-core in other TanStack Query packages like query-async-storage-persister, a workspace dependency "tanstack/query-core": "workspace:*" needs to be added to the package.json.
Applied to files:
examples/react/nextjs-suspense-streaming/package.jsonpackages/react-query-next-experimental/package.json
🔇 Additional comments (5)
examples/react/nextjs-suspense-streaming/package.json (2)
6-7: Explain why webpack is being forced over Turbopack.The addition of
--webpackflags forces the webpack bundler instead of using Turbopack, which became stable for development in Next.js 15 and for production in Next.js 15.3. This bypasses the modern default bundler.Is this due to a compatibility issue between TanStack Query and Turbopack, or is this intentional for testing purposes? Please clarify the reasoning, as this represents a regression to the legacy bundler.
14-20: Code is already React 19 compatible.The verification confirms that the example does not use any deprecated React 18 APIs. The code uses modern patterns that are compatible with React 19:
- React.Suspense is properly implemented and benefits from React 19 improvements
- Props are typed with TypeScript (not deprecated propTypes)
- No string refs or forwardRef usage
- Client/Server components correctly marked with 'use client'
- No deprecated form APIs (useFormState/useActionState)
The upgrade from React 18 to React 19 is safe for this example.
examples/react/nextjs-suspense-streaming/tsconfig.json (2)
19-19: Correct jsx transform for React 19.The change from
"preserve"to"react-jsx"enables the modern automatic JSX runtime, which is required for React 19. This aligns with the React 19 upgrade guide requirements.
31-32: Appropriate type includes for Next.js 16.Adding
.next/dev/types/**/*.tsensures TypeScript includes Next.js 16's auto-generated development types, enabling features like typed routes.packages/react-query-next-experimental/package.json (1)
62-68: Dev and peer dependencies aligned—manual Next.js 16 verification required.The dependency update addresses the alignment concern: dev is now
^16.0.1and peer includes^16. However, this package has no runtime tests—only type checking and linting. Since the hydration utilities are sensitive to Next.js version differences, manual verification is necessary before merging:
- Test with Next.js 16 locally (especially App Router, streaming, and Suspense behavior)
- Verify hydration in both dev and production builds
- Confirm no breaking changes to the hydration flow
…e autogenerated file
|
View your CI Pipeline Execution ↗ for commit 36f351e
☁️ Nx Cloud last updated this comment at |
There was a problem hiding this comment.
Actionable comments posted: 1
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
examples/react/nextjs-suspense-streaming/tsconfig.json(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-19T03:18:18.303Z
Learnt from: oscartbeaumont
Repo: TanStack/query PR: 9564
File: packages/solid-query-devtools/src/production.tsx:2-3
Timestamp: 2025-08-19T03:18:18.303Z
Learning: In the solid-query-devtools package, the codebase uses a pattern of type-only default imports combined with typeof for component type annotations (e.g., `import type SolidQueryDevtoolsComp from './devtools'` followed by `typeof SolidQueryDevtoolsComp`). This pattern is consistently used across index.tsx and production.tsx files, and the maintainers prefer consistency over changing this approach.
Applied to files:
examples/react/nextjs-suspense-streaming/tsconfig.json
🔇 Additional comments (3)
examples/react/nextjs-suspense-streaming/tsconfig.json (3)
15-15: Verify jsx setting aligns with Next.js 16 best practices.The official @tsconfig/next base and Next.js documentation recommend
"jsx": "preserve", as Next.js implements its own optimized JSX transform. The change to"react-jsx"deviates from the standard Next.js configuration pattern. While"react-jsx"works with React 17+, confirm this is intentional for this example and necessary for Next.js 16 support, or revert to the documented standard of"preserve".
23-29: LGTM: Include paths correctly reference Next.js generated types.The
.next/types/**/*.tsfile is included in tsconfig.json so TypeScript compiler checks routes and provides feedback, and.next/dev/types/**/*.tscontains information about loaded environment variables for editor IntelliSense. These additions are appropriate for modern Next.js projects.
23-29: Include paths are correct for Next.js 16.The addition of ".next/types//*.ts" (the documented recommended pattern) and ".next/dev/types//*.ts" (for the new dev/isolated build behavior in Next.js 16) ensures TypeScript correctly recognizes all generated type definitions. The configuration aligns with Next.js 16 best practices.
…ps://github.com/ValentinGurkov/query into feature/react-query-next-experimental-nextjs-16
…he rest of the repo
|
I saw that the PR tests failed due to the updated streaming example using React 19.2, whereas the rest of the repository uses 19.0, and it messes with the lock file. For now, I've reverted the React version in the example and the tests passed locally. Sorry! |
|
after we merge this, do you want to make a separate PR that bumps everything to 19.2 ? |
|
Sure, I can try and see how it goes |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #9868 +/- ##
=======================================
Coverage 45.78% 45.78%
=======================================
Files 200 200
Lines 8413 8413
Branches 1929 1921 -8
=======================================
Hits 3852 3852
Misses 4113 4113
Partials 448 448 🚀 New features to boost your workflow:
|
3 participants
🎯 Changes
Hello 👋🏻
I’m in the process of migrating my app to Next.js 16, and I noticed that
@tanstack/react-query-next-experimentalwas the only dependency blocking the upgrade. Coming from #9836, I went ahead and bumped the peer dependency version and ran some tests.I haven’t encountered any issues so far, though my app currently uses the query client in only one area. I’d really appreciate it if others interested in this update could also try it out and share their results, so we can be certain that everything is fine and can move forward.
This is my first time opening a PR in any open source repo, so apologies if I don't get something right.
✅ Checklist
pnpm run test:pr.🚀 Release Impact
Summary by CodeRabbit
New Features
Chores
Build / Tooling
Cleanup