Skip to main content

创建 React 18 向 19 升级的行动手册

将官方 React 19 升级指南转化为分阶段的行动手册，并映射到你的代码库。
AuthorCognition
Category迁移
Features高级, 行动手册
1

使用 React 19 升级指南对 Advanced Devin 进行提示

React 19 在 ref 处理、context 使用、TypeScript 类型以及移除遗留 API 等方面引入了破坏性变更。官方升级指南 详细说明了每一项变更，但真正困难的是把这些变更映射到你的代码里。与其自己通读整份指南并审查每个组件，不如把两者都交给 Advanced Devin，然后获取一份只针对你实际代码文件的升级行动手册。在 Devin 首页输入框下方点击 Advanced 按钮打开 Advanced Devin，然后粘贴一个包含升级指南 URL 和你需求的提示：
2

分层加入代码库特定上下文

Advanced Devin 使用 DeepWiki 自动理解你的代码仓库架构。它还可以查找关于 React 19 的在线资料——官方升级指南、博客文章、库的变更日志——并将检索到的内容直接整合进 playbook 中。为了让 playbook 更加精准，可以向 Devin 说明这次迁移会涉及到的模式：
  • “我们在 src/components/ui/ 下的 23 个组件中使用了 forwardRef —— 这些是我们的设计系统基础组件”
  • “我们在 src/legacy/ 中还有 4 个 class 组件使用了字符串 ref 和 componentWillMount”
  • “检查我们组织里的其他代码仓库（例如 acme/design-system、acme/admin-dashboard），看看它们是否已经开始 React 19 迁移——复用它们已经建立的任何模式”
如果有任何依赖本身提供了 React 19 兼容性指南（例如 React Router、React Hook Form，或你的 UI 库），也把这些 URL 粘贴到提示中——Devin 会读取它们，并对照其中列出的所有不兼容变更。
3

查看针对该代码库的专用操作手册

Devin 通读 React 19 升级指南，通过 DeepWiki 将每一项不兼容变更与您的代码库逐一交叉比对，并生成一个分阶段执行方案，包含具体文件、复杂度预估以及验证步骤：
# React 18 → 19 Migration Playbook

## Phase 1: Upgrade to React 18.3 and fix deprecation warnings (S)
- npm install react@18.3 react-dom@18.3
- Run the app and fix all console deprecation warnings:
  - Remove string refs in src/legacy/OldModal.tsx, src/legacy/OldTooltip.tsx
  - Replace ReactDOM.findDOMNode in src/legacy/DropdownMenu.tsx
- Run test suite to confirm no regressions
- Validation: Zero deprecation warnings in dev console, all tests pass

## Phase 2: Migrate forwardRef to ref-as-prop (M)
- Remove forwardRef wrappers from 23 components in src/components/ui/:
  - Button.tsx, Input.tsx, Select.tsx, TextArea.tsx (high usage)
  - Modal.tsx, Popover.tsx, Tooltip.tsx (medium usage)
  - +16 more components (full list below)
- Pass ref as a regular prop instead of wrapping in forwardRef
- Update TypeScript types: change RefObject<T> to RefObject<T> | null
- Update src/types/refs.d.ts to match new React 19 ref semantics
- Validation: All ref-forwarding components render, focus management works

## Phase 3: Remove deprecated APIs (M)
- Replace legacy Context (contextTypes/getChildContext) in:
  - src/legacy/ThemeProvider.tsx → already uses createContext (no change)
  - src/legacy/LocaleContext.tsx → convert to createContext pattern
- Remove propTypes from 12 files (TypeScript handles validation)
- Remove defaultProps from function components (use JS defaults)
- Validation: Context values propagate correctly, no runtime warnings

## Phase 4: Update data fetching and Suspense patterns (L)
- Review Suspense boundaries in src/components/layouts/
- Update any components relying on fallback behavior changes
- Test lazy-loaded routes in src/routes/ with new Suspense semantics
- Validation: All lazy routes load, loading states render correctly

## Phase 5: Install React 19 and adopt new features (M)
- npm install react@19 react-dom@19
- Replace useFormState with useActionState in src/hooks/useFormField.ts
- Update react-dom imports: ReactDOM.render → already using createRoot
- Enable the new JSX transform if not already active
- Validation: Full test suite passes, app runs without errors

## Phase 6: Update third-party libraries (L)
- react-hook-form → upgrade to v8 (React 19 compatible)
- @radix-ui/react-* → upgrade to latest (ref-as-prop support)
- react-router-dom → verify v6.4+ compatibility
- Validation: Forms submit correctly, UI primitives render, routing works

## Risks
- forwardRef removal is highest-volume change — 23 components, many
  consumed by other teams
- TypeScript ref type changes may surface null-safety issues
- react-hook-form v8 has its own breaking changes — test form
  validation thoroughly
该手册是一份迁移方案，而非已执行的迁移。请与团队一起审阅，视需要调整阶段划分或范围，然后再决定具体如何执行。
4

执行与扩展规模

一旦迁移手册确认无误，保存它并将其关联到一个会话中，按阶段依次执行：在多个仓库间扩展 — 如果你有多个需要相同升级的 React 应用，可以使用 Advanced Devin 的批量会话，在所有这些应用上并行运行已保存的迁移手册。