This PR will resolve the core reason for the series of fixes / handling for automatic lazy-route resolution for a while.
Related: #18898, #18881, #18346, #18155, #18098, #17962, #17867, #17438, #17277
The core issue we have been trying to tackle is not having access to the complete route hierarchy when asynchronously loaded lazy routes are used. React Router provides a route manifest that we can use while matching parameterized transaction names with routes in all cases except this lazy-routes pattern.
This problem has been discussed on React Router:
While this has been addressed for Remix / React Router (Framework Mode), it's still not available in Library Mode. The manifest contains the lazily-loaded route, only when it's navigated to. While waiting for navigation, our transactions can be dropped for several reasons, such as user behaviour like switching tabs (document.hidden guard), hitting timeouts like idleTimeout, and potentially other reasons. This results in incomplete transaction naming with leftover wildcards, which caused broken aggregation on the Sentry dashboard.
The series of attempts to fix this while keeping automatic route discovery has been prone to race conditions and required special-case handling of each edge case scenario, also requiring a considerable amount of internal logic, affecting our readability and performance. At the end, all failed in giving completely robust and deterministic results on the customers' side.
This PR proposes a new option: lazyRouteManifest specifically for lazy routes. This will let us have initial information about the route hierarchy. So we can assign correct parameterized transaction names without needing to wait for navigated state.
It's a static array of routes in parameterized format (needs to be maintained by the users on route hierarchy updates) like:
Sentry.reactRouterV7BrowserTracingIntegration({// ...enableAsyncRouteHandlers: truelazyRouteManifest: ['/','/pricing','/features','/login','/signup','/forgot-password','/reset-password/:token','/org/:orgSlug','/org/:orgSlug/dashboard','/org/:orgSlug/projects','/org/:orgSlug/projects/:projectId','/org/:orgSlug/projects/:projectId/settings','/org/:orgSlug/projects/:projectId/issues','/org/:orgSlug/projects/:projectId/issues/:issueId','/org/:orgSlug/team','/org/:orgSlug/team/:memberId','/org/:orgSlug/settings','/org/:orgSlug/billing','/admin','/admin/users','/admin/users/:userId','/admin/orgs','/admin/orgs/:orgId',],})- This will only be active when
enableAsyncRouteHandlers is set to true - To match URLs with given routes, we mimic React Router's own implementation.
- When this is not provided or fails, it falls back to the current behaviour
- Also added E2E tests that will fail when (if at some point) React Router manifests include the lazy routes before navigation, so we'll be aware and plan depending on that manifest instead.
Note
The pull request "feat(react): Add
lazyRouteManifestoption to resolve lazy-route names" was created by @onurtemizkan but did not reference an issue. Therefore this issue was created for better visibility in external tools like Linear.This PR will resolve the core reason for the series of fixes / handling for automatic lazy-route resolution for a while.
Related: #18898, #18881, #18346, #18155, #18098, #17962, #17867, #17438, #17277
The core issue we have been trying to tackle is not having access to the complete route hierarchy when asynchronously loaded lazy routes are used. React Router provides a route manifest that we can use while matching parameterized transaction names with routes in all cases except this lazy-routes pattern.
This problem has been discussed on React Router:
While this has been addressed for Remix / React Router (Framework Mode), it's still not available in Library Mode. The manifest contains the lazily-loaded route, only when it's navigated to. While waiting for navigation, our transactions can be dropped for several reasons, such as user behaviour like switching tabs (
document.hiddenguard), hitting timeouts likeidleTimeout, and potentially other reasons. This results in incomplete transaction naming with leftover wildcards, which caused broken aggregation on the Sentry dashboard.The series of attempts to fix this while keeping automatic route discovery has been prone to race conditions and required special-case handling of each edge case scenario, also requiring a considerable amount of internal logic, affecting our readability and performance. At the end, all failed in giving completely robust and deterministic results on the customers' side.
This PR proposes a new option:
lazyRouteManifestspecifically for lazy routes. This will let us have initial information about the route hierarchy. So we can assign correct parameterized transaction names without needing to wait for navigated state.It's a static array of routes in parameterized format (needs to be maintained by the users on route hierarchy updates) like:
enableAsyncRouteHandlersis set totrue