Database governance built for humans and agents — controlling changes and access across every major database.
Explain Visualizer — Vue → React Migration
Date: 2026-05-13
Scope: frontend/explain-visualizer.html standalone entry and everything it transitively renders.
Status: Implementation in progress (uncommitted; will land in the same PR as other Stage 22 work).
Context
The Explain Visualizer is a standalone Vite entry (frontend/explain-visualizer.html → frontend/src/explain-visualizer-main.ts) that renders SQL EXPLAIN output passed via a ?token=... URL parameter. The token is a sessionStorage handle to { statement, explain, engine } stashed by createExplainToken in frontend/src/utils/pev2.ts and is opened in a separate browser tab from the SQL Editor's result view.
The page dispatches on engine:
| Engine | Renderer | Source |
|---|---|---|
| Postgres | pev2 npm package (Vue component) |
external lib |
| MSSQL | window.QP.showPlan from /libs/qp.min.js |
external lib, dynamic load |
| Spanner | Custom recursive tree (SpannerQueryPlan + SpannerPlanNode) |
repo-local Vue |
| anything else | "Unsupported engine" fallback | inline |
This is the last self-contained Vue surface in the project; the SQL Editor result view that opens this window is already React, so closing the gap removes a Vue island in an otherwise React-leaning area.
Surface inventory
Vue files in scope:
frontend/src/ExplainVisualizerApp.vue(156 lines) — engine dispatch + MSSQL imperative mount viaonMountedfrontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue— wrapper, parses JSONplanSource, finds root node byindex === 0frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue— recursive node with expand/collapse, kind badge, metadatafrontend/src/components/SpannerQueryPlan/types.ts— pure TS, framework-agnosticfrontend/src/components/SpannerQueryPlan/index.ts— barrelfrontend/src/explain-visualizer-main.ts— VuecreateApp(...).mount("body")
Cross-boundary helpers that stay as-is (no Vue deps already):
frontend/src/utils/pev2.ts—createExplainToken/readExplainFromToken(sessionStorageonly). Already consumed by both Vue (current) and React (SingleResultView.tsx).frontend/src/types/proto-es/v1/common_pb—Engineenum.
Live callers of the in-scope Vue files: none outside the explain-visualizer entry chain. rg over frontend/src confirmed pev2 (npm), SpannerQueryPlan, and html-query-plan are referenced only from ExplainVisualizerApp.vue and SpannerQueryPlan/. Safe to delete all of them at the end of this migration per the playbook deletion rule.
Strategy
Postgres — Vue island for pev2
[email protected] is a Vue 3 defineComponent. There is no maintained React port and reimplementing the Postgres EXPLAIN renderer is well out of scope. Mount a tiny Vue subapp inside a React component:
function PostgresPlanView({ planSource, planQuery }: Props) {
const hostRef = useRef<HTMLDivElement>(null);
useEffect(() => {
if (!hostRef.current) return;
const app = createApp(pev2, { planSource, planQuery });
app.mount(hostRef.current);
return () => app.unmount();
}, [planSource, planQuery]);
return <div ref={hostRef} className="size-full" />;
}
Trade-off: Vue runtime stays in this entry's bundle. Since pev2 transitively requires Vue, that cost exists even today — this approach adds no new runtime weight, just a wrapper shim.
MSSQL — pure React + dynamic load
html-query-plan exposes a global window.QP.showPlan(container, planXml). The Vue version dynamically injects /libs/qp.min.js once and then calls showPlan in onMounted. Translate that 1:1 into a useEffect with a ref. Move the dynamic-load helper out of the component to keep the effect clean and let it be reused if a second caller ever needs it.
Spanner — pure React port
Direct translation:
SpannerQueryPlan.vue→SpannerQueryPlan.tsx:useMemoforplanNodesandrootNode.SpannerPlanNode.vue→SpannerPlanNode.tsx:useState(true)forexpanded,useMemofor the derived computeds. Recurses on itself like the Vue version.- Icons: swap
lucide-vue-next→lucide-react.
The original scoped CSS is preserved verbatim by importing a sibling .css file (these are not theme-aware tokens — they're standalone visual styling for a dedicated page). Keeping the original CSS avoids visual regressions and keeps the diff focused on framework migration.
Entry point
Replace createApp(...).mount("body") with React's createRoot(...).render(...). React requires a real container, so update the HTML to add a <div id="app"> and mount there. Move the entry to frontend/src/react/explain-visualizer/main.tsx so the file lives where the react-tsx-transform Vite plugin already picks it up — no Vite config changes required.
The HTML's <script src="..."> updates to the new path. The Vite entry key (explain-visualizer) stays the same.
i18n
The Vue version uses zero locale keys for its visible strings ("Query Plan", "Unsupported Database Engine", etc. are hardcoded English in the template). The visualizer is a single-purpose dev-tooling page that opens English-only pev2 and html-query-plan UIs underneath it; adding i18n now would be scope creep and inconsistent with the embedded third-party UI. Leave strings hardcoded to preserve current behavior; can be promoted to locale keys in a follow-up if a translation request lands.
File mapping
| Vue (current) | React (target) |
|---|---|
frontend/src/explain-visualizer-main.ts |
frontend/src/react/explain-visualizer/main.tsx |
frontend/src/ExplainVisualizerApp.vue |
frontend/src/react/explain-visualizer/ExplainVisualizerApp.tsx |
| (PG branch inline) | frontend/src/react/explain-visualizer/PostgresPlanView.tsx |
| (MSSQL branch inline) | frontend/src/react/explain-visualizer/MSSQLPlanView.tsx + loadQueryPlanScript.ts helper |
frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue |
frontend/src/react/explain-visualizer/SpannerQueryPlan.tsx |
frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue |
frontend/src/react/explain-visualizer/SpannerPlanNode.tsx |
frontend/src/components/SpannerQueryPlan/types.ts |
frontend/src/react/explain-visualizer/spanner-types.ts |
frontend/src/components/SpannerQueryPlan/index.ts |
(deleted; no callers left) |
frontend/explain-visualizer.html (mount body, ts entry) |
same file, edited to add <div id="app"> + point at the new .tsx entry |
Verification
Minimum gate sequence per the migration playbook:
pnpm --dir frontend fixpnpm --dir frontend checkpnpm --dir frontend type-check(vue-tsc for Vue, separate React tsconfig for the new React tree)pnpm --dir frontend test
Add a focused unit test for SpannerPlanNode (recursion, expand/collapse, metadata filtering) since the recursive tree is the largest piece of net-new React code in this migration.
Manual smoke (can only be done from the SQL Editor UI in a running dev environment): run an EXPLAIN on each of Postgres / MSSQL / Spanner and confirm the new tab renders correctly. Listed as a follow-up the user will do; no Playwright in scope.
Risk and rollback
pev2Vue-island approach is reversible by reverting the migration commit — no Vite/Vue/React config changes are required to keep the surface working.- The Spanner CSS port preserves classnames so visual regressions, if any, are pinpointable.
- No deletions until the React surface is verified locally; the playbook's "verify no live callers before deleting" check is already complete for the Spanner dir (no callers outside this entry).