feat: add profile export command for React DevTools Profiler import

kacper-mikolajczak · claude · kacper-mikolajczak · commit a4f339b0ea31 · 2026-03-06T15:24:08.000+01:00
Export profiling data in React DevTools Profiler JSON format (version 5)
so it can be imported into the browser extension's Profiler tab.

- New IPC command: profile-export
- New CLI command: profile export &lt;file&gt;
- Maps internal ProfilingSession to ProfilingDataExport schema
- Includes commit data, fiber durations, change descriptions, snapshots

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/profile-export.md b/.changeset/profile-export.md
@@ -0,0 +1,9 @@
+---
+"agent-react-devtools": minor
+---
+
+Add `profile export <file>` command
+
+- Exports profiling data in React DevTools Profiler JSON format (version 5)
+- Output can be imported into React DevTools via the Profiler tab
+- Includes commit data, fiber durations, change descriptions, and component snapshots
diff --git a/packages/agent-react-devtools/src/__tests__/profiler.test.ts b/packages/agent-react-devtools/src/__tests__/profiler.test.ts
@@ -299,4 +299,175 @@ describe('Profiler', () => {
     expect(timeline[1].duration).toBe(20);
     expect(timeline[1].componentCount).toBe(2);
   });
+
+  describe('getExportData', () => {
+    it('returns null when no session exists', () => {
+      expect(profiler.getExportData(tree)).toBeNull();
+    });
+
+    it('returns null when session has no commits', () => {
+      profiler.start('test');
+      profiler.stop();
+      expect(profiler.getExportData(tree)).toBeNull();
+    });
+
+    it('exports version 5 format', () => {
+      profiler.start('test');
+      profiler.processProfilingData({
+        commitData: [
+          {
+            timestamp: 1000,
+            duration: 15,
+            fiberActualDurations: [1, 10, 2, 3, 3, 2],
+            fiberSelfDurations: [1, 5, 2, 3, 3, 2],
+          },
+        ],
+      });
+      profiler.stop(tree);
+
+      const exported = profiler.getExportData(tree);
+      expect(exported).not.toBeNull();
+      expect(exported!.version).toBe(5);
+      expect(exported!.dataForRoots).toHaveLength(1);
+    });
+
+    it('maps commits to CommitDataExport format', () => {
+      profiler.start('test');
+      profiler.processProfilingData({
+        commitData: [
+          {
+            timestamp: 1000,
+            duration: 15,
+            fiberActualDurations: [1, 10, 2, 3],
+            fiberSelfDurations: [1, 5, 2, 3],
+            changeDescriptions: [
+              [1, { props: ['theme'], isFirstMount: false }],
+              [2, { isFirstMount: true }],
+            ],
+          },
+        ],
+      });
+      profiler.stop(tree);
+
+      const root = profiler.getExportData(tree)!.dataForRoots[0];
+      expect(root.commitData).toHaveLength(1);
+
+      const commit = root.commitData[0];
+      expect(commit.timestamp).toBe(1000);
+      expect(commit.duration).toBe(15);
+      expect(commit.fiberActualDurations).toEqual(expect.arrayContaining([[1, 10], [2, 3]]));
+      expect(commit.fiberSelfDurations).toEqual(expect.arrayContaining([[1, 5], [2, 3]]));
+      expect(commit.effectDuration).toBeNull();
+      expect(commit.passiveEffectDuration).toBeNull();
+      expect(commit.priorityLevel).toBeNull();
+      expect(commit.updaters).toBeNull();
+    });
+
+    it('exports change descriptions with context:null field', () => {
+      profiler.start('test');
+      profiler.processProfilingData({
+        commitData: [
+          {
+            timestamp: 1000,
+            duration: 5,
+            fiberActualDurations: [1, 5],
+            fiberSelfDurations: [1, 5],
+            changeDescriptions: [
+              [1, { props: ['onClick'], state: ['count'], isFirstMount: false, didHooksChange: true }],
+            ],
+          },
+        ],
+      });
+      profiler.stop(tree);
+
+      const commit = profiler.getExportData(tree)!.dataForRoots[0].commitData[0];
+      expect(commit.changeDescriptions).toHaveLength(1);
+      const [id, desc] = commit.changeDescriptions![0];
+      expect(id).toBe(1);
+      expect(desc.context).toBeNull();
+      expect(desc.props).toEqual(['onClick']);
+      expect(desc.state).toEqual(['count']);
+      expect(desc.didHooksChange).toBe(true);
+      expect(desc.isFirstMount).toBe(false);
+    });
+
+    it('builds snapshots from component tree', () => {
+      profiler.start('test');
+      profiler.processProfilingData({
+        commitData: [
+          {
+            timestamp: 1000,
+            duration: 5,
+            fiberActualDurations: [1, 5],
+            fiberSelfDurations: [1, 5],
+          },
+        ],
+      });
+      profiler.stop(tree);
+
+      const root = profiler.getExportData(tree)!.dataForRoots[0];
+      // Should have snapshots for all nodes in the tree
+      expect(root.snapshots.length).toBeGreaterThanOrEqual(3); // App, Header, Content
+
+      // Find the App snapshot
+      const appSnapshot = root.snapshots.find(([id]) => id === 1);
+      expect(appSnapshot).toBeDefined();
+      const [, appNode] = appSnapshot!;
+      expect(appNode.displayName).toBe('App');
+      expect(appNode.type).toBe(5); // ElementType for function
+      expect(appNode.children).toEqual(expect.arrayContaining([2, 3]));
+      expect(appNode.compiledWithForget).toBe(false);
+      expect(appNode.hocDisplayNames).toBeNull();
+    });
+
+    it('populates initialTreeBaseDurations from first commit', () => {
+      profiler.start('test');
+      profiler.processProfilingData({
+        commitData: [
+          {
+            timestamp: 1000,
+            duration: 15,
+            fiberActualDurations: [1, 10, 2, 3],
+            fiberSelfDurations: [1, 5, 2, 3],
+          },
+          {
+            timestamp: 2000,
+            duration: 8,
+            fiberActualDurations: [1, 6],
+            fiberSelfDurations: [1, 4],
+          },
+        ],
+      });
+      profiler.stop(tree);
+
+      const root = profiler.getExportData(tree)!.dataForRoots[0];
+      // Should use first commit's self durations
+      expect(root.initialTreeBaseDurations).toEqual(expect.arrayContaining([[1, 5], [2, 3]]));
+    });
+
+    it('produces JSON that can be serialized and parsed', () => {
+      profiler.start('test');
+      profiler.processProfilingData({
+        commitData: [
+          {
+            timestamp: 1000,
+            duration: 15,
+            fiberActualDurations: [1, 10, 2, 3, 3, 2],
+            fiberSelfDurations: [1, 5, 2, 3, 3, 2],
+            changeDescriptions: [
+              [1, { props: ['x'], isFirstMount: false }],
+            ],
+          },
+        ],
+      });
+      profiler.stop(tree);
+
+      const exported = profiler.getExportData(tree)!;
+      const json = JSON.stringify(exported);
+      const parsed = JSON.parse(json);
+      expect(parsed.version).toBe(5);
+      expect(parsed.dataForRoots).toHaveLength(1);
+      expect(parsed.dataForRoots[0].commitData).toHaveLength(1);
+    });
+  });
 });
diff --git a/packages/agent-react-devtools/src/cli.ts b/packages/agent-react-devtools/src/cli.ts
@@ -18,6 +18,8 @@ import {
   formatTimeline,
   formatCommitDetail,
 } from './formatters.js';
+import { writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import type { IpcCommand } from './types.js';
 
 function usage(): string {
@@ -48,7 +50,8 @@ Profiling:
   profile slow [--limit N]      Slowest components (by avg)
   profile rerenders [--limit N] Most re-rendered components
   profile timeline [--limit N]  Commit timeline
-  profile commit <N | #N> [--limit N]  Detail for specific commit`;
+  profile commit <N | #N> [--limit N]  Detail for specific commit
+  profile export <file>               Export as React DevTools JSON`;
 }
 
 function parseArgs(argv: string[]): {
@@ -364,6 +367,24 @@ async function main(): Promise<void> {
       return;
     }
 
+    if (cmd0 === 'profile' && cmd1 === 'export') {
+      const file = command[2];
+      if (!file) {
+        console.error('Usage: devtools profile export <file>');
+        process.exit(1);
+      }
+      const resp = await sendCommand({ type: 'profile-export' });
+      if (resp.ok) {
+        const outPath = resolve(file);
+        writeFileSync(outPath, JSON.stringify(resp.data), 'utf-8');
+        console.log(`Exported to ${outPath}`);
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+
     console.error(`Unknown command: ${command.join(' ')}`);
     console.log(usage());
     process.exit(1);
diff --git a/packages/agent-react-devtools/src/daemon.ts b/packages/agent-react-devtools/src/daemon.ts
@@ -255,6 +255,14 @@ class Daemon {
           return { ok: true, data: detail };
         }
 
+        case 'profile-export': {
+          const exportData = this.profiler.getExportData(this.tree);
+          if (!exportData) {
+            return { ok: false, error: 'No profiling data to export (run profile start/stop first)' };
+          }
+          return { ok: true, data: exportData };
+        }
+
         case 'wait':
           return this.handleWait(cmd, conn);
 
diff --git a/packages/agent-react-devtools/src/profiler.ts b/packages/agent-react-devtools/src/profiler.ts
@@ -5,6 +5,11 @@ import type {
   ComponentRenderReport,
   RenderCause,
   ChangedKeys,
+  ComponentType,
+  ProfilingDataExport,
+  ProfilingDataForRootExport,
+  CommitDataExport,
+  SnapshotNodeExport,
 } from './types.js';
 import type { ComponentTree } from './component-tree.js';
 
@@ -317,6 +322,106 @@ export class Profiler {
     return entries;
   }
 
+  /**
+   * Export profiling data in React DevTools Profiler format (version 5).
+   * The output can be imported into React DevTools via the Profiler tab.
+   */
+  getExportData(tree: ComponentTree): ProfilingDataExport | null {
+    if (!this.session || this.session.commits.length === 0) return null;
+
+    // Group commits by root ID (most apps have one root)
+    const rootIds = tree.getRootIds();
+    if (rootIds.length === 0) {
+      // Fallback: use a synthetic root
+      rootIds.push(1);
+    }
+
+    const dataForRoots: ProfilingDataForRootExport[] = [];
+
+    for (const rootId of rootIds) {
+      const rootNode = tree.getNode(rootId);
+
+      // Build snapshots from current tree
+      const snapshots: Array<[number, SnapshotNodeExport]> = [];
+      const allNodeIds = tree.getAllNodeIds();
+      for (const nodeId of allNodeIds) {
+        const node = tree.getNode(nodeId);
+        if (!node) continue;
+        snapshots.push([nodeId, {
+          id: nodeId,
+          children: node.children,
+          displayName: node.displayName || null,
+          hocDisplayNames: null,
+          key: node.key,
+          type: componentTypeToElementType(node.type),
+          compiledWithForget: false,
+        }]);
+      }
+
+      // Build initial tree base durations from first commit
+      const initialTreeBaseDurations: Array<[number, number]> = [];
+      if (this.session.commits.length > 0) {
+        const firstCommit = this.session.commits[0];
+        for (const [id, duration] of firstCommit.fiberSelfDurations) {
+          initialTreeBaseDurations.push([id, duration]);
+        }
+      }
+
+      // Convert commits
+      const commitData: CommitDataExport[] = this.session.commits.map(
+        (commit) => this.convertCommit(commit),
+      );
+
+      dataForRoots.push({
+        commitData,
+        displayName: rootNode?.displayName || 'Root',
+        initialTreeBaseDurations,
+        operations: this.session.commits.map(() => []),
+        rootID: rootId,
+        snapshots,
+      });
+    }
+
+    return {
+      version: 5,
+      dataForRoots,
+    };
+  }
+
+  private convertCommit(commit: ProfilingCommit): CommitDataExport {
+    const changeDescriptions: Array<[number, {
+      context: null;
+      didHooksChange: boolean;
+      isFirstMount: boolean;
+      props: string[] | null;
+      state: string[] | null;
+      hooks: number[] | null;
+    }]> = [];
+
+    for (const [id, desc] of commit.changeDescriptions) {
+      changeDescriptions.push([id, {
+        context: null,
+        didHooksChange: desc.didHooksChange,
+        isFirstMount: desc.isFirstMount,
+        props: desc.props,
+        state: desc.state,
+        hooks: desc.hooks,
+      }]);
+    }
+
+    return {
+      changeDescriptions: changeDescriptions.length > 0 ? changeDescriptions : null,
+      duration: commit.duration,
+      effectDuration: null,
+      fiberActualDurations: Array.from(commit.fiberActualDurations.entries()),
+      fiberSelfDurations: Array.from(commit.fiberSelfDurations.entries()),
+      passiveEffectDuration: null,
+      priorityLevel: null,
+      timestamp: commit.timestamp,
+      updaters: null,
+    };
+  }
+
   private getAllReports(tree: ComponentTree): ComponentRenderReport[] {
     if (!this.session) return [];
 
@@ -337,6 +442,21 @@ export class Profiler {
   }
 }
 
+function componentTypeToElementType(type: ComponentType): number {
+  switch (type) {
+    case 'class': return 1;
+    case 'context': return 2;
+    case 'function': return 5;
+    case 'forwardRef': return 6;
+    case 'host': return 7;
+    case 'memo': return 8;
+    case 'profiler': return 10;
+    case 'suspense': return 12;
+    case 'other': return 9;
+    default: return 9;
+  }
+}
+
 function parseDurations(
   raw: Array<[number, number]> | number[],
   target: Map<number, number>,
diff --git a/packages/agent-react-devtools/src/types.ts b/packages/agent-react-devtools/src/types.ts
