redux-devtools-inspector-monitor 变更日志深度解读:从 ESM 迁移到 Emotion 化改造的完整演进史
redux-devtools-inspector-monitor 变更日志深度解读:从 ESM 迁移到 Emotion 化改造的完整演进史
@redux-devtools/inspector-monitor 是 Redux DevTools 体系中专注于"状态预览 + 相邻状态差异比对"的监控器组件,它以 diff 为核心,擅长检视真实业务中深层嵌套的复杂状态。本文以仓库内 packages/redux-devtools-inspector-monitor/CHANGELOG.md 为骨架,结合该包源码逐条还原每个版本背后的实现改动,帮你理清它的模块化构建策略(ESM/CJS)、样式体系迁移(JSS → Emotion)、拖拽依赖替换(react-dragula → dnd-kit)以及新引入的配置项,并给出当前版本可实际运行的接入示例。读完本文,你将能依据版本演进理解该监控器的设计取舍,并在自己的 Redux 应用里正确安装、配置与扩展它。
一、版本总览:一条清晰的演进主线
从变更日志可见,该包经历了 0.x → 7.0.0 的持续演进,几条主线贯穿始终:
- 构建与发布形态:从 CommonJS 单输出,到 2.0.0 引入 ESM 构建并切换为命名导出,再到 7.0.0 全面转为 ESM(monorepo 下所有 monitors 统一迁移);
- 样式体系:5.0.0 用 Emotion 替换 JSS,
@emotion/react成为必需的 peer dependency; - 拖拽交互:3.1.0 用 dnd-kit 替换 react-dragula,为 Action 列表的拖拽重排带来更现代的实现;
- 功能迭代:3.1.0 新增状态树按键排序与禁用集合折叠两个选项;后续版本持续放宽 React/Redux peer 依赖范围。
以当前仓库为准,包的最新版本为 7.0.0(见 packages/redux-devtools-inspector-monitor/package.json),"type": "module" 已开启,源码通过 src/index.ts 对外导出 InspectorMonitor 等符号。
二、7.0.0:Monitors 全面转向 ESM
变更要点:
Convert monitors to ESM,并随之更新对@redux-devtools/core@5.0.0的依赖。
在 7.0.0 中,monitors 整体转换为 ESM。这一点在包配置中得到直接印证:
- package.json 中声明
"type": "module"; exports字段仅暴露".": "./lib/index.js"与"./package.json";- 构建产物统一由
tsc生成到lib目录,源码保留在src目录(files字段同时发布两者); - 源码内部所有相对导入均使用带
.js后缀的 ESM 写法,例如 DevtoolsInspector.tsx 中的from './utils/themes.js'、from './ActionList.js'。
这一转换的铺垫其实早在 2.0.0 就已完成。当时为了确保 CommonJS 输出与 ESM 输出"可互换"(interchangeable),默认导出被切换为命名导出,变更日志给出了明确的迁移代码:
- import Inspector from '@redux-devtools/inspector-monitor';
+ import { InspectorMonitor } from '@redux-devtools/inspector-monitor';
而 7.0.0 则是把整条依赖链(monitors 与 @redux-devtools/core)统一推上 ESM 的收官一步。对于使用打包器(webpack、Vite 等)的应用而言,ESM 化意味着更好的 tree-shaking 与更优的静态分析能力;对于直接使用 Node ESM 环境的用户,则消除了 CJS/ESM 互操作带来的坑。
三、5.0.0:样式体系从 JSS 迁移到 Emotion
变更要点:
Replace jss with Emotion in inspector-monitor. @emotion/react is now a required peer dependency.
这是该包历史上最影响开发者安装方式的一次变更。迁移后,组件内部通过 ThemeProvider 提供基于 base16 主题变量的样式上下文,例如 DevtoolsInspector.tsx 顶层渲染:
<ThemeProvider theme={inspectorMonitorTheme}>
<div ... css={(theme) => ({ backgroundColor: theme.BACKGROUND_COLOR, color: theme.TEXT_COLOR, ... })}>
...
</div>
</ThemeProvider>
其中 inspectorMonitorTheme 由 createInspectorMonitorThemeFromBase16Theme(base16Theme, invertTheme) 生成,主题解析与反色逻辑集中在 src/utils/themes.ts(经 resolveBase16Theme 处理)。
由此产生的安装约束是:@emotion/react 成为必需的 peer dependency。当前 package.json 的 peerDependencies 明确列出 "@emotion/react": "^11.14.0",意味着即使你的应用不直接使用 Emotion,也必须安装它才能正常渲染该监控器。仓库自带的 demo 也遵循这一要求,见 demo/package.json 中的 @emotion/react: ^11.14.0。
四、3.1.0:两大交互与展示能力升级
3.1.0 是该包功能层面最重要的一次 minor 版本,包含两项新特性与一项底层替换:
- Option to sort State Tree keys alphabetically(状态树按键字母排序)
- Option to disable collapsing of object keys(禁用对象键折叠/集合截断)
- Replace react-dragula with dnd-kit(拖拽库替换)
4.1 状态树排序与集合折叠开关
两个新开关分别对应 sortStateTreeAlphabetically 与 disableStateTreeCollection,它们的传递终点是 State 标签页。在 src/tabs/StateTab.tsx 中:
<JSONTree
...
sortObjectKeys={sortStateTreeAlphabetically}
{...(disableStateTreeCollection ? { collectionLimit: 0 } : {})}
/>
sortObjectKeys为真时,react-json-tree会按字母序渲染对象键,方便在键名无序的嵌套状态里快速定位;collectionLimit: 0表示不截断集合(数组/对象)的展示,disableStateTreeCollection为真即禁用"折叠大量子项"的默认行为——代价是超大状态树会显著增加渲染成本。
二者同样作为透传 prop 出现在 DevtoolsInspector.tsx 的 ExternalProps 接口与 ActionPreview.tsx 的 TabComponentProps 中,说明任何自定义 Tab 都能拿到这两个开关。
4.2 拖拽库替换:react-dragula → dnd-kit
3.1.0 用 dnd-kit 替换了 react-dragula。当前 package.json 依赖中包含一整套 dnd-kit 生态:
"@dnd-kit/core": "^6.3.1",
"@dnd-kit/modifiers": "^9.0.0",
"@dnd-kit/sortable": "^10.0.0",
"@dnd-kit/utilities": "^3.2.2"
在 src/ActionList.tsx 中,Action 列表通过 DndContext + SortableContext + useSortable 实现拖拽重排:
- 传感器使用
PointerSensor(激活距离 8px 防误触)与KeyboardSensor(配合sortableKeyboardCoordinates支持键盘排序,保证无障碍); - 碰撞检测采用
closestCenter,并应用restrictToFirstScrollableAncestor修饰符把拖拽限制在可滚动容器内; handleDragEnd根据目标位置计算beforeActionId,最终派发reorderAction(actionId, beforeActionId)(对应@redux-devtools/core的ActionCreators.reorderAction)。
同时,仓库根目录的 patches/@dnd-kit__core.patch 与 patches/@dnd-kit__sortable.patch 表明 monorepo 通过 pnpm patch 机制对 dnd-kit 做了针对性修正,这正是"替换 dragula 后仍需精细调校"的直接证据。
五、Peer 依赖范围的持续放宽:React 16.8 → 19
变更日志中还有一条隐线:对 React/Redux 的兼容范围不断扩展。
- 6.0.0:最低 React 版本更新为
16.8.4(对应 Hooks 全面可用的版本基线); - 4.0.0:新增
react-dompeerDependency,并将 react peer 范围定为^16.8.0 || ^17.0.0 || ^18.0.0; - 3.0.0:把 React 18 加入 peerDependencies 范围;
- 6.1.0:把 React 19 加入 peer deps,同时带动
react-json-tree@0.20.0与@redux-devtools/core@4.1.0更新; - 4.1.0:新增新版 Redux 到 peer dependencies,并放宽 peer 依赖(
Widen peer dependencies)。
当前 package.json 的最终形态为:
"peerDependencies": {
"@emotion/react": "^11.14.0",
"@redux-devtools/core": "workspace:^",
"@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
"react": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0",
"react-dom": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0",
"redux": "^3.4.0 || ^4.0.0 || ^5.0.0"
}
即:React 16.8.4 及以上(含 17/18/19)、Redux 3/4/5 均可使用,覆盖面相当广。
六、变更日志之外:Inspector Monitor 的核心能力速览
CHANGELOG 记录的是"变化",而监控器本身的能力基线由 README.md 与源码共同定义,以下内容帮助你把版本演进落到实际使用上。
6.1 工作原理
Inspector 展示一份 Action 列表和一个预览面板:
- 选中某个 action 后,预览面板同时显示该 action 执行后的 state 与与前一 state 的 diff;
- 未选中任何 action 时,展示最后一个 state;
- 支持"固定"(pin)状态的某个局部路径,只追踪该路径下的变化——对应源码中每个对象键旁的
(pin)按钮(见 ActionPreview.tsx 的labelRenderer实现与inspectedStatePath/inspectedActionPath状态)。
diff 计算由 jsondiffpatch 完成(依赖 jsondiffpatch: ^0.7.6)。在 src/createDiffPatcher.ts 中可以看到默认配置:
arrays: { detectMove: false },即默认不检测数组元素移动(3.1.1 更新 jsondiffpatch 也正是为了解决旧版打包问题);- 默认
objectHash优先按id、其次_id、最后$$index:${idx}识别数组元素,保证对象级 diff 的稳定性; - 默认
propertyFilter忽略值为函数(function)的属性。
中间状态的计算集中在 createIntermediateState(DevtoolsInspector.tsx),它依据 selectedActionId/startActionId 定位"from/to"两个状态,再调用 getInspectedState 按路径裁剪并(可选)把 Immutable 数据转为原生 JS 后求 diff。
6.2 面板布局自适应
组件会监听自身宽度,超过 500px 时切换为左右布局(左侧 Action 列表占 40%,右侧预览面板),否则上下堆叠,见 updateSizeMode 与 isWideLayout 状态。
6.3 Action 列表的交互细节
- 搜索过滤:按
action.type做不区分大小写的子串匹配(ActionList.tsx 中filteredActionIds); - 区间选择:
Shift + 点击可选中一段连续 action 区间进行 diff,相关区间状态由startActionId/selectedActionId维护(见handleSelectAction); - 自动滚动:列表靠近底部时新 action 到达会自动滚到底部。
6.4 可配置 Props 一览
| Name | Type | Description |
|---|---|---|
theme |
Object 或 string | base16 主题名或主题对象(可为 base16 颜色映射,或包含 classnames/styles 的对象) |
invertTheme |
Boolean | 反转主题亮度(默认 true,即默认呈现深色主题) |
supportImmutable |
Boolean | 在 Diff 中更好地渲染 Immutable 数据(大对象/大数组下可能影响性能),默认 false |
tabs |
Array 或 function | 覆盖/扩展标签页列表,见下方说明 |
diffObjectHash |
Function | 优化 diff 中数组处理的可选回调(对应 jsondiffpatch 的 objectHash) |
diffPropertyFilter |
Function | 忽略 diff 中特定属性的可选回调(对应 jsondiffpatch 的 propertyFilter) |
draggableActions |
Boolean | 是否允许拖拽重排 Action,默认 true |
sortStateTreeAlphabetically |
Boolean | 状态树键是否按字母排序(3.1.0 新增) |
disableStateTreeCollection |
Boolean | 是否禁用对象键/集合折叠截断(3.1.0 新增) |
hideMainButtons / hideActionButtons |
Boolean | 隐藏主操作按钮/单行操作按钮 |
默认 Props 在 DevtoolsInspector.tsx 的 defaultProps 中:select 恒等返回、supportImmutable: false、draggableActions: true、theme: 'inspector'、invertTheme: true。
6.5 tabs 的扩展机制
tabs 若为函数,接收默认标签列表并返回新列表;若为数组,则只渲染给定标签。默认标签为 Action / Diff / State 三个(见 ActionPreview.tsx 的 DEFAULT_TABS,对应 tabs/ActionTab.tsx、tabs/DiffTab.tsx、tabs/StateTab.tsx)。自定义 Tab 会获得 action、nextState、delta、monitorState、updateMonitorState 等完整上下文(TabComponentProps)。仓库中 redux-devtools-inspector-monitor-test-tab 即是"扩展一个测试用例生成 Tab"的实战范例。
七、接入与配置:当前版本(7.0.0)实操指南
7.1 安装
使用 yarn 安装(npm/pnpm 同理,注意本包为 ESM 且需要配套 peer 依赖):
yarn add @redux-devtools/inspector-monitor @emotion/react
需与 @redux-devtools/core、react、react-dom、redux 的版本范围匹配(React ≥ 16.8.4,Redux 3/4/5,详见上文 peerDependencies)。
7.2 作为唯一监控器使用
// containers/DevTools.tsx
import React from 'react';
import { createDevTools } from '@redux-devtools/core';
import { InspectorMonitor } from '@redux-devtools/inspector-monitor';
export default createDevTools(<InspectorMonitor />);
随后可把 <DevTools /> 渲染到应用任意位置,甚至放进独立弹窗。
7.3 与 DockMonitor 组合成可停靠面板
仓库 demo(demo/src/DevTools.tsx)演示了标准组合方式:
import { createDevTools } from '@redux-devtools/core';
import { DockMonitor } from '@redux-devtools/dock-monitor';
import { InspectorMonitor } from '@redux-devtools/inspector-monitor';
createDevTools(
<DockMonitor
defaultIsVisible
toggleVisibilityKey="ctrl-h"
changePositionKey="ctrl-q"
changeMonitorKey="ctrl-m"
>
<InspectorMonitor
theme="inspector"
invertTheme
supportImmutable={false}
tabs={(defaultTabs) => [
{ name: 'Custom Tab', component: CustomComponent },
...defaultTabs,
]}
/>
</DockMonitor>,
);
其中 tabs 回调演示了"在默认标签前插入自定义标签"的扩展方式。
7.4 按需开启 3.1.0 引入的展示选项
<InspectorMonitor
sortStateTreeAlphabetically // 状态树键按字母排序
disableStateTreeCollection // 不折叠对象键/集合
/>
注意:disableStateTreeCollection 会让超大 state 的渲染成本上升,建议仅在必要时开启。
八、总结
通过这条变更日志可以完整还原 @redux-devtools/inspector-monitor 的演进逻辑:先是 2.0.0 用命名导出统一 ESM/CJS 双构建,再在 5.0.0 以 Emotion 取代 JSS(@emotion/react 成为必装 peer 依赖),3.1.0 引入状态树排序/集合折叠开关并完成拖拽库到 dnd-kit 的迁移,最后在 7.0.0 随 monorepo 全面 ESM 化收官。配合 README.md、package.json 与 src 下各模块源码,无论是追溯旧版本兼容问题,还是在新项目中接入并定制该监控器,都有据可查、可直接落地。
