feat(vue): Register a route provider read off the Vue app

`vue-router` sets `app.config.globalProperties.$router` when it installs, and the
SDK is already given the app, so the provider needs no new option and no router
passed to the tracing integration.

Registered from `init()`, so route parameterization no longer depends on tracing
being enabled and works for users who never pass `router` to
`browserTracingIntegration`. The router is looked up per call rather than
captured, because `app.use(router)` may run either side of `Sentry.init()`.

Returns the matched path rather than `route.name` even under
`routeLabel: 'name'`: callers set `url.template` from this and a route name is an
identifier, not a template. The navigation instrumentation still names the span
after the route name when the user asked for it.

Author: logaretm

packages/vue/src/index.ts

@@ -8,5 +8,6 @@ export { browserTracingIntegration } from './browserTracingIntegration';
 export { attachErrorHandler } from './errorhandler';
 export { createTracingMixins } from './tracing';
 export { vueIntegration } from './integration';
+export { createVueRouteProvider } from './routeProvider';
 export type { VueIntegrationOptions } from './integration';
 export { createSentryPiniaPlugin } from './pinia';

packages/vue/src/routeProvider.ts

@@ -0,0 +1,44 @@
+import type { RouteProvider } from '@sentry/core';
+import { createUrlRouteProvider } from '@sentry/core';
+import type { Route } from './router';
+
+// Vue Router 3 resolves to `{ route }`, Vue Router 4+ returns the route itself.
+type ResolvedLocation = Route | { route: Route };
+
+interface InstalledRouter {
+  resolve?: (to: string) => ResolvedLocation;
+}
+
+interface AppWithRouter {
+  config?: { globalProperties?: { $router?: InstalledRouter } };
+}
+
+/**
+ * Builds a route provider from a `vue-router` instance, however the SDK got hold of one.
+ *
+ * The router is looked up per call rather than captured once, because `app.use(router)` may run
+ * either side of `Sentry.init()` and only the app itself is guaranteed to exist by then.
+ */
+export function createVueRouteProvider(getRouter: () => InstalledRouter | undefined): RouteProvider {
+  return createUrlRouteProvider(url => {
+    const resolved = getRouter()?.resolve?.(`${url.pathname}${url.search}${url.hash}`);
+    if (!resolved) {
+      return undefined;
+    }
+
+    const route = 'matched' in resolved ? resolved : resolved.route;
+
+    // Always the matched path, never `route.name`. Callers set `url.template` from this, and a route
+    // name is an identifier rather than a template.
+    return route.matched[route.matched.length - 1]?.path;
+  });
+}
+
+/**
+ * Reads the router `vue-router` installed onto a Vue app.
+ */
+export function getRouterFromApp(app: unknown): InstalledRouter | undefined {
+  const firstApp: AppWithRouter | undefined = Array.isArray(app) ? app[0] : (app as AppWithRouter | undefined);
+
+  return firstApp?.config?.globalProperties?.$router;
+}

packages/vue/src/sdk.ts

@@ -1,10 +1,11 @@
 import { getDefaultIntegrations, init as browserInit } from '@sentry/browser';
 import type { Client } from '@sentry/core';
-import { applySdkMetadata, setNormalizeStringifier } from '@sentry/core/browser';
+import { applySdkMetadata, setNormalizeStringifier, setRouteProvider } from '@sentry/core/browser';
 
 import { vueIntegration } from './integration';
 import type { Options } from './types';
 import { normalizeStringifyValue } from './normalizeStringifyValue';
+import { createVueRouteProvider, getRouterFromApp } from './routeProvider';
 
 /**
  * Inits the Vue SDK
@@ -19,6 +20,14 @@ export function init(options: Partial<Omit<Options, 'tracingOptions'>> = {}): Cl
 
   const client = browserInit(opts);
 
+  // Registered here rather than from `browserTracingIntegration` so route parameterization does not
+  // depend on tracing. The router is read off the app the SDK is already given, so users who never
+  // pass `router` to the tracing integration still get parameterized routes.
+  setRouteProvider(
+    createVueRouteProvider(() => getRouterFromApp(opts.app)),
+    client,
+  );
+
   // Add vue-specific stringification
   setNormalizeStringifier(normalizeStringifyValue);
 

packages/vue/test/routeProvider.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { createVueRouteProvider, getRouterFromApp } from '../src/routeProvider';
+import type { Route } from '../src/router';
+
+function makeRoute(overrides: Partial<Route> = {}): Route {
+  return { path: '/users/42', query: {}, params: {}, matched: [{ path: '/users/:id' }], ...overrides };
+}
+
+/** Vue Router 4+ returns the route itself. */
+const v4Router = (route: Route | undefined) => ({ resolve: () => route as Route });
+/** Vue Router 3 wraps it in `{ route }`. */
+const v3Router = (route: Route) => ({ resolve: () => ({ route }) });
+
+/** A Vue 3 app with `vue-router` installed, which sets `config.globalProperties.$router`. */
+const appWithRouter = (router: unknown) => ({ config: { globalProperties: { $router: router } } });
+
+describe('getRouterFromApp', () => {
+  it('reads the router vue-router installed on the app', () => {
+    const router = v4Router(makeRoute());
+
+    expect(getRouterFromApp(appWithRouter(router))).toBe(router);
+  });
+
+  it('reads from the first app when several were passed', () => {
+    const router = v4Router(makeRoute());
+
+    expect(getRouterFromApp([appWithRouter(router), appWithRouter(undefined)])).toBe(router);
+  });
+
+  it('returns undefined when no router is installed yet', () => {
+    expect(getRouterFromApp({ config: { globalProperties: {} } })).toBeUndefined();
+    expect(getRouterFromApp(undefined)).toBeUndefined();
+  });
+});
+
+describe('createVueRouteProvider', () => {
+  it('resolves the matched path for Vue Router 4+', () => {
+    const provider = createVueRouteProvider(() => v4Router(makeRoute()));
+
+    expect(provider.resolveRoute(new URL('https://example.com/users/42'))).toBe('/users/:id');
+  });
+
+  it('unwraps the `{ route }` shape Vue Router 3 resolves to', () => {
+    const provider = createVueRouteProvider(() => v3Router(makeRoute()));
+
+    expect(provider.resolveRoute(new URL('https://example.com/users/42'))).toBe('/users/:id');
+  });
+
+  it('returns the matched path even for a named route, since a name is not a template', () => {
+    const provider = createVueRouteProvider(() => v4Router(makeRoute({ name: 'UserProfile' })));
+
+    expect(provider.resolveRoute(new URL('https://example.com/users/42'))).toBe('/users/:id');
+  });
+
+  it('picks the router up late, since `app.use(router)` may run after `Sentry.init`', () => {
+    let router: ReturnType<typeof v4Router> | undefined;
+    const provider = createVueRouteProvider(() => router);
+
+    expect(provider.resolveRoute(new URL('https://example.com/users/42'))).toBeUndefined();
+
+    router = v4Router(makeRoute());
+    expect(provider.resolveRoute(new URL('https://example.com/users/42'))).toBe('/users/:id');
+  });
+
+  it('returns undefined when nothing matched', () => {
+    const provider = createVueRouteProvider(() => v4Router(makeRoute({ matched: [] })));
+
+    expect(provider.resolveRoute(new URL('https://example.com/nope'))).toBeUndefined();
+  });
+});