From e30d851f1ea517154f6c4881e5e92e1022b4c5f5 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Mon, 31 Aug 2026 15:11:38 -0400 Subject: [PATCH 1/6] feat(astro): Register a route provider backed by the route meta tag The middleware already injects the parameterized route into the document it renders, but it was only readable from the pageload instrumentation. Registered from `init()` rather than the tracing integration, so route parameterization no longer depends on tracing being enabled. Not a matcher: the document only describes the page it rendered, so a URL other than the current one resolves to undefined rather than a guess. Verified against Astro 5.18 that `ClientRouter` swaps the tag during `astro:after-swap", at the same moment `location` changes, so reading it per call stays correct across soft navigations and back/forward. --- packages/astro/src/client/routeProvider.ts | 40 ++++++++++++ packages/astro/src/client/sdk.ts | 12 +++- .../astro/test/client/routeProvider.test.ts | 65 +++++++++++++++++++ 3 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 packages/astro/src/client/routeProvider.ts create mode 100644 packages/astro/test/client/routeProvider.test.ts diff --git a/packages/astro/src/client/routeProvider.ts b/packages/astro/src/client/routeProvider.ts new file mode 100644 index 000000000000..ee49fd88f978 --- /dev/null +++ b/packages/astro/src/client/routeProvider.ts @@ -0,0 +1,40 @@ +import type { RouteProvider } from '@sentry/core'; +import { WINDOW } from '@sentry/browser'; + +/** + * Reads the parameterized route the Astro middleware injects into the document it rendered. + */ +function readRouteNameFromMeta(): string | undefined { + const optionalDocument = WINDOW.document as (typeof WINDOW)['document'] | undefined; + const content = optionalDocument?.querySelector('meta[name=sentry-route-name]')?.getAttribute('content'); + if (!content) { + return undefined; + } + + try { + return decodeURIComponent(content); + } catch { + // The middleware encodes the route, so a value we can't decode isn't one we put there. + return undefined; + } +} + +/** + * A route provider backed by the `sentry-route-name` meta tag the Astro middleware injects. + * + * Unlike a manifest-backed provider this is not a matcher: the document only ever describes the page + * it rendered, so a URL other than the current one resolves to `undefined` rather than a guess. + * + * The tag does track client-side navigations. Astro's `ClientRouter` swaps it during + * `astro:after-swap`, at the same moment `location` changes, so reading it per call stays correct + * across soft navigations and back/forward. It is only stale *during* a navigation, before the swap, + * which is why `resolveRoute` refuses to answer for anything but the current path. + */ +export function createAstroRouteProvider(): RouteProvider { + const isCurrentPath = (url: URL): boolean => url.pathname === WINDOW.location?.pathname; + + return { + resolveRoute: url => (isCurrentPath(url) ? readRouteNameFromMeta() : undefined), + resolveCurrentRoute: readRouteNameFromMeta, + }; +} diff --git a/packages/astro/src/client/sdk.ts b/packages/astro/src/client/sdk.ts index 21c5770f255f..648664cf600d 100644 --- a/packages/astro/src/client/sdk.ts +++ b/packages/astro/src/client/sdk.ts @@ -1,8 +1,9 @@ import type { BrowserOptions } from '@sentry/browser'; import { getDefaultIntegrations as getBrowserDefaultIntegrations, init as initBrowserSdk } from '@sentry/browser'; import type { Client, Integration } from '@sentry/core'; -import { applySdkMetadata } from '@sentry/core'; +import { applySdkMetadata, setRouteProvider } from '@sentry/core'; import { browserTracingIntegration } from './browserTracingIntegration'; +import { createAstroRouteProvider } from './routeProvider'; // Tree-shakable guard to remove all code related to tracing declare const __SENTRY_TRACING__: boolean; @@ -20,7 +21,14 @@ export function init(options: BrowserOptions): Client | undefined { applySdkMetadata(opts, 'astro', ['astro', 'browser']); - return initBrowserSdk(opts); + const client = initBrowserSdk(opts); + + // Registered here rather than from the tracing integration so route parameterization does not + // depend on tracing: the middleware injects the route into the document, so anything that needs a + // route name (bfcache metrics, web vitals) can resolve one even with tracing disabled. + setRouteProvider(createAstroRouteProvider(), client); + + return client; } function getDefaultIntegrations(options: BrowserOptions): Integration[] { diff --git a/packages/astro/test/client/routeProvider.test.ts b/packages/astro/test/client/routeProvider.test.ts new file mode 100644 index 000000000000..a81080eb37ab --- /dev/null +++ b/packages/astro/test/client/routeProvider.test.ts @@ -0,0 +1,65 @@ +import { GLOBAL_OBJ } from '@sentry/core'; +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { createAstroRouteProvider } from '../../src/client/routeProvider'; + +let originalDocument: unknown; +let originalLocation: unknown; + +/** Mirrors what the Astro middleware injects: an encoded route on a `sentry-route-name` meta tag. */ +function renderPage(pathname: string, routeName: string | undefined): void { + const meta = routeName + ? { getAttribute: (attr: string) => (attr === 'content' ? encodeURIComponent(routeName) : null) } + : null; + + (GLOBAL_OBJ as { document?: unknown }).document = { + querySelector: (selector: string) => (selector === 'meta[name=sentry-route-name]' ? meta : null), + }; + (GLOBAL_OBJ as { location?: unknown }).location = { pathname }; +} + +describe('createAstroRouteProvider', () => { + beforeEach(() => { + originalDocument = (GLOBAL_OBJ as { document?: unknown }).document; + originalLocation = (GLOBAL_OBJ as { location?: unknown }).location; + }); + + afterEach(() => { + (GLOBAL_OBJ as { document?: unknown }).document = originalDocument; + (GLOBAL_OBJ as { location?: unknown }).location = originalLocation; + }); + + it('resolves the current route from the meta tag', () => { + renderPage('/users/1', '/users/[id]'); + + expect(createAstroRouteProvider().resolveCurrentRoute()).toBe('/users/[id]'); + }); + + it('resolves a URL that is the current page', () => { + renderPage('/users/1', '/users/[id]'); + + expect(createAstroRouteProvider().resolveRoute(new URL('https://example.com/users/1'))).toBe('/users/[id]'); + }); + + it('refuses to answer for a URL that is not the current page', () => { + renderPage('/users/1', '/users/[id]'); + + // The document only ever describes the page it rendered, so guessing here would be wrong. This is + // also what keeps a navigation from being named after the route it is leaving. + expect(createAstroRouteProvider().resolveRoute(new URL('https://example.com/posts/hello'))).toBeUndefined(); + }); + + it('follows a client-side navigation, since the meta tag is swapped with the document', () => { + const provider = createAstroRouteProvider(); + renderPage('/users/1', '/users/[id]'); + expect(provider.resolveCurrentRoute()).toBe('/users/[id]'); + + renderPage('/posts/hello', '/posts/[slug]'); + expect(provider.resolveCurrentRoute()).toBe('/posts/[slug]'); + }); + + it('returns undefined when the middleware injected no route', () => { + renderPage('/users/1', undefined); + + expect(createAstroRouteProvider().resolveCurrentRoute()).toBeUndefined(); + }); +}); From d411e8aa7439996f2496cc5a2ad5971dd67aabcb Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 24 Sep 2026 14:03:23 -0400 Subject: [PATCH 2/6] ref(astro): Import the route provider API from `@sentry/core/browser` --- packages/astro/src/client/routeProvider.ts | 2 +- packages/astro/src/client/sdk.ts | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/astro/src/client/routeProvider.ts b/packages/astro/src/client/routeProvider.ts index ee49fd88f978..8409c08b0c14 100644 --- a/packages/astro/src/client/routeProvider.ts +++ b/packages/astro/src/client/routeProvider.ts @@ -1,4 +1,4 @@ -import type { RouteProvider } from '@sentry/core'; +import type { RouteProvider } from '@sentry/core/browser'; import { WINDOW } from '@sentry/browser'; /** diff --git a/packages/astro/src/client/sdk.ts b/packages/astro/src/client/sdk.ts index 648664cf600d..800cc1222c2b 100644 --- a/packages/astro/src/client/sdk.ts +++ b/packages/astro/src/client/sdk.ts @@ -1,7 +1,8 @@ import type { BrowserOptions } from '@sentry/browser'; import { getDefaultIntegrations as getBrowserDefaultIntegrations, init as initBrowserSdk } from '@sentry/browser'; import type { Client, Integration } from '@sentry/core'; -import { applySdkMetadata, setRouteProvider } from '@sentry/core'; +import { applySdkMetadata } from '@sentry/core'; +import { setRouteProvider } from '@sentry/core/browser'; import { browserTracingIntegration } from './browserTracingIntegration'; import { createAstroRouteProvider } from './routeProvider'; From 423bfb7bfdb48c2ac99d4ba0274efb36566d338c Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 24 Sep 2026 14:30:04 -0400 Subject: [PATCH 3/6] ref(astro): Only require the pathname in the route provider --- packages/astro/src/client/routeProvider.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/astro/src/client/routeProvider.ts b/packages/astro/src/client/routeProvider.ts index 8409c08b0c14..624b94863fc6 100644 --- a/packages/astro/src/client/routeProvider.ts +++ b/packages/astro/src/client/routeProvider.ts @@ -31,7 +31,7 @@ function readRouteNameFromMeta(): string | undefined { * which is why `resolveRoute` refuses to answer for anything but the current path. */ export function createAstroRouteProvider(): RouteProvider { - const isCurrentPath = (url: URL): boolean => url.pathname === WINDOW.location?.pathname; + const isCurrentPath = (url: { pathname: string }): boolean => url.pathname === WINDOW.location?.pathname; return { resolveRoute: url => (isCurrentPath(url) ? readRouteNameFromMeta() : undefined), From c9b3e564b303afc110f17fe39e170f6f5b8830f4 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 24 Sep 2026 14:36:14 -0400 Subject: [PATCH 4/6] ref(astro): Import the route provider API from `@sentry/browser` --- packages/astro/src/client/routeProvider.ts | 2 +- packages/astro/src/client/sdk.ts | 7 +++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/packages/astro/src/client/routeProvider.ts b/packages/astro/src/client/routeProvider.ts index 624b94863fc6..6aeec7bdfd02 100644 --- a/packages/astro/src/client/routeProvider.ts +++ b/packages/astro/src/client/routeProvider.ts @@ -1,4 +1,4 @@ -import type { RouteProvider } from '@sentry/core/browser'; +import type { RouteProvider } from '@sentry/browser'; import { WINDOW } from '@sentry/browser'; /** diff --git a/packages/astro/src/client/sdk.ts b/packages/astro/src/client/sdk.ts index 800cc1222c2b..081beb60c696 100644 --- a/packages/astro/src/client/sdk.ts +++ b/packages/astro/src/client/sdk.ts @@ -1,8 +1,11 @@ import type { BrowserOptions } from '@sentry/browser'; -import { getDefaultIntegrations as getBrowserDefaultIntegrations, init as initBrowserSdk } from '@sentry/browser'; +import { + getDefaultIntegrations as getBrowserDefaultIntegrations, + init as initBrowserSdk, + setRouteProvider, +} from '@sentry/browser'; import type { Client, Integration } from '@sentry/core'; import { applySdkMetadata } from '@sentry/core'; -import { setRouteProvider } from '@sentry/core/browser'; import { browserTracingIntegration } from './browserTracingIntegration'; import { createAstroRouteProvider } from './routeProvider'; From e5d0d388ba78c96cacb575c843af7413e0f79744 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 24 Sep 2026 15:57:53 -0400 Subject: [PATCH 5/6] ref(astro): Pass the route provider as the `routeProvider` option --- packages/astro/src/client/sdk.ts | 18 +++++------------- packages/astro/test/client/sdk.test.ts | 11 +++++++++++ 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/packages/astro/src/client/sdk.ts b/packages/astro/src/client/sdk.ts index 081beb60c696..14effd00cacb 100644 --- a/packages/astro/src/client/sdk.ts +++ b/packages/astro/src/client/sdk.ts @@ -1,9 +1,5 @@ import type { BrowserOptions } from '@sentry/browser'; -import { - getDefaultIntegrations as getBrowserDefaultIntegrations, - init as initBrowserSdk, - setRouteProvider, -} from '@sentry/browser'; +import { getDefaultIntegrations as getBrowserDefaultIntegrations, init as initBrowserSdk } from '@sentry/browser'; import type { Client, Integration } from '@sentry/core'; import { applySdkMetadata } from '@sentry/core'; import { browserTracingIntegration } from './browserTracingIntegration'; @@ -20,19 +16,15 @@ declare const __SENTRY_TRACING__: boolean; export function init(options: BrowserOptions): Client | undefined { const opts = { defaultIntegrations: getDefaultIntegrations(options), + // The middleware injects the route into the document, so route parameterization works from `init` on, + // even with tracing disabled. + routeProvider: createAstroRouteProvider(), ...options, }; applySdkMetadata(opts, 'astro', ['astro', 'browser']); - const client = initBrowserSdk(opts); - - // Registered here rather than from the tracing integration so route parameterization does not - // depend on tracing: the middleware injects the route into the document, so anything that needs a - // route name (bfcache metrics, web vitals) can resolve one even with tracing disabled. - setRouteProvider(createAstroRouteProvider(), client); - - return client; + return initBrowserSdk(opts); } function getDefaultIntegrations(options: BrowserOptions): Integration[] { diff --git a/packages/astro/test/client/sdk.test.ts b/packages/astro/test/client/sdk.test.ts index 9225af26b564..041034f9164e 100644 --- a/packages/astro/test/client/sdk.test.ts +++ b/packages/astro/test/client/sdk.test.ts @@ -92,6 +92,17 @@ describe('Sentry client SDK', () => { }); }); + it('passes the Astro route provider unless the user passed one', () => { + init({ dsn: 'https://public@dsn.ingest.sentry.io/1337' }); + expect(browserInit).toHaveBeenLastCalledWith( + expect.objectContaining({ routeProvider: expect.objectContaining({ resolveRoute: expect.any(Function) }) }), + ); + + const routeProvider = { resolveRoute: () => '/custom', resolveCurrentRoute: () => '/custom' }; + init({ dsn: 'https://public@dsn.ingest.sentry.io/1337', routeProvider }); + expect(browserInit).toHaveBeenLastCalledWith(expect.objectContaining({ routeProvider })); + }); + it('returns client from init', () => { expect(init({})).not.toBeUndefined(); }); From bccce36b502e6834c754d70d28fe78d1ca5e5f00 Mon Sep 17 00:00:00 2001 From: Abdelrahman Awad Date: Thu, 24 Sep 2026 17:13:21 -0400 Subject: [PATCH 6/6] test(astro): Cover route resolution through the route provider --- .../src/pages/route-provider/[id].astro | 18 ++++++++++++++++++ .../astro-5/tests/route-provider.test.ts | 10 ++++++++++ 2 files changed, 28 insertions(+) create mode 100644 dev-packages/e2e-tests/test-applications/astro-5/src/pages/route-provider/[id].astro create mode 100644 dev-packages/e2e-tests/test-applications/astro-5/tests/route-provider.test.ts diff --git a/dev-packages/e2e-tests/test-applications/astro-5/src/pages/route-provider/[id].astro b/dev-packages/e2e-tests/test-applications/astro-5/src/pages/route-provider/[id].astro new file mode 100644 index 000000000000..ff0ee0f13d59 --- /dev/null +++ b/dev-packages/e2e-tests/test-applications/astro-5/src/pages/route-provider/[id].astro @@ -0,0 +1,18 @@ +--- +import Layout from '../../layouts/Layout.astro'; + +export const prerender = false; +--- + + + +
+ + + diff --git a/dev-packages/e2e-tests/test-applications/astro-5/tests/route-provider.test.ts b/dev-packages/e2e-tests/test-applications/astro-5/tests/route-provider.test.ts new file mode 100644 index 000000000000..09e444a04c26 --- /dev/null +++ b/dev-packages/e2e-tests/test-applications/astro-5/tests/route-provider.test.ts @@ -0,0 +1,10 @@ +import { expect, test } from '@playwright/test'; + +// The route provider reads the route the middleware renders into the page, so this fails if that route +// never reaches the browser. +test('resolves the parameterized route through the route provider', async ({ page }) => { + await page.goto('/route-provider/123'); + await page.locator('#resolve-route').click(); + + await expect(page.locator('#resolved-route')).toHaveText('/route-provider/[id]'); +});