feat(@angular/ssr): Add support for route matchers with fine-grained render mode control

This commit adds support for custom route matchers in Angular SSR, allowing fine-grained control over the `renderMode` (Server, Client) for individual routes, including those defined with matchers.

Routes with custom matchers are **not** supported during prerendering and must explicitly define a `renderMode` of either server or client.

The following configuration demonstrates how to use glob patterns (including recursive `**`) to define server-side rendering (SSR) or client-side rendering (CSR) for specific parts of the 'product' route and its child routes.

```typescript
// app.routes.ts
import { Routes } from '@angular/router';

export const routes: Routes = [
  {
    path: '',
    component: DummyComponent,
  },
  {
    path: 'product',
    component: DummyComponent,
    children: [
      {
        path: '',
        component: DummyComponent,
      },
      {
        path: 'list',
        component: DummyComponent,
      },
      {
        matcher: () => null, // Example custom matcher (always returns null)
        component: DummyComponent,
      },
    ],
  },
];
```

```typescript
// app.routes.server.ts
import { RenderMode, ServerRoute } from '@angular/ssr';

export const serverRoutes: ServerRoute[] = [
  { path: '**', renderMode: RenderMode.Client },
  { path: 'product', renderMode: RenderMode.Prerender },
  { path: 'product/list', renderMode: RenderMode.Prerender },
  { path: 'product/**/overview/details', renderMode: RenderMode.Server },
];
```

Closes #29284

Author: alan-agius4

packages/angular/ssr/src/routes/ng-routes.ts

@@ -110,6 +110,108 @@ interface AngularRouterConfigResult {
 
 type EntryPointToBrowserMapping = AngularAppManifest['entryPointToBrowserMapping'];
 
+/**
+ * Handles a single route within the route tree and yields metadata or errors.
+ *
+ * @param options - Configuration options for handling the route.
+ * @returns An async iterable iterator yielding `RouteTreeNodeMetadata` or an error object.
+ */
+async function* handleRoute(options: {
+  metadata: ServerConfigRouteTreeNodeMetadata;
+  currentRoutePath: string;
+  route: Route;
+  compiler: Compiler;
+  parentInjector: Injector;
+  serverConfigRouteTree?: RouteTree<ServerConfigRouteTreeAdditionalMetadata>;
+  invokeGetPrerenderParams: boolean;
+  includePrerenderFallbackRoutes: boolean;
+  entryPointToBrowserMapping?: EntryPointToBrowserMapping;
+}): AsyncIterableIterator<RouteTreeNodeMetadata | { error: string }> {
+  try {
+    const {
+      metadata,
+      currentRoutePath,
+      route,
+      compiler,
+      parentInjector,
+      serverConfigRouteTree,
+      entryPointToBrowserMapping,
+      invokeGetPrerenderParams,
+      includePrerenderFallbackRoutes,
+    } = options;
+
+    const { redirectTo, loadChildren, loadComponent, children, ɵentryName } = route;
+    if (ɵentryName && loadComponent) {
+      appendPreloadToMetadata(ɵentryName, entryPointToBrowserMapping, metadata, true);
+    }
+
+    if (metadata.renderMode === RenderMode.Prerender) {
+      yield* handleSSGRoute(
+        serverConfigRouteTree,
+        typeof redirectTo === 'string' ? redirectTo : undefined,
+        metadata,
+        parentInjector,
+        invokeGetPrerenderParams,
+        includePrerenderFallbackRoutes,
+      );
+    } else if (typeof redirectTo === 'string') {
+      if (metadata.status && !VALID_REDIRECT_RESPONSE_CODES.has(metadata.status)) {
+        yield {
+          error:
+            `The '${metadata.status}' status code is not a valid redirect response code. ` +
+            `Please use one of the following redirect response codes: ${[...VALID_REDIRECT_RESPONSE_CODES.values()].join(', ')}.`,
+        };
+      } else {
+        yield { ...metadata, redirectTo: resolveRedirectTo(metadata.route, redirectTo) };
+      }
+    } else {
+      yield metadata;
+    }
+
+    // Recursively process child routes
+    if (children?.length) {
+      yield* traverseRoutesConfig({
+        ...options,
+        routes: children,
+        parentRoute: currentRoutePath,
+        parentPreloads: metadata.preload,
+      });
+    }
+
+    // Load and process lazy-loaded child routes
+    if (loadChildren) {
+      if (ɵentryName) {
+        // When using `loadChildren`, the entire feature area (including multiple routes) is loaded.
+        // As a result, we do not want all dynamic-import dependencies to be preload, because it involves multiple dependencies
+        // across different child routes. In contrast, `loadComponent` only loads a single component, which allows
+        // for precise control over preloading, ensuring that the files preloaded are exactly those required for that specific route.
+        appendPreloadToMetadata(ɵentryName, entryPointToBrowserMapping, metadata, false);
+      }
+
+      const loadedChildRoutes = await loadChildrenHelper(
+        route,
+        compiler,
+        parentInjector,
+      ).toPromise();
+
+      if (loadedChildRoutes) {
+        const { routes: childRoutes, injector = parentInjector } = loadedChildRoutes;
+        yield* traverseRoutesConfig({
+          ...options,
+          routes: childRoutes,
+          parentInjector: injector,
+          parentRoute: currentRoutePath,
+          parentPreloads: metadata.preload,
+        });
+      }
+    }
+  } catch (error) {
+    yield {
+      error: `Error in handleRoute for '${options.currentRoutePath}': ${(error as Error).message}`,
+    };
+  }
+}
+
 /**
  * Traverses an array of route configurations to generate route tree node metadata.
  *
@@ -124,64 +226,79 @@ async function* traverseRoutesConfig(options: {
   compiler: Compiler;
   parentInjector: Injector;
   parentRoute: string;
-  serverConfigRouteTree: RouteTree<ServerConfigRouteTreeAdditionalMetadata> | undefined;
+  serverConfigRouteTree?: RouteTree<ServerConfigRouteTreeAdditionalMetadata>;
   invokeGetPrerenderParams: boolean;
   includePrerenderFallbackRoutes: boolean;
-  entryPointToBrowserMapping: EntryPointToBrowserMapping | undefined;
+  entryPointToBrowserMapping?: EntryPointToBrowserMapping;
   parentPreloads?: readonly string[];
 }): AsyncIterableIterator<RouteTreeNodeMetadata | { error: string }> {
-  const {
-    routes,
-    compiler,
-    parentInjector,
-    parentRoute,
-    serverConfigRouteTree,
-    entryPointToBrowserMapping,
-    parentPreloads,
-    invokeGetPrerenderParams,
-    includePrerenderFallbackRoutes,
-  } = options;
+  const { routes: routeConfigs, parentPreloads, parentRoute, serverConfigRouteTree } = options;
 
-  for (const route of routes) {
-    try {
-      const {
-        path = '',
-        matcher,
-        redirectTo,
-        loadChildren,
-        loadComponent,
-        children,
-        ɵentryName,
-      } = route;
-      const currentRoutePath = joinUrlParts(parentRoute, path);
-
-      // Get route metadata from the server config route tree, if available
-      let matchedMetaData: ServerConfigRouteTreeNodeMetadata | undefined;
-      if (serverConfigRouteTree) {
-        if (matcher) {
-          // Only issue this error when SSR routing is used.
-          yield {
-            error: `The route '${stripLeadingSlash(currentRoutePath)}' uses a route matcher that is not supported.`,
-          };
+  for (const route of routeConfigs) {
+    const { matcher, path = matcher ? '**' : '' } = route;
+    const currentRoutePath = joinUrlParts(parentRoute, path);
 
+    if (matcher && serverConfigRouteTree) {
+      let foundMatch = false;
+      for (const matchedMetaData of serverConfigRouteTree.traverse()) {
+        if (!matchedMetaData.route.startsWith(currentRoutePath)) {
           continue;
         }
 
-        matchedMetaData = serverConfigRouteTree.match(currentRoutePath);
-        if (!matchedMetaData) {
+        foundMatch = true;
+        matchedMetaData.presentInClientRouter = true;
+
+        if (matchedMetaData.renderMode === RenderMode.Prerender) {
           yield {
             error:
-              `The '${stripLeadingSlash(currentRoutePath)}' route does not match any route defined in the server routing configuration. ` +
-              'Please ensure this route is added to the server routing configuration.',
+              `The route '${stripLeadingSlash(currentRoutePath)}' is set for prerendering but has a defined matcher. ` +
+              `Routes with matchers cannot use prerendering. Please specify a different 'renderMode'.`,
           };
-
           continue;
         }
 
-        matchedMetaData.presentInClientRouter = true;
+        yield* handleRoute({
+          ...options,
+          currentRoutePath,
+          route,
+          metadata: {
+            ...matchedMetaData,
+            preload: parentPreloads,
+            route: matchedMetaData.route,
+            presentInClientRouter: undefined,
+          },
+        });
+      }
+
+      if (!foundMatch) {
+        yield {
+          error:
+            `The route '${stripLeadingSlash(currentRoutePath)}' has a defined matcher but does not ` +
+            'match any route in the server routing configuration. Please ensure this route is added to the server routing configuration.',
+        };
+      }
+
+      continue;
+    }
+
+    let matchedMetaData: ServerConfigRouteTreeNodeMetadata | undefined;
+    if (serverConfigRouteTree) {
+      matchedMetaData = serverConfigRouteTree.match(currentRoutePath);
+      if (!matchedMetaData) {
+        yield {
+          error:
+            `The '${stripLeadingSlash(currentRoutePath)}' route does not match any route defined in the server routing configuration. ` +
+            'Please ensure this route is added to the server routing configuration.',
+        };
+        continue;
       }
 
-      const metadata: ServerConfigRouteTreeNodeMetadata = {
+      matchedMetaData.presentInClientRouter = true;
+    }
+
+    yield* handleRoute({
+      ...options,
+      metadata: {
         renderMode: RenderMode.Prerender,
         ...matchedMetaData,
         preload: parentPreloads,
@@ -190,81 +307,10 @@ async function* traverseRoutesConfig(options: {
         // ['one', 'two', 'three'] -> 'one/two/three'
         route: path === '' ? addTrailingSlash(currentRoutePath) : currentRoutePath,
         presentInClientRouter: undefined,
-      };
-
-      if (ɵentryName && loadComponent) {
-        appendPreloadToMetadata(ɵentryName, entryPointToBrowserMapping, metadata, true);
-      }
-
-      if (metadata.renderMode === RenderMode.Prerender) {
-        // Handle SSG routes
-        yield* handleSSGRoute(
-          serverConfigRouteTree,
-          typeof redirectTo === 'string' ? redirectTo : undefined,
-          metadata,
-          parentInjector,
-          invokeGetPrerenderParams,
-          includePrerenderFallbackRoutes,
-        );
-      } else if (typeof redirectTo === 'string') {
-        // Handle redirects
-        if (metadata.status && !VALID_REDIRECT_RESPONSE_CODES.has(metadata.status)) {
-          yield {
-            error:
-              `The '${metadata.status}' status code is not a valid redirect response code. ` +
-              `Please use one of the following redirect response codes: ${[...VALID_REDIRECT_RESPONSE_CODES.values()].join(', ')}.`,
-          };
-
-          continue;
-        }
-
-        yield { ...metadata, redirectTo: resolveRedirectTo(metadata.route, redirectTo) };
-      } else {
-        yield metadata;
-      }
-
-      // Recursively process child routes
-      if (children?.length) {
-        yield* traverseRoutesConfig({
-          ...options,
-          routes: children,
-          parentRoute: currentRoutePath,
-          parentPreloads: metadata.preload,
-        });
-      }
-
-      // Load and process lazy-loaded child routes
-      if (loadChildren) {
-        if (ɵentryName) {
-          // When using `loadChildren`, the entire feature area (including multiple routes) is loaded.
-          // As a result, we do not want all dynamic-import dependencies to be preload, because it involves multiple dependencies
-          // across different child routes. In contrast, `loadComponent` only loads a single component, which allows
-          // for precise control over preloading, ensuring that the files preloaded are exactly those required for that specific route.
-          appendPreloadToMetadata(ɵentryName, entryPointToBrowserMapping, metadata, false);
-        }
-
-        const loadedChildRoutes = await loadChildrenHelper(
-          route,
-          compiler,
-          parentInjector,
-        ).toPromise();
-
-        if (loadedChildRoutes) {
-          const { routes: childRoutes, injector = parentInjector } = loadedChildRoutes;
-          yield* traverseRoutesConfig({
-            ...options,
-            routes: childRoutes,
-            parentInjector: injector,
-            parentRoute: currentRoutePath,
-            parentPreloads: metadata.preload,
-          });
-        }
-      }
-    } catch (error) {
-      yield {
-        error: `Error processing route '${stripLeadingSlash(route.path ?? '')}': ${(error as Error).message}`,
-      };
-    }
+      },
+      currentRoutePath,
+      route,
+    });
   }
 }
 

packages/angular/ssr/test/routes/ng-routes_spec.ts

@@ -167,6 +167,24 @@ describe('extractRoutesAndCreateRouteTree', () => {
         `The 'invalid' route does not match any route defined in the server routing configuration`,
       );
     });
+
+    it('should error when a route with a matcher when render mode is Prerender.', async () => {
+      setAngularAppTestingManifest(
+        [{ matcher: () => null, component: DummyComponent }],
+        [
+          {
+            path: '**',
+            renderMode: RenderMode.Prerender,
+          },
+        ],
+      );
+
+      const { errors } = await extractRoutesAndCreateRouteTree({ url });
+      expect(errors[0]).toContain(
+        `The route '**' is set for prerendering but has a defined matcher. ` +
+          `Routes with matchers cannot use prerendering. Please specify a different 'renderMode'.`,
+      );
+    });
   });
 
   describe('when `invokeGetPrerenderParams` is true', () => {
@@ -330,6 +348,54 @@ describe('extractRoutesAndCreateRouteTree', () => {
     });
   });
 
+  it('should extract routes with a route level matcher', async () => {
+    setAngularAppTestingManifest(
+      [
+        {
+          path: '',
+          component: DummyComponent,
+        },
+        {
+          path: 'product',
+          component: DummyComponent,
+          children: [
+            {
+              path: '',
+              component: DummyComponent,
+            },
+            {
+              matcher: () => null,
+              component: DummyComponent,
+            },
+            {
+              path: 'list',
+              component: DummyComponent,
+            },
+          ],
+        },
+      ],
+      [
+        { path: '**', renderMode: RenderMode.Client },
+        { path: 'product', renderMode: RenderMode.Client },
+        { path: 'product/*', renderMode: RenderMode.Client },
+        { path: 'product/**/overview/details', renderMode: RenderMode.Server },
+        { path: 'product/**/overview', renderMode: RenderMode.Server },
+        { path: 'product/**/overview/about', renderMode: RenderMode.Server },
+      ],
+    );
+
+    const { routeTree, errors } = await extractRoutesAndCreateRouteTree({ url });
+    expect(errors).toHaveSize(0);
+    expect(routeTree.toObject()).toEqual([
+      { route: '/', renderMode: RenderMode.Client },
+      { route: '/product', renderMode: RenderMode.Client },
+      { route: '/product/**/overview', renderMode: RenderMode.Server },
+      { route: '/product/**/overview/details', renderMode: RenderMode.Server },
+      { route: '/product/**/overview/about', renderMode: RenderMode.Server },
+      { route: '/product/list', renderMode: RenderMode.Client },
+    ]);
+  });
+
   it('should extract nested redirects that are not explicitly defined.', async () => {
     setAngularAppTestingManifest(
       [