@angular/ssr 20.0.0-next.1 → 20.0.0-next.3

package/index.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationRef } from '@angular/core';
+import { ApplicationRef } from '@angular/core';
 import { default as default_2 } from 'beasties';
 import { DefaultExport } from '@angular/router';
 import { EnvironmentProviders } from '@angular/core';
@@ -12,8 +12,6 @@ import { Type } from '@angular/core';
  *
  * @remarks This class should be instantiated once and used as a singleton across the server-side
  * application to ensure consistent handling of rendering requests and resource management.
- *
- * @developerPreview
  */
 export declare class AngularAppEngine {
     /**
@@ -392,7 +390,6 @@ declare class BeastiesBase extends default_2 {
  * const handler = toWebHandler(app);
  * export default createRequestHandler(handler);
  * ```
- * @developerPreview
  */
 export declare function createRequestHandler(handler: RequestHandlerFunction): RequestHandlerFunction;
 
@@ -507,7 +504,6 @@ declare interface PartialHTMLElement {
  * Defines the fallback strategies for Static Site Generation (SSG) routes when a pre-rendered path is not available.
  * This is particularly relevant for routes with parameterized URLs where some paths might not be pre-rendered at build time.
  * @see {@link ServerRoutePrerenderWithParams}
- * @developerPreview
  */
 export declare enum PrerenderFallback {
     /**
@@ -528,26 +524,44 @@ export declare enum PrerenderFallback {
 }
 
 /**
- * Sets up the necessary providers for configuring server routes.
- * This function accepts an array of server routes and optional configuration
- * options, returning an `EnvironmentProviders` object that encapsulates
- * the server routes and configuration settings.
+ * Configures server-side rendering for an Angular application.
  *
- * @param routes - An array of server routes to be provided.
- * @param features - (Optional) server routes features.
- * @returns An `EnvironmentProviders` instance with the server routes configuration.
+ * This function sets up the necessary providers for server-side rendering, including
+ * support for server routes and app shell. It combines features configured using
+ * `withRoutes` and `withAppShell` to provide a comprehensive server-side rendering setup.
  *
- * @see {@link ServerRoute}
- * @see {@link withAppShell}
- * @developerPreview
+ * @param features - Optional features to configure additional server rendering behaviors.
+ * @returns An `EnvironmentProviders` instance with the server-side rendering configuration.
+ *
+ * @example
+ * Basic example of how you can enable server-side rendering in your application
+ * when using the `bootstrapApplication` function:
+ *
+ * ```ts
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { provideServerRendering, withRoutes, withAppShell } from '@angular/ssr';
+ * import { AppComponent } from './app/app.component';
+ * import { SERVER_ROUTES } from './app/app.server.routes';
+ * import { AppShellComponent } from './app/app-shell.component';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *      provideServerRendering(
+ *         withRoutes(SERVER_ROUTES),
+ *         withAppShell(AppShellComponent)
+ *      )
+ *   ]
+ * });
+ * ```
+ * @see {@link withRoutes} configures server-side routing
+ * @see {@link withAppShell} configures the application shell
  */
-export declare function provideServerRouting(routes: ServerRoute[], ...features: ServerRoutesFeature<ServerRoutesFeatureKind>[]): EnvironmentProviders;
+export declare function provideServerRendering(...features: ServerRenderingFeature<ServerRenderingFeatureKind>[]): EnvironmentProviders;
 
 /**
  * Different rendering modes for server routes.
- * @see {@link provideServerRouting}
+ * @see {@link withRoutes}
  * @see {@link ServerRoute}
- * @developerPreview
  */
 export declare enum RenderMode {
     /** Server-Side Rendering (SSR) mode, where content is rendered on the server for each request. */
@@ -565,7 +579,6 @@ export declare enum RenderMode {
  * @param request - The incoming HTTP request object.
  * @returns A Promise resolving to a `Response` object, `null`, or directly a `Response`,
  * supporting both synchronous and asynchronous handling.
- * @developerPreview
  */
 export declare type RequestHandlerFunction = (request: Request) => Promise<Response | null> | null | Response;
 
@@ -752,17 +765,33 @@ declare interface ServerAsset {
     size: number;
 }
 
+/**
+ * Helper type to represent a server routes feature.
+ * @see {@link ServerRenderingFeatureKind}
+ */
+declare interface ServerRenderingFeature<FeatureKind extends ServerRenderingFeatureKind> {
+    ɵkind: FeatureKind;
+    ɵproviders: (Provider | EnvironmentProviders)[];
+}
+
+/**
+ * Identifies a particular kind of `ServerRenderingFeatureKind`.
+ * @see {@link ServerRenderingFeature}
+ */
+declare enum ServerRenderingFeatureKind {
+    AppShell = 0,
+    ServerRoutes = 1
+}
+
 /**
  * Server route configuration.
- * @see {@link provideServerRouting}
- * @developerPreview
+ * @see {@link withRoutes}
  */
 export declare type ServerRoute = ServerRouteClient | ServerRoutePrerender | ServerRoutePrerenderWithParams | ServerRouteServer;
 
 /**
  * A server route that uses Client-Side Rendering (CSR) mode.
  * @see {@link RenderMode}
- * @developerPreview
  */
 export declare interface ServerRouteClient extends ServerRouteCommon {
     /** Specifies that the route uses Client-Side Rendering (CSR) mode. */
@@ -771,7 +800,6 @@ export declare interface ServerRouteClient extends ServerRouteCommon {
 
 /**
  * Common interface for server routes, providing shared properties.
- * @developerPreview
  */
 export declare interface ServerRouteCommon {
     /** The path associated with this route. */
@@ -785,7 +813,6 @@ export declare interface ServerRouteCommon {
 /**
  * A server route that uses Static Site Generation (SSG) mode.
  * @see {@link RenderMode}
- * @developerPreview
  */
 export declare interface ServerRoutePrerender extends Omit<ServerRouteCommon, 'status'> {
     /** Specifies that the route uses Static Site Generation (SSG) mode. */
@@ -799,7 +826,6 @@ export declare interface ServerRoutePrerender extends Omit<ServerRouteCommon, 's
  * @see {@link RenderMode}
  * @see {@link ServerRoutePrerender}
  * @see {@link PrerenderFallback}
- * @developerPreview
  */
 export declare interface ServerRoutePrerenderWithParams extends Omit<ServerRoutePrerender, 'fallback'> {
     /**
@@ -843,7 +869,6 @@ export declare interface ServerRoutePrerenderWithParams extends Omit<ServerRoute
 /**
  * A server route that uses Server-Side Rendering (SSR) mode.
  * @see {@link RenderMode}
- * @developerPreview
  */
 export declare interface ServerRouteServer extends ServerRouteCommon {
     /** Specifies that the route uses Server-Side Rendering (SSR) mode. */
@@ -851,42 +876,87 @@ export declare interface ServerRouteServer extends ServerRouteCommon {
 }
 
 /**
- * Helper type to represent a server routes feature.
- * @see {@link ServerRoutesFeatureKind}
- * @developerPreview
- */
-declare interface ServerRoutesFeature<FeatureKind extends ServerRoutesFeatureKind> {
-    ɵkind: FeatureKind;
-    ɵproviders: Provider[];
-}
-
-/**
- * Identifies a particular kind of `ServerRoutesFeatureKind`.
- * @see {@link ServerRoutesFeature}
- * @developerPreview
+ * Configures the shell of the application.
+ *
+ * The app shell is a minimal, static HTML page that is served immediately, while the
+ * full Angular application loads in the background. This improves perceived performance
+ * by providing instant feedback to the user.
+ *
+ * This function configures the app shell route, which serves the provided component for
+ * requests that do not match any defined server routes.
+ *
+ * @param component - The Angular component to render for the app shell. Can be a direct
+ * component type or a dynamic import function.
+ * @returns A `ServerRenderingFeature` object configuring the app shell.
+ *
+ * @example
+ * ```ts
+ * import { provideServerRendering, withAppShell, withRoutes } from '@angular/ssr';
+ * import { AppShellComponent } from './app-shell.component';
+ *
+ * provideServerRendering(
+ *   withRoutes(serverRoutes),
+ *   withAppShell(AppShellComponent)
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { provideServerRendering, withAppShell, withRoutes } from '@angular/ssr';
+ *
+ * provideServerRendering(
+ *   withRoutes(serverRoutes),
+ *   withAppShell(() =>
+ *     import('./app-shell.component').then((m) => m.AppShellComponent)
+ *   )
+ * );
+ * ```
+ *
+ * @see {@link provideServerRendering}
+ * @see {@link https://angular.dev/ecosystem/service-workers/app-shell App shell pattern on Angular.dev}
  */
-declare enum ServerRoutesFeatureKind {
-    AppShell = 0
-}
+export declare function withAppShell(component: Type<unknown> | (() => Promise<Type<unknown> | DefaultExport<Type<unknown>>>)): ServerRenderingFeature<ServerRenderingFeatureKind.AppShell>;
 
 /**
- * Configures the app shell route with the provided component.
+ * Configures server-side routing for the application.
  *
- * The app shell serves as the main entry point for the application and is commonly used
- * to enable server-side rendering (SSR) of the application shell. It handles requests
- * that do not match any specific server route, providing a fallback mechanism and improving
- * perceived performance during navigation.
+ * This function registers an array of `ServerRoute` definitions, enabling server-side rendering
+ * for specific URL paths. These routes are used to pre-render content on the server, improving
+ * initial load performance and SEO.
  *
- * This configuration is particularly useful in applications leveraging Progressive Web App (PWA)
- * patterns, such as service workers, to deliver a seamless user experience.
+ * @param routes - An array of `ServerRoute` objects, each defining a server-rendered route.
+ * @returns A `ServerRenderingFeature` object configuring server-side routes.
  *
- * @param component The Angular component to render for the app shell route.
- * @returns A server routes feature configuration for the app shell.
+ * @example
+ * ```ts
+ * import { provideServerRendering, withRoutes, ServerRoute, RenderMode } from '@angular/ssr';
+ *
+ * const serverRoutes: ServerRoute[] = [
+ *   {
+ *     route: '', // This renders the "/" route on the client (CSR)
+ *     renderMode: RenderMode.Client,
+ *   },
+ *   {
+ *     route: 'about', // This page is static, so we prerender it (SSG)
+ *     renderMode: RenderMode.Prerender,
+ *   },
+ *   {
+ *     route: 'profile', // This page requires user-specific data, so we use SSR
+ *     renderMode: RenderMode.Server,
+ *   },
+ *   {
+ *     route: '**', // All other routes will be rendered on the server (SSR)
+ *     renderMode: RenderMode.Server,
+ *   },
+ * ];
  *
- * @see {@link provideServerRouting}
- * @see {@link https://angular.dev/ecosystem/service-workers/app-shell | App shell pattern on Angular.dev}
+ * provideServerRendering(withRoutes(serverRoutes));
+ * ```
+ *
+ * @see {@link provideServerRendering}
+ * @see {@link ServerRoute}
  */
-export declare function withAppShell(component: Type<unknown> | (() => Promise<Type<unknown> | DefaultExport<Type<unknown>>>)): ServerRoutesFeature<ServerRoutesFeatureKind.AppShell>;
+export declare function withRoutes(routes: ServerRoute[]): ServerRenderingFeature<ServerRenderingFeatureKind.ServerRoutes>;
 
 /**
  * Destroys the existing `AngularServerApp` instance, releasing associated resources and resetting the

package/node/index.d.ts

@@ -13,8 +13,6 @@ import { Type } from '@angular/core';
  *
  * @remarks This class should be instantiated once and used as a singleton across the server-side
  * application to ensure consistent handling of rendering requests and resource management.
- *
- * @developerPreview
  */
 export declare class AngularNodeAppEngine {
     private readonly angularAppEngine;
@@ -127,7 +125,6 @@ export declare interface CommonEngineRenderOptions {
  *   res.send('Hello from Fastify with Node Next Handler!');
  * }));
  * ```
- * @developerPreview
  */
 export declare function createNodeRequestHandler<T extends NodeRequestHandlerFunction>(handler: T): T;
 
@@ -140,7 +137,6 @@ export declare function createNodeRequestHandler<T extends NodeRequestHandlerFun
  *
  * @param nodeRequest - The Node.js request object (`IncomingMessage` or `Http2ServerRequest`) to convert.
  * @returns A Web Standard `Request` object.
- * @developerPreview
  */
 export declare function createWebRequestFromNodeRequest(nodeRequest: IncomingMessage | Http2ServerRequest): Request;
 
@@ -159,7 +155,6 @@ export declare function createWebRequestFromNodeRequest(nodeRequest: IncomingMes
  *
  * @param url The URL of the module to check. This should typically be `import.meta.url`.
  * @returns `true` if the provided URL represents the main entry point, otherwise `false`.
- * @developerPreview
  */
 export declare function isMainModule(url: string): boolean;
 
@@ -171,7 +166,6 @@ export declare function isMainModule(url: string): boolean;
  * @param next - A callback function that signals the completion of the middleware or forwards the error if provided.
  *
  * @returns A Promise that resolves to void or simply void. The handler can be asynchronous.
- * @developerPreview
  */
 export declare type NodeRequestHandlerFunction = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => Promise<void> | void;
 
@@ -185,7 +179,6 @@ export declare type NodeRequestHandlerFunction = (req: IncomingMessage, res: Ser
  * @param source - The web-standard `Response` object to stream from.
  * @param destination - The Node.js response object (`ServerResponse` or `Http2ServerResponse`) to stream into.
  * @returns A promise that resolves once the streaming operation is complete.
- * @developerPreview
  */
 export declare function writeResponseToNodeResponse(source: Response, destination: ServerResponse | Http2ServerResponse): Promise<void>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/ssr",
-  "version": "20.0.0-next.1",
+  "version": "20.0.0-next.3",
   "description": "Angular server side rendering utilities",
   "type": "module",
   "license": "MIT",
@@ -29,12 +29,12 @@
   },
   "devDependencies": {
     "@angular-devkit/schematics": "workspace:*",
-    "@angular/common": "20.0.0-next.2",
-    "@angular/compiler": "20.0.0-next.2",
-    "@angular/core": "20.0.0-next.2",
-    "@angular/platform-browser": "20.0.0-next.2",
-    "@angular/platform-server": "20.0.0-next.2",
-    "@angular/router": "20.0.0-next.2",
+    "@angular/common": "20.0.0-next.3",
+    "@angular/compiler": "20.0.0-next.3",
+    "@angular/core": "20.0.0-next.3",
+    "@angular/platform-browser": "20.0.0-next.3",
+    "@angular/platform-server": "20.0.0-next.3",
+    "@angular/router": "20.0.0-next.3",
     "@schematics/angular": "workspace:*"
   },
   "sideEffects": false,

package/schematics/ng-add/schema.d.ts

@@ -10,11 +10,6 @@ export type Schema = {
      * determine the project from the current directory.
      */
     project: string;
-    /**
-     * Configure the server application to use the Angular Server Routing API and App Engine
-     * APIs (currently in Developer Preview).
-     */
-    serverRouting?: boolean;
     /**
      * Skip the automatic installation of packages. You will need to manually install the
      * dependencies later.

package/schematics/ng-add/schema.json

@@ -16,10 +16,6 @@
       "description": "Skip the automatic installation of packages. You will need to manually install the dependencies later.",
       "type": "boolean",
       "default": false
-    },
-    "serverRouting": {
-      "description": "Configure the server application to use the Angular Server Routing API and App Engine APIs (currently in Developer Preview).",
-      "type": "boolean"
     }
   },
   "required": ["project"],