[Bug]: React 19 Support: Incompatibility with @tanstack/react-query versions

[peterjarian]

Package.json file

{
    "name": "frontend",
    "private": true,
    "scripts": {
        "dev": "next dev --turbopack",
        "build": "next build",
        "start": "next start",
        "lint": "next lint"
    },
    "dependencies": {
        "@medusajs/js-sdk": "^2.8.4",
        "@t3-oss/env-nextjs": "^0.13.8",
        "@tanstack/react-query": "^5.80.10",
        "medusa-react": "^9.0.18",
        "next": "15.3.4",
        "react": "^19.1.0",
        "react-dom": "^19.1.0",
        "zod": "^3.25.67"
    },
    "devDependencies": {
        "@eslint/eslintrc": "^3.3.1",
        "@medusajs/types": "^2.8.4",
        "@tailwindcss/postcss": "^4.1.10",
        "@types/node": "^24.0.3",
        "@types/react": "^19.1.8",
        "@types/react-dom": "^19.1.6",
        "eslint": "^9.29.0",
        "eslint-config-next": "15.3.4",
        "tailwindcss": "^4.1.10",
        "typescript": "^5.8.3"
    }
}

Node.js version

v22.14.0

Database and its version

PostgreSQL latest

Operating system name and version

MacOS Sequoia. 15.3.2

Browser name

Zen Browser

What happended?

When trying to use Medusa with React 19 (released December 5, 2024), I encountered type conflicts between different versions of @tanstack/react-query. The QueryClient from medusa-react is incompatible with React 19's requirements, despite React 19 being out for over 6 months now.

The error occurs specifically when trying to use the MedusaProvider:

Type 'QueryClient' is not assignable to type 'QueryClient'.
  Property '#private' in type 'QueryClient' refers to a different member that cannot be accessed from within type 'QueryClient'.

Environment:

• React: 19.1.0
• react-dom: 19.1.0
• medusa-react: 9.0.18
• @medusajs/js-sdk: 2.8.4
• @tanstack/react-query: 5.80.10

Expected behavior

• medusa-react should support React 19 and its corresponding ecosystem packages
• The QueryClient from medusa-react should be compatible with the latest @tanstack/react-query version
• All Medusa packages (@medusajs/js-sdk, medusa-react, @medusajs/types) should be updated to support React 19's features and types

Actual behavior

• medusa-react is locked to an older version of @tanstack/react-query
• Cannot use React 19 with current Medusa packages without type errors
• Forced to either:
  1. Downgrade to React 18
  2. Use incompatible package versions that might break in production
  3. Create complex workarounds to handle version mismatches

This creates a significant blocker for teams wanting to adopt React 19's improvements while using Medusa as their e-commerce solution.

Link to reproduction repo

https://github.com/peterjarian/medusa-issue