refactor(@angular/ssr): remove RenderMode.AppShell in favor of new configuration option

This commit removes the `RenderMode.AppShell` option. Instead, a new configuration parameter, `{ appShellRoute: 'shell' }`, is introduced to the `provideServerRoutesConfig` method.

```ts
provideServerRoutesConfig(serverRoutes, { appShellRoute: 'shell' })
```

Author: alan-agius4

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

@@ -24,11 +24,10 @@ export enum PrerenderFallback {
 }
 
 // @public
-export function provideServerRoutesConfig(routes: ServerRoute[]): EnvironmentProviders;
+export function provideServerRoutesConfig(routes: ServerRoute[], options?: ServerRoutesConfigOptions): EnvironmentProviders;
 
 // @public
 export enum RenderMode {
-    AppShell = 0,
     Client = 2,
     Prerender = 3,
     Server = 1
@@ -38,12 +37,7 @@ export enum RenderMode {
 export type RequestHandlerFunction = (request: Request) => Promise<Response | null> | null | Response;
 
 // @public
-export type ServerRoute = ServerRouteAppShell | ServerRouteClient | ServerRoutePrerender | ServerRoutePrerenderWithParams | ServerRouteServer;
-
-// @public
-export interface ServerRouteAppShell extends Omit<ServerRouteCommon, 'headers' | 'status'> {
-    renderMode: RenderMode.AppShell;
-}
+export type ServerRoute = ServerRouteClient | ServerRoutePrerender | ServerRoutePrerenderWithParams | ServerRouteServer;
 
 // @public
 export interface ServerRouteClient extends ServerRouteCommon {
@@ -69,6 +63,11 @@ export interface ServerRoutePrerenderWithParams extends Omit<ServerRoutePrerende
     getPrerenderParams: () => Promise<Record<string, string>[]>;
 }
 
+// @public
+export interface ServerRoutesConfigOptions {
+    appShellRoute?: string;
+}
+
 // @public
 export interface ServerRouteServer extends ServerRouteCommon {
     renderMode: RenderMode.Server;

packages/angular/build/src/builders/application/tests/options/app-shell_spec.ts

@@ -117,8 +117,6 @@ describeBuilder(buildApplication, APPLICATION_BUILDER_INFO, (harness) => {
       harness.expectFile('dist/browser/main.js').toExist();
       const indexFileContent = harness.expectFile('dist/browser/index.html').content;
       indexFileContent.toContain('app-shell works!');
-      // TODO(alanagius): enable once integration of routes in complete.
-      // indexFileContent.toContain('ng-server-context="app-shell"');
     });
 
     it('critical CSS is inlined', async () => {

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

@@ -23,6 +23,7 @@ export type WritableSerializableRouteTreeNode = Writeable<SerializableRouteTreeN
 
 export interface RoutersExtractorWorkerResult {
   serializedRouteTree: SerializableRouteTreeNode;
+  appShellRoute?: string;
   errors: string[];
 }
 
@@ -33,7 +34,6 @@ export interface RoutersExtractorWorkerResult {
  * It maps `RenderMode` enum values to their corresponding numeric identifiers.
  */
 export const RouteRenderMode: Record<keyof typeof RenderMode, RenderMode> = {
-  AppShell: 0,
   Server: 1,
   Client: 2,
   Prerender: 3,

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

@@ -97,24 +97,26 @@ export async function prerenderPages(
   }
 
   // Get routes to prerender
-  const { errors: extractionErrors, serializedRouteTree: serializableRouteTreeNode } =
-    await getAllRoutes(
-      workspaceRoot,
-      baseHref,
-      outputFilesForWorker,
-      assetsReversed,
-      appShellOptions,
-      prerenderOptions,
-      sourcemap,
-      outputMode,
-    ).catch((err) => {
-      return {
-        errors: [
-          `An error occurred while extracting routes.\n\n${err.stack ?? err.message ?? err}`,
-        ],
-        serializedRouteTree: [],
-      };
-    });
+  const {
+    errors: extractionErrors,
+    serializedRouteTree: serializableRouteTreeNode,
+    appShellRoute,
+  } = await getAllRoutes(
+    workspaceRoot,
+    baseHref,
+    outputFilesForWorker,
+    assetsReversed,
+    appShellOptions,
+    prerenderOptions,
+    sourcemap,
+    outputMode,
+  ).catch((err) => {
+    return {
+      errors: [`An error occurred while extracting routes.\n\n${err.stack ?? err.message ?? err}`],
+      serializedRouteTree: [],
+      appShellRoute: undefined,
+    };
+  });
 
   errors.push(...extractionErrors);
 
@@ -133,7 +135,6 @@ export async function prerenderPages(
     switch (metadata.renderMode) {
       case undefined: /* Legacy building mode */
       case RouteRenderMode.Prerender:
-      case RouteRenderMode.AppShell:
         serializableRouteTreeNodeForPrerender.push(metadata);
         break;
       case RouteRenderMode.Server:
@@ -166,6 +167,7 @@ export async function prerenderPages(
     assetsReversed,
     appShellOptions,
     outputMode,
+    appShellRoute ?? appShellOptions?.route,
   );
 
   errors.push(...renderingErrors);
@@ -188,6 +190,7 @@ async function renderPages(
   assetFilesForWorker: Record<string, string>,
   appShellOptions: AppShellOptions | undefined,
   outputMode: OutputMode | undefined,
+  appShellRoute: string | undefined,
 ): Promise<{
   output: PrerenderOutput;
   errors: string[];
@@ -215,7 +218,7 @@ async function renderPages(
 
   try {
     const renderingPromises: Promise<void>[] = [];
-    const appShellRoute = appShellOptions && addLeadingSlash(appShellOptions.route);
+    const appShellRouteWithLeadingSlash = appShellRoute && addLeadingSlash(appShellRoute);
     const baseHrefWithLeadingSlash = addLeadingSlash(baseHref);
 
     for (const { route, redirectTo, renderMode } of serializableRouteTreeNode) {
@@ -232,16 +235,14 @@ async function renderPages(
         continue;
       }
 
-      const isAppShellRoute =
-        renderMode === RouteRenderMode.AppShell ||
-        // Legacy handling
-        (renderMode === undefined && appShellRoute === routeWithoutBaseHref);
-
-      const render: Promise<string | null> = renderWorker.run({ url: route, isAppShellRoute });
+      const render: Promise<string | null> = renderWorker.run({ url: route });
       const renderResult: Promise<void> = render
         .then((content) => {
           if (content !== null) {
-            output[outPath] = { content, appShellRoute: isAppShellRoute };
+            output[outPath] = {
+              content,
+              appShellRoute: appShellRouteWithLeadingSlash === routeWithoutBaseHref,
+            };
           }
         })
         .catch((err) => {
@@ -274,14 +275,21 @@ async function getAllRoutes(
   prerenderOptions: PrerenderOptions | undefined,
   sourcemap: boolean,
   outputMode: OutputMode | undefined,
-): Promise<{ serializedRouteTree: SerializableRouteTreeNode; errors: string[] }> {
+): Promise<{
+  serializedRouteTree: SerializableRouteTreeNode;
+  appShellRoute?: string;
+  errors: string[];
+}> {
   const { routesFile, discoverRoutes } = prerenderOptions ?? {};
   const routes: WritableSerializableRouteTreeNode = [];
+  let appShellRoute: string | undefined;
 
   if (appShellOptions) {
+    appShellRoute = urlJoin(baseHref, appShellOptions.route);
+
     routes.push({
-      renderMode: RouteRenderMode.AppShell,
-      route: urlJoin(baseHref, appShellOptions.route),
+      renderMode: RouteRenderMode.Prerender,
+      route: appShellRoute,
     });
   }
 
@@ -296,7 +304,7 @@ async function getAllRoutes(
   }
 
   if (!discoverRoutes) {
-    return { errors: [], serializedRouteTree: routes };
+    return { errors: [], appShellRoute, serializedRouteTree: routes };
   }
 
   const workerExecArgv = [IMPORT_EXEC_ARGV];
@@ -319,12 +327,11 @@ async function getAllRoutes(
   });
 
   try {
-    const { serializedRouteTree, errors }: RoutersExtractorWorkerResult = await renderWorker.run(
-      {},
-    );
+    const { serializedRouteTree, appShellRoute, errors }: RoutersExtractorWorkerResult =
+      await renderWorker.run({});
 
     if (!routes.length) {
-      return { errors, serializedRouteTree };
+      return { errors, appShellRoute, serializedRouteTree };
     }
 
     // Merge the routing trees

packages/angular/build/src/utils/server-rendering/routes-extractor-worker.ts

@@ -33,7 +33,7 @@ async function extractRoutes(): Promise<RoutersExtractorWorkerResult> {
   const { ɵextractRoutesAndCreateRouteTree: extractRoutesAndCreateRouteTree } =
     await loadEsmModuleFromMemory('./main.server.mjs');
 
-  const { routeTree, errors } = await extractRoutesAndCreateRouteTree(
+  const { routeTree, appShellRoute, errors } = await extractRoutesAndCreateRouteTree(
     serverURL,
     undefined /** manifest */,
     true /** invokeGetPrerenderParams */,
@@ -42,6 +42,7 @@ async function extractRoutes(): Promise<RoutersExtractorWorkerResult> {
 
   return {
     errors,
+    appShellRoute,
     serializedRouteTree: routeTree.toObject(),
   };
 }

packages/angular/ssr/public_api.ts

@@ -6,6 +6,8 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import { provideZoneChangeDetection } from '@angular/core';
+
 export * from './private_export';
 
 export { AngularAppEngine } from './src/app-engine';
@@ -14,12 +16,14 @@ export { createRequestHandler, type RequestHandlerFunction } from './src/handler
 export {
   type PrerenderFallback,
   type ServerRoute,
+  type ServerRoutesConfigOptions,
   provideServerRoutesConfig,
   RenderMode,
-  type ServerRouteAppShell,
   type ServerRouteClient,
   type ServerRoutePrerender,
   type ServerRoutePrerenderWithParams,
   type ServerRouteServer,
   type ServerRouteCommon,
 } from './src/routes/route-config';
+
+provideZoneChangeDetection();

packages/angular/ssr/src/app.ts

@@ -35,13 +35,11 @@ const MAX_INLINE_CSS_CACHE_ENTRIES = 50;
  *
  * - `RenderMode.Prerender` maps to `'ssg'` (Static Site Generation).
  * - `RenderMode.Server` maps to `'ssr'` (Server-Side Rendering).
- * - `RenderMode.AppShell` maps to `'app-shell'` (pre-rendered application shell).
  * - `RenderMode.Client` maps to an empty string `''` (Client-Side Rendering, no server context needed).
  */
 const SERVER_CONTEXT_VALUE: Record<RenderMode, string> = {
   [RenderMode.Prerender]: 'ssg',
   [RenderMode.Server]: 'ssr',
-  [RenderMode.AppShell]: 'app-shell',
   [RenderMode.Client]: '',
 };
 
@@ -240,10 +238,7 @@ export class AngularServerApp {
     }
 
     const { renderMode, headers } = matchedRoute;
-    if (
-      !this.allowStaticRouteRender &&
-      (renderMode === RenderMode.Prerender || renderMode === RenderMode.AppShell)
-    ) {
+    if (!this.allowStaticRouteRender && renderMode === RenderMode.Prerender) {
       return null;
     }
 

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

@@ -22,7 +22,13 @@ import { Console } from '../console';
 import { AngularAppManifest, getAngularAppManifest } from '../manifest';
 import { AngularBootstrap, isNgModule } from '../utils/ng';
 import { joinUrlParts, stripLeadingSlash } from '../utils/url';
-import { PrerenderFallback, RenderMode, SERVER_ROUTES_CONFIG, ServerRoute } from './route-config';
+import {
+  PrerenderFallback,
+  RenderMode,
+  SERVER_ROUTES_CONFIG,
+  ServerRoute,
+  ServerRoutesConfig,
+} from './route-config';
 import { RouteTree, RouteTreeNodeMetadata } from './route-tree';
 
 /**
@@ -80,6 +86,11 @@ interface AngularRouterConfigResult {
    * A list of errors encountered during the route extraction process.
    */
   errors: string[];
+
+  /**
+   * The specified route for the app-shell, if configured.
+   */
+  appShellRoute?: string;
 }
 
 /**
@@ -317,22 +328,30 @@ function resolveRedirectTo(routePath: string, redirectTo: string): string {
 /**
  * Builds a server configuration route tree from the given server routes configuration.
  *
- * @param serverRoutesConfig - The array of server routes to be used for configuration.
+ * @param serverRoutesConfig - The server routes to be used for configuration.
 
  * @returns An object containing:
  * - `serverConfigRouteTree`: A populated `RouteTree` instance, which organizes the server routes
  *   along with their additional metadata.
  * - `errors`: An array of strings that list any errors encountered during the route tree construction
  *   process, such as invalid paths.
  */
-function buildServerConfigRouteTree(serverRoutesConfig: ServerRoute[]): {
+function buildServerConfigRouteTree({ routes, appShellRoute }: ServerRoutesConfig): {
   errors: string[];
   serverConfigRouteTree: RouteTree<ServerConfigRouteTreeAdditionalMetadata>;
 } {
+  const serverRoutes: ServerRoute[] = [...routes];
+  if (appShellRoute !== undefined) {
+    serverRoutes.unshift({
+      path: appShellRoute,
+      renderMode: RenderMode.Prerender,
+    });
+  }
+
   const serverConfigRouteTree = new RouteTree<ServerConfigRouteTreeAdditionalMetadata>();
   const errors: string[] = [];
 
-  for (const { path, ...metadata } of serverRoutesConfig) {
+  for (const { path, ...metadata } of serverRoutes) {
     if (path[0] === '/') {
       errors.push(`Invalid '${path}' route configuration: the path cannot start with a slash.`);
 
@@ -442,18 +461,6 @@ export async function getRoutesFromAngularRouterConfig(
         if ('error' in result) {
           errors.push(result.error);
         } else {
-          if (result.renderMode === RenderMode.AppShell) {
-            if (seenAppShellRoute !== undefined) {
-              errors.push(
-                `Error: Both '${seenAppShellRoute}' and '${stripLeadingSlash(result.route)}' routes have ` +
-                  `their 'renderMode' set to 'AppShell'. AppShell renderMode should only be assigned to one route. ` +
-                  `Please review your route configurations to ensure that only one route is set to 'RenderMode.AppShell'.`,
-              );
-            }
-
-            seenAppShellRoute = stripLeadingSlash(result.route);
-          }
-
           routesResults.push(result);
         }
       }
@@ -485,6 +492,7 @@ export async function getRoutesFromAngularRouterConfig(
       baseHref,
       routes: routesResults,
       errors,
+      appShellRoute: serverRoutesConfig?.appShellRoute,
     };
   } finally {
     platformRef.destroy();
@@ -508,18 +516,19 @@ export async function getRoutesFromAngularRouterConfig(
  *
  * @returns A promise that resolves to an object containing:
  *  - `routeTree`: A populated `RouteTree` containing all extracted routes from the Angular application.
+ *  - `appShellRoute`: The specified route for the app-shell, if configured.
  *  - `errors`: An array of strings representing any errors encountered during the route extraction process.
  */
 export async function extractRoutesAndCreateRouteTree(
   url: URL,
   manifest: AngularAppManifest = getAngularAppManifest(),
   invokeGetPrerenderParams = false,
   includePrerenderFallbackRoutes = true,
-): Promise<{ routeTree: RouteTree; errors: string[] }> {
+): Promise<{ routeTree: RouteTree; appShellRoute?: string; errors: string[] }> {
   const routeTree = new RouteTree();
   const document = await new ServerAssets(manifest).getIndexServerHtml().text();
   const bootstrap = await manifest.bootstrap();
-  const { baseHref, routes, errors } = await getRoutesFromAngularRouterConfig(
+  const { baseHref, appShellRoute, routes, errors } = await getRoutesFromAngularRouterConfig(
     bootstrap,
     document,
     url,
@@ -537,6 +546,7 @@ export async function extractRoutesAndCreateRouteTree(
   }
 
   return {
+    appShellRoute,
     routeTree,
     errors,
   };