TanStack Query在Monorepo架构中的上下文共享问题解析

问题现象

在Monorepo架构中使用TanStack Query（特别是v5版本）时，开发者经常会遇到"Error: No QueryClient set, use QueryClientProvider to set one"的错误提示。这个错误表明React上下文(Context)中的QueryClient实例未被正确识别，导致查询功能无法正常工作。

问题本质

这个问题的根源在于React的上下文机制与模块解析方式的交互。当出现以下情况时，就会导致上下文共享失败：

1. 版本不一致：Monorepo中不同包使用了不同版本的TanStack Query或React
2. 模块重复：打包工具或包管理器(pnpm/yarn/npm)解析出了多个模块实例
3. 上下文隔离：共享库和消费应用处于不同的React上下文树中

技术原理深度解析

TanStack Query的核心机制依赖于React Context来传递QueryClient实例。当组件调用useQuery时，它会尝试从最近的QueryClientProvider中获取client实例。在Monorepo环境中，如果出现以下情况就会导致上下文断裂：

1. peerDependencies处理不当：当共享库将react-query声明为dependency而非peerDependency时，包管理器可能会安装多个版本
2. 包管理器的解析策略：特别是pnpm的严格模式会为不同peerDependency组合创建隔离的模块实例
3. 框架干扰：如Next.js自带React版本，可能与项目声明的React版本冲突

解决方案与实践建议

1. 统一版本管理

确保整个Monorepo中使用完全相同的TanStack Query版本，包括：

• 主应用和所有共享库
• 所有相关插件（如persist-client）
• 配套的React版本

2. 正确的依赖声明

在共享库中，应该将react和react-query声明为peerDependencies：

{
  "peerDependencies": {
    "react": "^18.0.0",
    "@tanstack/react-query": "^5.0.0"
  }
}

3. 上下文共享策略

推荐在共享库中同时导出QueryClientProvider和自定义hooks：

// 在共享库中
export const queryClient = new QueryClient()

export function AppProviders({children}) {
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  )
}

// 在应用入口处
import {AppProviders} from 'shared-library'

function App() {
  return (
    <AppProviders>
      {/* 应用内容 */}
    </AppProviders>
  )
}

4. 显式传递QueryClient

对于深度嵌套的组件，可以显式传递queryClient实例：

const result = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
}, queryClient) // 作为第二个参数传入

高级场景处理

对于复杂的Monorepo结构，建议：

1. 使用工作区协议：在package.json中通过workspace:协议确保版本一致
2. 构建工具配置：配置打包工具(如esbuild/vite)的external选项，避免重复打包
3. 版本检查脚本：添加预构建脚本验证所有包的依赖版本一致性

总结

Monorepo中共享TanStack Query的核心挑战在于维护单一的React上下文环境。通过统一的版本管理、正确的依赖声明和合理的上下文共享策略，可以构建稳定可靠的查询架构。理解React上下文机制与模块解析的交互原理，有助于开发者更好地诊断和解决这类问题。

对于大型项目，建议建立严格的依赖管理规范，并考虑使用更高级的Monorepo工具(如Nx)来简化上下文共享的复杂度。