vscode-webview-trpc-messaging
Implements tRPC-based communication between the Rayfin VS Code extension host and React webviews (packages/tools/vscode). Use when creating new webview procedures (queries, mutations, subscriptions), adding a new webview router, wiring up a webview controller, using the tRPC client from React components, applying telemetry middleware (trpcToTelemetry), or supporting AbortSignal-based cancellation in webview operations.
- License 许可
- MIT
- 所属仓库
- microsoft/rayfin
- 最近更新
- 2026-11-12
- Stars
- ★ 662
- Forks
- 77
01 前言 Front Matter
- name
- vscode-webview-trpc-messaging
- description
- Implements tRPC-based communication between the Rayfin VS Code extension host and React webviews (packages/tools/vscode). Use when creating new webview procedures (queries, mutations, subscriptions), adding a new webview router, wiring up a webview controller, using the tRPC client from React components, applying telemetry middleware (trpcToTelemetry), or supporting AbortSignal-based cancellation in webview operations.
02 资源文件 4
- 参考文档resources/integration-testing.md12.7 KB
- 参考文档resources/local-setup.md11.8 KB
- 参考文档resources/replay-testing.md12.1 KB
- 参考文档resources/unit-testing.md8.5 KB
03 SKILL.md 正文
Webview tRPC Messaging
Type-safe RPC communication between the VS Code extension host (server) and React webviews (client) using tRPC.
Architecture Overview
React Webview (client) Extension Host (server)
───────────────────── ──────────────────────
useTrpcClient() hook WebviewController
└─ createTRPCClient └─ setupTrpc()
└─ vscodeLink ──── postMessage ────► ├─ callerFactory(appRouter)
(send/onReceive) ◄─────┤ └─ procedure(input)
└─ abort/subscription.stop
Key files (read as needed for implementation details):
| File | Purpose |
|---|---|
packages/tools/vscode/src/webviews/api/extension-server/trpc.ts |
tRPC init, publicProcedure, publicProcedureWithTelemetry |
packages/tools/vscode/src/webviews/api/configuration/appRouter.ts |
Root router bundling all view routers + commonRouter |
packages/tools/vscode/src/webviews/api/extension-server/WebviewController.ts |
WebviewPanel lifecycle, tRPC message dispatcher (queries, mutations, subscriptions, abort) |
packages/tools/vscode/src/webviews/api/webview-client/useTrpcClient.ts |
React hook providing the tRPC client |
packages/tools/vscode/src/webviews/api/webview-client/vscodeLink.ts |
Custom tRPC link bridging postMessage transport |
Creating a New Router
Each webview maintains its own router. Follow this pattern:
1. Define the router context
Extend BaseRouterContext with view-specific fields:
// packages/tools/vscode/src/webviews/myView/myViewRouter.ts
import { type BaseRouterContext } from '../api/configuration/appRouter';
export type RouterContext = BaseRouterContext & {
clusterId: string;
viewId: string;
databaseName: string;
// add view-specific fields
};
2. Define procedures
import { z } from 'zod';
import { publicProcedureWithTelemetry, router, type WithTelemetry } from '../../api/extension-server/trpc';
export const myViewRouter = router({
// Query with telemetry (preferred for operations that touch external services)
getData: publicProcedureWithTelemetry.input(z.object({ id: z.string() })).query(async ({ input, ctx }) => {
const myCtx = ctx as WithTelemetry<RouterContext>;
// myCtx.telemetry is guaranteed present
// myCtx.signal is the AbortSignal for cancellation
return { data: 'result' };
}),
// Mutation without telemetry (rare, use for fire-and-forget)
doAction: publicProcedure.input(z.string()).mutation(({ input }) => {
// lightweight operation
}),
});
3. Register in appRouter
// packages/tools/vscode/src/webviews/api/configuration/appRouter.ts
import { myViewRouter } from '../../myView/myViewRouter';
export const appRouter = router({
common: commonRouter,
myView: myViewRouter, // <-- add here
});
4. Create the controller
// packages/tools/vscode/src/webviews/myView/myViewController.ts
import { WebviewController } from '../api/extension-server/WebviewController';
import { type RouterContext } from './myViewRouter';
export class MyViewController extends WebviewController<MyViewConfig> {
constructor(initialData: MyViewConfig) {
super(ext.context, title, 'myViewName', initialData);
const trpcContext: RouterContext = {
webviewName: 'myView',
clusterId: initialData.clusterId,
viewId: initialData.viewId,
};
this.setupTrpc(trpcContext);
}
}
Important: The
webviewNamein theWebviewControllerconstructor is the registry key (must match a key inWebviewRegistry, e.g.myViewName). ThewebviewNamein the tRPC context is a telemetry label used in telemetry event names (e.g.myView). These are intentionally different values — do not confuse them.
5. Register in WebviewRegistry
Add your React component to the registry. The key must match the webviewName passed to WebviewController's constructor. The WebviewName type (exported from the same file) ensures compile-time validation of webview names.
// packages/tools/vscode/src/webviews/api/configuration/WebviewRegistry.ts
import { MyView } from '../../myView/MyView';
export const WebviewRegistry = {
myViewName: MyView, // <-- add your entry
} as const;
export type WebviewName = keyof typeof WebviewRegistry;
Telemetry: publicProcedure vs publicProcedureWithTelemetry
| Base | When to use | ctx.telemetry |
|---|---|---|
publicProcedure |
Fire-and-forget, no external calls, telemetry reported separately | undefined |
publicProcedureWithTelemetry |
Default choice. Any procedure touching DB, network, or user-visible work | Guaranteed via trpcToTelemetry middleware |
trpcToTelemetry (file-local, not exported) wraps the procedure in callWithTelemetryAndErrorHandling, auto-generating a telemetry event named rayfin.rpc.{type}.{path} and recording errors, duration, and abort status.
Access telemetry safely:
const myCtx = ctx as WithTelemetry<RouterContext>;
myCtx.telemetry.properties.myCustomProp = 'value';
myCtx.telemetry.measurements.itemCount = items.length;
AbortSignal Support
Every tRPC operation (query, mutation, subscription) receives its own AbortController. Cancellation flows:
Client (React) Server (Extension Host)
────────────── ──────────────────────
// Queries/Mutations:
ac = new AbortController()
trpcClient.myProc.query(input,
{ signal: ac.signal })
ac.abort() → sends 'abort' msg → abortController.abort()
→ ctx.signal.aborted = true
// Subscriptions:
sub = trpcClient.mySub.subscribe(...)
sub.unsubscribe() → 'subscription.stop' → abortController.abort()
Using abort in procedures
getData: publicProcedureWithTelemetry
.input(z.object({ filter: z.record(z.unknown()) }))
.query(async ({ input, ctx }) => {
const myCtx = ctx as WithTelemetry<RouterContext>;
// Option 1: Pass to APIs that accept AbortSignal
const response = await fetch(url, { signal: myCtx.signal });
// Option 2: Manual check in loops
for (const item of items) {
if (myCtx.signal?.aborted) return;
await processItem(item);
}
}),
Client-side abort
const { trpcClient } = useTrpcClient();
const abortControllerRef = useRef<AbortController>();
const runQuery = async () => {
abortControllerRef.current?.abort(); // cancel previous
const ac = new AbortController();
abortControllerRef.current = ac;
const result = await trpcClient.myView.myQuery.query(input, { signal: ac.signal });
};
When trpcToTelemetry detects an aborted signal, it sets telemetry.properties.aborted = 'true' and result = 'Canceled' automatically.
Subscriptions
Subscriptions stream multiple values from server to client using async generators:
// Server (router)
streamData: publicProcedureWithTelemetry
.input(z.object({ batchSize: z.number() }))
.subscription(async function* ({ input, ctx }) {
const myCtx = ctx as WithTelemetry<RouterContext>;
for (let i = 0; i < total; i += input.batchSize) {
if (myCtx.signal?.aborted) return; // check before each yield
const batch = await fetchBatch(i, input.batchSize);
yield batch;
}
}),
// Client (React)
const sub = trpcClient.myView.streamData.subscribe(
{ batchSize: 100 },
{
onData(batch) { /* handle each batch */ },
onComplete() { /* all done */ },
onError(err) { /* handle error */ },
},
);
// To stop:
sub.unsubscribe();
Client-Side Hook Usage
import { useTrpcClient } from '../api/webview-client/useTrpcClient';
import { useConfiguration } from '../api/webview-client/useConfiguration';
export const MyComponent = () => {
const { trpcClient } = useTrpcClient();
const config = useConfiguration<MyViewConfig>();
useEffect(() => {
trpcClient.myView.getData.query({ id: config.documentId }).then(setData);
}, []);
};
useConfiguration<T>() retrieves the initial config passed to WebviewController constructor (serialized via encodeURIComponent(JSON.stringify(...))).
Common Pitfalls
- Never use
anyin procedure context casts — useWithTelemetry<RouterContext>orRouterContext - Always prefer
publicProcedureWithTelemetryunless you have a specific reason not to - Always check
myCtx.signal?.abortedin long-running loops — not checking causes wasted work after client cancels - Do not mutate the shared
contextobject —WebviewControllerclones it per-operation already, but router code should treatctxas read-only - Input validation uses
zod— always define.input(z.object({...}))for type safety - The
commonRouterhandles cross-cutting concerns (error reporting, telemetry events, surveys, URL opening) — do not duplicate these in view-specific routers
04 同仓库更多 Skills
rayfin-getting-started
Use when starting or creating a NEW Rayfin app, or when a Rayfin task comes up and you are not yet inside a Rayfin project. Gets you into a project with the Rayfin CLI, then hands off to the authoritative, version-locked in-project rayfin skill/docs that own all in-project work. Triggers: build a Rayfin app, start a Rayfin project, create a new Rayfin app, create-rayfin, npm create @microsoft/rayfin, rayfin init, scaffold rayfin, rayfin CLI, rayfin template, universal app, awesome-rayfin gallery, get started with Rayfin
visuals
Use when user wants to incorporate charts, graphs, data grid, or other visual representations of data into their project. Use VegaVisual and DataGrid components to create these visuals, utilizing the shared DataTable input, formatting, theme, and interactivity. Covers the onInteraction selection/click events host apps consume, named multi-table data input for layered overlays and reference lines, and Vega-Lite native selections. Triggers: chart, graph, plot, dashboard, KPI, metric, trend, scorecard, data grid, visualize.
schema-discovery
Explore Power BI semantic model schemas using DAX INFO functions. Progressive metadata discovery strategy, scope estimation, and narrowing techniques for tables, columns, measures, and relationships.
query-design
Separates DAX data-fetching from TypeScript presentation. Guides when to use DAX vs. TypeScript vs. Vega-Lite for aggregation, total rows, FORMAT(), SELECTCOLUMNS, BLANK handling, filtering, multi-grain queries, cross-filtering and cross-highlight subset/overlay queries, and format strings.
functions-capability
Apply and build the Universal App functions capability. Use for trusted server-side logic, secrets, external APIs, custom model endpoints, published Fabric data agents, webhooks, or privileged operations.
fabric-sdk
How to query Fabric data from a running app through the Rayfin connectors client. Use getRayfinClient().connectors.<name>.executeQuery to run DAX against a semantic model, and toQueryResult to normalize the response.