Refine 项目从 4.x 升级到 5.x 需要处理哪些破坏性变更并如何用 codemod 自动迁移【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine把 Refine 4.x 项目升到 5.x 不是一个简单的依赖版本号变更。Refine v5 移除了 v4 中标记废弃的 API 和旧系统、把底层缓存库升级为 TanStack Query v5并新增对 React 19 的支持。迁移需要按顺序完成升级依赖、移除废弃 API、重构遗留 router provider、重构遗留 auth provider、升级 TanStack Query 到 v5最后再视情况升级到 React 19。官方文档 4.x 到 5.x 迁移指南 给出了完整步骤配套了refinedev/codemod自动迁移工具本文按文档把整条迁移路径整理出来。升级前的前置检查开始升级前确认项目当前使用的是 Refine 4.x.x。文档明确要求这一点如果你还在用 3.x.x不能直接跳到 5.x需要先按 3.x 到 4.x 的迁移指南 升到 4.x再执行本文的流程。第一步把所有 Refine 依赖升级到 v5Refine 的所有包作为一次协同发布整体升到新的主版本以测试过的完整生态形式提供。各包从 v4 到 v5 的版本对应关系如下摘自迁移指南的官方表格包v4 版本v5 版本refinedev/core4.x.x5.x.xreact17 or 1818 or 19tanstack/react-query4.x.x5.x.xrefinedev/antd5.x.x6.x.xrefinedev/mui6.x.x7.x.xrefinedev/mantine2.x.x3.x.xrefinedev/chakra-ui2.x.x3.x.xrefinedev/react-hook-form4.x.x5.x.xrefinedev/react-table5.x.x6.x.xrefinedev/react-router1.x.x2.x.xrefinedev/nextjs-router6.x.x7.x.xrefinedev/remix-router3.x.x4.x.xrefinedev/inferencer5.x.x6.x.xrefinedev/devtools1.x.x2.x.x文档给出两条更新路径路径 A使用 Refine CLI推荐npm run refine update命令执行完依赖更新后文档特别提醒Refine v5 强制要求 React Query v5确认它已随更新安装npm i tanstack/react-query5路径 B手动安装核心必装项npm i refinedev/core^5.0.0 tanstack/react-query^5.0.0UI 库按项目实际使用的选装# 使用 Ant Design 时 npm i refinedev/antd^6.0.0 # 使用 Material-UI 时 npm i refinedev/mui^7.0.0 # 使用 Mantine 时 npm i refinedev/mantine^3.0.0 # 使用 Chakra UI 时 npm i refinedev/chakra-ui^3.0.0路由包按项目实际使用的选装# React Router npm i refinedev/react-router^2.0.0 # Next.js npm i refinedev/nextjs-router^7.0.0 # Remix npm i refinedev/remix-router^4.0.0表单、表格、数据源等附加包用到哪个升哪个npm i refinedev/react-hook-form^5.0.0 npm i refinedev/react-table^6.0.0 npm i refinedev/simple-rest^5.0.0 npm i refinedev/graphql^6.0.0 npm i refinedev/strapi-v4^5.0.0 npm i refinedev/supabase^5.0.0文档给出的一个完整 Ant Design 项目示例是npm i refinedev/core^5.0.0 refinedev/antd^6.0.0 refinedev/react-router^2.0.0 refinedev/simple-rest^5.0.0 tanstack/react-query^5.0.0第二步运行 codemod 自动迁移v4 中标记废弃的 API 在 v5 中已全部移除。官方推荐用refinedev/codemod包自动处理大部分破坏性变更——它解析项目代码并自动完成转换。运行前需要说明两点命令会直接修改你的源码文件建议先提交工作区改动方便用 diff 审查和回滚必须在项目根目录package.json所在目录下执行。npx refinedev/codemodlatest refine4-to-refine5npx会拉取refinedev/codemod包并执行其中的refine4-to-refine5转换脚本latest表示使用最新发布版本。想看工具支持的全部转换项可以运行npx refinedev/codemod --help。对照仓库中的转换实现 refine4-to-refine5.ts这一条命令实际执行的自动化改写包括从 auth hooks 中移除v3LegacyAuthProviderCompatible: trueuseTable、useForm等 hooks 中的queryResult/mutationResult返回字段改名移除Refine上的useNewQueryKeys配置项ITreeMenu类型改名为TreeMenuItem类型导入RouterBindings→RouterProvider、AuthBindings→AuthProvideruseResource改名为useResourceParamsThemedLayoutV2、ThemedTitleV2、ThemedSiderV2、ThemedHeaderV2等 V2 布局组件去掉 V2 后缀覆盖refinedev/antd、refinedev/mui、refinedev/mantine、refinedev/chakra-uisetCurrent→setCurrentPagepagination.current→pagination.currentPageuseList、useOne、useInfiniteList、useCustom等 hooks 的返回值重构为query/result分组结构mutation hooks 的mutationResult→mutationrefinedev/react-table的useTable返回值更新WelcomePage组件改为从 core 导入。codemod 不覆盖、需要手动处理的部分文档明确列出 codemod 覆盖不到的内容这些要人工修改1. Hook 返回类型中的复杂写法codemod 能处理大多数标准解构但复杂解构、条件逻辑或自定义 wrapper 可能漏掉。如果你用到这些模式需要对照文档逐一检查。返回值重构的核心模式如下——查询状态归入querymutation 状态归入mutation归一化数据归入resultconst { - data, - isLoading, - isError, } useList(); - const posts data.data - const total data.total const { result, query: { isLoading, isError }, } useList(); const posts result.data; const total result.total;useOne、useMany、useShow遵循同样的模式const { - data, - isLoading, - isError, } useOne({ resource: users, id: 1, }); - const user data.data; const { result, query: { isLoading, isError }, } useOne({ resource: users, id: 1, }); const user result;refinedev/react-table的useTable把 TanStack Table 属性收进reactTable对象refinedev/core和refinedev/antd的useTable、refinedev/mui的useDataGrid、refinedev/antd的useSimpleList本身没有破坏性变更但新增了一致的result属性。mutation hooksuseUpdate、useDelete、useCreateMany等的加载状态从isLoading变为mutation下的isPending。2.useNavigation→useGo影响push、replace、goBack导航逻辑- import { useNavigation } from refinedev/core; import { useGo } from refinedev/core; - const { replace, push } useNavigation(); - replace(/tasks/new); const go useGo(); go({ to: /tasks/new, type: replace }); go({ to: /tasks/new, type: push });返回导航改用useBack或使用路由库原生 API- import { useNavigation } from refinedev/core; import { useNavigate } from react-router; - const { goBack } useNavigation(); const navigate useNavigate(); - goBack(); navigate(-1);3.ITreeMenu移除后list字段语义变化影响useMenu和自定义 sider 渲染器。list现在始终是字符串路由list.path不存在了list也不再是函数以前可以在Refine的 resource 里把list定义为 React 组件现在路由和组件必须在 router 中定义- const { menuItems, selectedKey } useMenu(); - menuItems.map((item: ITreeMenu) { - const { key, list } item; - const route - typeof list string - ? list - : typeof list ! function - ? list?.path - : key; - }); const { menuItems, selectedKey } useMenu(); menuItems.map((item: TreeMenuItem) { const { list } item; const route list ?? key; // always a string route now });第三步重构遗留 Router Provider如果项目还在用legacyRouterProvider必须迁移到新路由系统文档建议参考 Router Provider 迁移指南 完成重构。第四步重构遗留 Auth Provider如果项目还在用legacyAuthProvider或在 auth hooks 中带v3LegacyAuthProviderCompatible: true这些在 v5 中被完全移除必须迁移到新的 auth provider 结构useLogin({ - v3LegacyAuthProviderCompatible: true, }); Refine - legacyAuthProvider{legacyAuthProvider} authProvider{authProvider} /完整迁移说明见 Auth Provider 迁移指南核心变化是所有 auth 方法都改为 resolve 并返回带success键的AuthActionResponse对象同时checkAuth→check、getUserIdentity→getIdentity、checkError→onError、useAuthenticated→useIsAuthenticated。注意如果你用 codemod 迁移过它会在 auth hooks 上自动添加v3LegacyAuthProviderCompatible: true以保持向后兼容升级到新 auth provider 时需要把该属性删掉——这一步的说明以 Auth Provider 迁移指南 为准。第五步升级 TanStack Query 到 v5Refine v5 依赖 TanStack Query v5需要把tanstack/react-query从 v4 升到 v5。文档将具体升级说明指向 TanStack Query 官方迁移文档按其指引处理即可。第六步可选升级到 React 19Refine v5 同时支持 React 18 和 React 19升级 React 不是必做步骤想使用 React 19 新特性时再按官方发布说明处理。其余破坏性变更速查迁移指南的 “List of All Breaking Changes” 一节列出了其余参数级变更多数属于重命名可配合 codemod 后的类型报错逐项核对变更影响范围metaData→meta所有数据 hooks、useForm、useTable、useDataGrid、useSelect等sorter/sort→sortersuseList、useInfiniteList、useTable、useDataGrid、useSelectconfig.filters扁平化为顶层filtersinitialFilter/permanentFilter→filters.initial/filters.permanentuseList、useTable、useDataGrid、useSelecthasPagination: false→pagination: { mode: off }initialCurrent/initialPageSize→pagination.currentPage/pageSizeuseList、useTable、useDataGrid、useSelectsetCurrent→setCurrentPageuseTable、useDataGrid、useSimpleListpagination.current→pagination.currentPageuseTable、useDataGrid、useSimpleList、useSubscription、useList等Resource 的options→metaRefine的 Resource 定义resourceName/resourceNameOrRouteName→resourceuseImport、useExport、所有 Button 组件config对象移除参数扁平化useList、useInfiniteListqueryResult→queryuseForm、useSelect、useShow、useSimpleList、useManydefaultValueQueryResult→defaultValueQueryuseSelecttableQueryResult→tableQueryuseTable、useDataGridmutationResult→mutationuseCreate、useUpdate、useDelete等所有 mutation hooksmutation 加载态isLoading→isPending所有 mutation hooksignoreAccessControlProvider→accessControl{{ enabled: false }}带该属性的按钮组件DataProvidergetList参数hasPagination/sort/metaData→pagination.mode/sorters/metacustom方法的sort→sorters自定义 data provider 实现useImport/useExport的mapData、parseConfig、batchSize等改为直接属性导入导出 hooksqueryKeyshelper →keys使用 Refine helper 的自定义实现一个综合示例useList的config对象移除 多处重命名useList({ - config: { - pagination: { currentPage: 1, pageSize: 10 }, - sorters: [{ field: title, order: asc }], - filters: [{ field: status, operator: eq, value: published }], - hasPagination: false, - sort: [{ field: title, order: asc }], - metaData: { foo: bar }, - }, pagination: { currentPage: 1, pageSize: 10, mode: off }, sorters: [{ field: title, order: asc }], filters: [{ field: status, operator: eq, value: published }], meta: { foo: bar }, })迁移完成后的核对清单文档没有给出单一的“升级成功”标志按以下步骤做完后可以按下面的清单核对package.json中所有refinedev/*包与第一步的版本表一致且tanstack/react-query为 5.x项目里搜索不到metaData、queryResult、mutationResult、useNavigation、useResource(、ITreeMenu、ThemedLayoutV2、legacyAuthProvider、v3LegacyAuthProviderCompatible等 v4 旧写法依赖自定义 data provider 的项目getList/custom方法签名已按新参数pagination.mode、sorters、meta改写启动项目跑通各页面重点检查列表、表格、表单、登录与路由跳转——这些都是返回值重构影响最大的区域对照文档中 codemod 不覆盖的几类变更hook 返回类型、useNavigation、ITreeMenu/list字段、router/auth provider逐一确认已手动处理。参考资料4.x 到 5.x 迁移指南官方主文档本文所有步骤与示例均出自该文档3.x 到 4.x 迁移指南仍在使用 3.x 时的前置步骤Auth Provider 迁移指南Router Provider 迁移指南codemod 工具包refine4-to-refine5转换实现见 refine4-to-refine5.ts【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Refine 项目从 4.x 升级到 5.x 需要处理哪些破坏性变更并如何用 codemod 自动迁移？
Refine 项目从 4.x 升级到 5.x 需要处理哪些破坏性变更并如何用 codemod 自动迁移【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine把 Refine 4.x 项目升到 5.x 不是一个简单的依赖版本号变更。Refine v5 移除了 v4 中标记废弃的 API 和旧系统、把底层缓存库升级为 TanStack Query v5并新增对 React 19 的支持。迁移需要按顺序完成升级依赖、移除废弃 API、重构遗留 router provider、重构遗留 auth provider、升级 TanStack Query 到 v5最后再视情况升级到 React 19。官方文档 4.x 到 5.x 迁移指南 给出了完整步骤配套了refinedev/codemod自动迁移工具本文按文档把整条迁移路径整理出来。升级前的前置检查开始升级前确认项目当前使用的是 Refine 4.x.x。文档明确要求这一点如果你还在用 3.x.x不能直接跳到 5.x需要先按 3.x 到 4.x 的迁移指南 升到 4.x再执行本文的流程。第一步把所有 Refine 依赖升级到 v5Refine 的所有包作为一次协同发布整体升到新的主版本以测试过的完整生态形式提供。各包从 v4 到 v5 的版本对应关系如下摘自迁移指南的官方表格包v4 版本v5 版本refinedev/core4.x.x5.x.xreact17 or 1818 or 19tanstack/react-query4.x.x5.x.xrefinedev/antd5.x.x6.x.xrefinedev/mui6.x.x7.x.xrefinedev/mantine2.x.x3.x.xrefinedev/chakra-ui2.x.x3.x.xrefinedev/react-hook-form4.x.x5.x.xrefinedev/react-table5.x.x6.x.xrefinedev/react-router1.x.x2.x.xrefinedev/nextjs-router6.x.x7.x.xrefinedev/remix-router3.x.x4.x.xrefinedev/inferencer5.x.x6.x.xrefinedev/devtools1.x.x2.x.x文档给出两条更新路径路径 A使用 Refine CLI推荐npm run refine update命令执行完依赖更新后文档特别提醒Refine v5 强制要求 React Query v5确认它已随更新安装npm i tanstack/react-query5路径 B手动安装核心必装项npm i refinedev/core^5.0.0 tanstack/react-query^5.0.0UI 库按项目实际使用的选装# 使用 Ant Design 时 npm i refinedev/antd^6.0.0 # 使用 Material-UI 时 npm i refinedev/mui^7.0.0 # 使用 Mantine 时 npm i refinedev/mantine^3.0.0 # 使用 Chakra UI 时 npm i refinedev/chakra-ui^3.0.0路由包按项目实际使用的选装# React Router npm i refinedev/react-router^2.0.0 # Next.js npm i refinedev/nextjs-router^7.0.0 # Remix npm i refinedev/remix-router^4.0.0表单、表格、数据源等附加包用到哪个升哪个npm i refinedev/react-hook-form^5.0.0 npm i refinedev/react-table^6.0.0 npm i refinedev/simple-rest^5.0.0 npm i refinedev/graphql^6.0.0 npm i refinedev/strapi-v4^5.0.0 npm i refinedev/supabase^5.0.0文档给出的一个完整 Ant Design 项目示例是npm i refinedev/core^5.0.0 refinedev/antd^6.0.0 refinedev/react-router^2.0.0 refinedev/simple-rest^5.0.0 tanstack/react-query^5.0.0第二步运行 codemod 自动迁移v4 中标记废弃的 API 在 v5 中已全部移除。官方推荐用refinedev/codemod包自动处理大部分破坏性变更——它解析项目代码并自动完成转换。运行前需要说明两点命令会直接修改你的源码文件建议先提交工作区改动方便用 diff 审查和回滚必须在项目根目录package.json所在目录下执行。npx refinedev/codemodlatest refine4-to-refine5npx会拉取refinedev/codemod包并执行其中的refine4-to-refine5转换脚本latest表示使用最新发布版本。想看工具支持的全部转换项可以运行npx refinedev/codemod --help。对照仓库中的转换实现 refine4-to-refine5.ts这一条命令实际执行的自动化改写包括从 auth hooks 中移除v3LegacyAuthProviderCompatible: trueuseTable、useForm等 hooks 中的queryResult/mutationResult返回字段改名移除Refine上的useNewQueryKeys配置项ITreeMenu类型改名为TreeMenuItem类型导入RouterBindings→RouterProvider、AuthBindings→AuthProvideruseResource改名为useResourceParamsThemedLayoutV2、ThemedTitleV2、ThemedSiderV2、ThemedHeaderV2等 V2 布局组件去掉 V2 后缀覆盖refinedev/antd、refinedev/mui、refinedev/mantine、refinedev/chakra-uisetCurrent→setCurrentPagepagination.current→pagination.currentPageuseList、useOne、useInfiniteList、useCustom等 hooks 的返回值重构为query/result分组结构mutation hooks 的mutationResult→mutationrefinedev/react-table的useTable返回值更新WelcomePage组件改为从 core 导入。codemod 不覆盖、需要手动处理的部分文档明确列出 codemod 覆盖不到的内容这些要人工修改1. Hook 返回类型中的复杂写法codemod 能处理大多数标准解构但复杂解构、条件逻辑或自定义 wrapper 可能漏掉。如果你用到这些模式需要对照文档逐一检查。返回值重构的核心模式如下——查询状态归入querymutation 状态归入mutation归一化数据归入resultconst { - data, - isLoading, - isError, } useList(); - const posts data.data - const total data.total const { result, query: { isLoading, isError }, } useList(); const posts result.data; const total result.total;useOne、useMany、useShow遵循同样的模式const { - data, - isLoading, - isError, } useOne({ resource: users, id: 1, }); - const user data.data; const { result, query: { isLoading, isError }, } useOne({ resource: users, id: 1, }); const user result;refinedev/react-table的useTable把 TanStack Table 属性收进reactTable对象refinedev/core和refinedev/antd的useTable、refinedev/mui的useDataGrid、refinedev/antd的useSimpleList本身没有破坏性变更但新增了一致的result属性。mutation hooksuseUpdate、useDelete、useCreateMany等的加载状态从isLoading变为mutation下的isPending。2.useNavigation→useGo影响push、replace、goBack导航逻辑- import { useNavigation } from refinedev/core; import { useGo } from refinedev/core; - const { replace, push } useNavigation(); - replace(/tasks/new); const go useGo(); go({ to: /tasks/new, type: replace }); go({ to: /tasks/new, type: push });返回导航改用useBack或使用路由库原生 API- import { useNavigation } from refinedev/core; import { useNavigate } from react-router; - const { goBack } useNavigation(); const navigate useNavigate(); - goBack(); navigate(-1);3.ITreeMenu移除后list字段语义变化影响useMenu和自定义 sider 渲染器。list现在始终是字符串路由list.path不存在了list也不再是函数以前可以在Refine的 resource 里把list定义为 React 组件现在路由和组件必须在 router 中定义- const { menuItems, selectedKey } useMenu(); - menuItems.map((item: ITreeMenu) { - const { key, list } item; - const route - typeof list string - ? list - : typeof list ! function - ? list?.path - : key; - }); const { menuItems, selectedKey } useMenu(); menuItems.map((item: TreeMenuItem) { const { list } item; const route list ?? key; // always a string route now });第三步重构遗留 Router Provider如果项目还在用legacyRouterProvider必须迁移到新路由系统文档建议参考 Router Provider 迁移指南 完成重构。第四步重构遗留 Auth Provider如果项目还在用legacyAuthProvider或在 auth hooks 中带v3LegacyAuthProviderCompatible: true这些在 v5 中被完全移除必须迁移到新的 auth provider 结构useLogin({ - v3LegacyAuthProviderCompatible: true, }); Refine - legacyAuthProvider{legacyAuthProvider} authProvider{authProvider} /完整迁移说明见 Auth Provider 迁移指南核心变化是所有 auth 方法都改为 resolve 并返回带success键的AuthActionResponse对象同时checkAuth→check、getUserIdentity→getIdentity、checkError→onError、useAuthenticated→useIsAuthenticated。注意如果你用 codemod 迁移过它会在 auth hooks 上自动添加v3LegacyAuthProviderCompatible: true以保持向后兼容升级到新 auth provider 时需要把该属性删掉——这一步的说明以 Auth Provider 迁移指南 为准。第五步升级 TanStack Query 到 v5Refine v5 依赖 TanStack Query v5需要把tanstack/react-query从 v4 升到 v5。文档将具体升级说明指向 TanStack Query 官方迁移文档按其指引处理即可。第六步可选升级到 React 19Refine v5 同时支持 React 18 和 React 19升级 React 不是必做步骤想使用 React 19 新特性时再按官方发布说明处理。其余破坏性变更速查迁移指南的 “List of All Breaking Changes” 一节列出了其余参数级变更多数属于重命名可配合 codemod 后的类型报错逐项核对变更影响范围metaData→meta所有数据 hooks、useForm、useTable、useDataGrid、useSelect等sorter/sort→sortersuseList、useInfiniteList、useTable、useDataGrid、useSelectconfig.filters扁平化为顶层filtersinitialFilter/permanentFilter→filters.initial/filters.permanentuseList、useTable、useDataGrid、useSelecthasPagination: false→pagination: { mode: off }initialCurrent/initialPageSize→pagination.currentPage/pageSizeuseList、useTable、useDataGrid、useSelectsetCurrent→setCurrentPageuseTable、useDataGrid、useSimpleListpagination.current→pagination.currentPageuseTable、useDataGrid、useSimpleList、useSubscription、useList等Resource 的options→metaRefine的 Resource 定义resourceName/resourceNameOrRouteName→resourceuseImport、useExport、所有 Button 组件config对象移除参数扁平化useList、useInfiniteListqueryResult→queryuseForm、useSelect、useShow、useSimpleList、useManydefaultValueQueryResult→defaultValueQueryuseSelecttableQueryResult→tableQueryuseTable、useDataGridmutationResult→mutationuseCreate、useUpdate、useDelete等所有 mutation hooksmutation 加载态isLoading→isPending所有 mutation hooksignoreAccessControlProvider→accessControl{{ enabled: false }}带该属性的按钮组件DataProvidergetList参数hasPagination/sort/metaData→pagination.mode/sorters/metacustom方法的sort→sorters自定义 data provider 实现useImport/useExport的mapData、parseConfig、batchSize等改为直接属性导入导出 hooksqueryKeyshelper →keys使用 Refine helper 的自定义实现一个综合示例useList的config对象移除 多处重命名useList({ - config: { - pagination: { currentPage: 1, pageSize: 10 }, - sorters: [{ field: title, order: asc }], - filters: [{ field: status, operator: eq, value: published }], - hasPagination: false, - sort: [{ field: title, order: asc }], - metaData: { foo: bar }, - }, pagination: { currentPage: 1, pageSize: 10, mode: off }, sorters: [{ field: title, order: asc }], filters: [{ field: status, operator: eq, value: published }], meta: { foo: bar }, })迁移完成后的核对清单文档没有给出单一的“升级成功”标志按以下步骤做完后可以按下面的清单核对package.json中所有refinedev/*包与第一步的版本表一致且tanstack/react-query为 5.x项目里搜索不到metaData、queryResult、mutationResult、useNavigation、useResource(、ITreeMenu、ThemedLayoutV2、legacyAuthProvider、v3LegacyAuthProviderCompatible等 v4 旧写法依赖自定义 data provider 的项目getList/custom方法签名已按新参数pagination.mode、sorters、meta改写启动项目跑通各页面重点检查列表、表格、表单、登录与路由跳转——这些都是返回值重构影响最大的区域对照文档中 codemod 不覆盖的几类变更hook 返回类型、useNavigation、ITreeMenu/list字段、router/auth provider逐一确认已手动处理。参考资料4.x 到 5.x 迁移指南官方主文档本文所有步骤与示例均出自该文档3.x 到 4.x 迁移指南仍在使用 3.x 时的前置步骤Auth Provider 迁移指南Router Provider 迁移指南codemod 工具包refine4-to-refine5转换实现见 refine4-to-refine5.ts【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考