fix(@angular/ssr): enable serving of prerendered pages in the App Engine

This commit implements the capability for the App Engine to serve prerendered pages directly. Previously, we relied on frameworks like Express for this functionality, which resulted in inconsistent redirects for directories where in some cases a trailing slash was added to the route.

**Note:** This change applies only when using the new SSR APIs. When using the `CommonEngine`, a 3rd party static serve middleware is still required.

Author: alan-agius4

goldens/public-api/angular/ssr/index.api.md

@@ -8,8 +8,7 @@ import { EnvironmentProviders } from '@angular/core';
 
 // @public
 export class AngularAppEngine {
-    getPrerenderHeaders(request: Request): ReadonlyMap<string, string>;
-    render(request: Request, requestContext?: unknown): Promise<Response | null>;
+    handle(request: Request, requestContext?: unknown): Promise<Response | null>;
     static ɵhooks: Hooks;
 }
 

goldens/public-api/angular/ssr/node/index.api.md

@@ -12,8 +12,7 @@ import { Type } from '@angular/core';
 
 // @public
 export class AngularNodeAppEngine {
-    getPrerenderHeaders(request: IncomingMessage): ReadonlyMap<string, string>;
-    render(request: IncomingMessage, requestContext?: unknown): Promise<Response | null>;
+    handle(request: IncomingMessage, requestContext?: unknown): Promise<Response | null>;
 }
 
 // @public

packages/angular/build/src/builders/application/execute-post-bundle.ts

@@ -175,7 +175,8 @@ export async function executePostBundleSteps(
       switch (metadata.renderMode) {
         case RouteRenderMode.Prerender:
         case /* Legacy building mode */ undefined: {
-          if (!metadata.redirectTo || outputMode === OutputMode.Static) {
+          if (!metadata.redirectTo) {
+            serializableRouteTreeNodeForManifest.push(metadata);
             prerenderedRoutes[metadata.route] = { headers: metadata.headers };
           }
           break;

packages/angular/build/src/tools/vite/middlewares/ssr-middleware.ts

@@ -59,7 +59,7 @@ export function createAngularSsrInternalMiddleware(
       const webReq = new Request(createWebRequestFromNodeRequest(req), {
         signal: AbortSignal.timeout(30_000),
       });
-      const webRes = await angularServerApp.render(webReq);
+      const webRes = await angularServerApp.handle(webReq);
       if (!webRes) {
         return next();
       }

packages/angular/build/src/utils/server-rendering/manifest.ts

@@ -6,9 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import { extname } from 'node:path';
 import {
-  INDEX_HTML_CSR,
-  INDEX_HTML_SERVER,
   NormalizedApplicationBuildOptions,
   getLocaleBaseHref,
 } from '../../builders/application/options';
@@ -135,11 +134,8 @@ export function generateAngularServerAppManifest(
 ): string {
   const serverAssetsContent: string[] = [];
   for (const file of [...additionalHtmlOutputFiles.values(), ...outputFiles]) {
-    if (
-      file.path === INDEX_HTML_SERVER ||
-      file.path === INDEX_HTML_CSR ||
-      (inlineCriticalCss && file.path.endsWith('.css'))
-    ) {
+    const extension = extname(file.path);
+    if (extension === '.html' || (inlineCriticalCss && extension === '.css')) {
       serverAssetsContent.push(`['${file.path}', async () => \`${escapeUnsafeChars(file.text)}\`]`);
     }
   }

packages/angular/ssr/node/src/app-engine.ts

@@ -24,49 +24,22 @@ export class AngularNodeAppEngine {
   private readonly angularAppEngine = new AngularAppEngine();
 
   /**
-   * Renders an HTTP response based on the incoming request using the Angular server application.
+   * Handles an incoming HTTP request by serving prerendered content or performing server-side rendering.
    *
-   * The method processes the incoming request, determines the appropriate route, and prepares the
-   * rendering context to generate a response. If the request URL corresponds to a static file (excluding `/index.html`),
-   * the method returns `null`.
+   * This method prioritizes serving a prerendered version of the requested page. If no prerendered content is available,
+   * it falls back on server-side rendering to dynamically generate the page. The function returns a promise that resolves
+   * to the appropriate HTTP response.
    *
-   * Example: A request to `https://www.example.com/page/index.html` will render the Angular route
-   * associated with `https://www.example.com/page`.
+   * @param request - The HTTP request to handle.
+   * @param requestContext - Optional context for rendering, such as metadata associated with the request.
+   * @returns A promise that resolves to the resulting HTTP response object, or `null` if no matching Angular route is found.
    *
-   * @param request - The incoming HTTP request object to be rendered.
-   * @param requestContext - Optional additional context for the request, such as metadata or custom settings.
-   * @returns A promise that resolves to a `Response` object, or `null` if the request URL is for a static file
-   * (e.g., `./logo.png`) rather than an application route.
+   * @note A request to `https://www.example.com/page/index.html` will serve or render the Angular route
+   * corresponding to `https://www.example.com/page`.
    */
-  render(request: IncomingMessage, requestContext?: unknown): Promise<Response | null> {
-    return this.angularAppEngine.render(createWebRequestFromNodeRequest(request), requestContext);
-  }
+  async handle(request: IncomingMessage, requestContext?: unknown): Promise<Response | null> {
+    const webRequest = createWebRequestFromNodeRequest(request);
 
-  /**
-   * Retrieves HTTP headers for a request associated with statically generated (SSG) pages,
-   * based on the URL pathname.
-   *
-   * @param request - The incoming request object.
-   * @returns A `Map` containing the HTTP headers as key-value pairs.
-   * @note This function should be used exclusively for retrieving headers of SSG pages.
-   * @example
-   * ```typescript
-   * const angularAppEngine = new AngularNodeAppEngine();
-   *
-   * app.use(express.static('dist/browser', {
-   *   setHeaders: (res, path) => {
-   *     // Retrieve headers for the current request
-   *     const headers = angularAppEngine.getPrerenderHeaders(res.req);
-   *
-   *     // Apply the retrieved headers to the response
-   *     for (const [key, value] of headers) {
-   *       res.setHeader(key, value);
-   *     }
-   *   }
-     }));
-  * ```
-  */
-  getPrerenderHeaders(request: IncomingMessage): ReadonlyMap<string, string> {
-    return this.angularAppEngine.getPrerenderHeaders(createWebRequestFromNodeRequest(request));
+    return this.angularAppEngine.handle(webRequest, requestContext);
   }
 }

packages/angular/ssr/src/app-engine.ts

@@ -53,21 +53,37 @@ export class AngularAppEngine {
   private readonly entryPointsCache = new Map<string, Promise<EntryPointExports>>();
 
   /**
-   * Renders a response for the given HTTP request using the server application.
+   * Handles an incoming HTTP request by serving prerendered content or performing server-side rendering.
    *
-   * This method processes the request, determines the appropriate route and rendering context,
-   * and returns an HTTP response.
+   * This method prioritizes serving a prerendered version of the requested page. If no prerendered content is available,
+   * it falls back on server-side rendering to dynamically generate the page. The function returns a promise that resolves
+   * to the appropriate HTTP response.
    *
-   * If the request URL appears to be for a file (excluding `/index.html`), the method returns `null`.
-   * A request to `https://www.example.com/page/index.html` will render the Angular route
+   * @param request - The HTTP request to handle.
+   * @param requestContext - Optional context for rendering, such as metadata associated with the request.
+   * @returns A promise that resolves to the resulting HTTP response object, or `null` if no matching Angular route is found.
+   *
+   * @note A request to `https://www.example.com/page/index.html` will serve or render the Angular route
    * corresponding to `https://www.example.com/page`.
+   */
+  async handle(request: Request, requestContext?: unknown): Promise<Response | null> {
+    const serverApp = await this.getAngularServerAppForRequest(request);
+
+    return serverApp ? serverApp.handle(request, requestContext) : null;
+  }
+
+  /**
+   * Retrieves the Angular server application instance for a given request.
    *
-   * @param request - The incoming HTTP request object to be rendered.
-   * @param requestContext - Optional additional context for the request, such as metadata.
-   * @returns A promise that resolves to a Response object, or `null` if the request URL represents a file (e.g., `./logo.png`)
-   * rather than an application route.
+   * This method checks if the request URL corresponds to an Angular application entry point.
+   * If so, it initializes or retrieves an instance of the Angular server application for that entry point.
+   * Requests that resemble file requests (except for `/index.html`) are skipped.
+   *
+   * @param request - The incoming HTTP request object.
+   * @returns A promise that resolves to an `AngularServerApp` instance if a valid entry point is found,
+   * or `null` if no entry point matches the request URL.
    */
-  async render(request: Request, requestContext?: unknown): Promise<Response | null> {
+  private async getAngularServerAppForRequest(request: Request): Promise<AngularServerApp | null> {
     // Skip if the request looks like a file but not `/index.html`.
     const url = new URL(request.url);
     const entryPoint = await this.getEntryPointExportsForUrl(url);
@@ -82,26 +98,7 @@ export class AngularAppEngine {
     const serverApp = getOrCreateAngularServerApp() as AngularServerApp;
     serverApp.hooks = this.hooks;
 
-    return serverApp.render(request, requestContext);
-  }
-
-  /**
-   * Retrieves HTTP headers for a request associated with statically generated (SSG) pages,
-   * based on the URL pathname.
-   *
-   * @param request - The incoming request object.
-   * @returns A `Map` containing the HTTP headers as key-value pairs.
-   * @note This function should be used exclusively for retrieving headers of SSG pages.
-   */
-  getPrerenderHeaders(request: Request): ReadonlyMap<string, string> {
-    if (this.manifest.staticPathsHeaders.size === 0) {
-      return new Map();
-    }
-
-    const { pathname } = stripIndexHtmlFromURL(new URL(request.url));
-    const headers = this.manifest.staticPathsHeaders.get(stripTrailingSlash(pathname));
-
-    return new Map(headers);
+    return serverApp;
   }
 
   /**