Expose framework routes for server-side matchRoutes usage

[jdnichollsc]

What version of React Router are you using?

7.4.0 (framework mode)

---

What problem are you trying to solve?

When using React Router in framework mode with @react-router/express and route modules defined in app/routes.ts (via @react-router/dev/routes), there is no official way to access the resolved route objects on the server side to use with utilities like matchRoutes().

The use case is to dynamically extract route patterns (e.g., /users/:id) from the current URL on the server, to enhance tracing/logging systems (e.g., Datadog, OpenTelemetry) by setting tags like http.route during server-side request handling.

---

Describe the solution you'd like

I would like to have an official way to access the framework-generated routes in a format compatible with matchRoutes() on the server (e.g., a fully resolved array of AgnosticRouteObject[] or similar).

This could be:

• An official API like getResolvedRoutes() that exposes the same route structure that is internally passed to createStaticRouter().
• Or a utility to convert the RouteConfigEntry[] from @react-router/dev/routes into a matchRoutes()-compatible structure.

---

Why is this needed?

• Tools like Datadog and OpenTelemetry recommend reporting the matched route pattern (e.g., /dashboard/:id/settings) in traces and logs.
• In previous RemixJS setups, it was possible to manually extract route information from build.routes and process it.
• Without access to normalized routes on the server, we are forced to maintain separate manual route maps or JSON files to power matchRoutes() on the backend.

---

Describe alternatives you've considered

In older RemixJS-based setups, we used a manual workaround where we exported the route manifest and iterated over it on the server to match incoming requests:
https://github.com/brunojppb/react-router-datadog-express-tracing/blob/main/src/index.js#L114

However, this is less ergonomic now in React Router's framework mode since we already define routes in app/routes.ts using @react-router/dev/routes, but there is no official utility to resolve them into AgnosticRouteObject[].

---

Additional context

• It would help framework users (e.g., those using @react-router/express) to implement tracing/logging patterns without duplicating route definitions.
• Other SSR setups also need access to route metadata to improve error reporting, monitoring, and analytics on the server side.

Question

Is there a recommended approach or planned API to access resolved routes in framework mode for server-side use cases like this?

Thanks for your support! 🙌

[jdnichollsc]

Hey folks, wondering if we can use the matchServerRoutes function from our SSR apps, can you share any example please? <3

Thanks for your support!

[jdnichollsc]

Ok, I was able to do that here:

import { RouteConfigEntry } from "@react-router/dev/routes";
import { matchRoutes } from "react-router";
import routes from "@/routes";

// Extract the type from matchRoutes function parameter
type AgnosticRouteObject = Parameters<typeof matchRoutes>[0][0];

export function convertRouteConfig(entries: RouteConfigEntry[]): AgnosticRouteObject[] {
  return entries.map((entry) => {
    const routeObj: AgnosticRouteObject = {
      index: entry.index,
      path: entry.path,
      caseSensitive: entry.caseSensitive,
      id: entry.id,
    };
    if (entry.children) {
      routeObj.children = convertRouteConfig(entry.children);
    }
    return routeObj;
  });
}

// Example using Datadog with dd-trace and express adapter:
const matches = matchRoutes(convertRouteConfig(routes), url.pathname);
if (matches?.length) {
  span.setTag("http.route", matches?.at(-1)?.route.path);
}

But please let me know if there's another better recommendation! <3