@angular/ssr - npm Package Compare versions

Comparing version 19.0.0-next.5 to 19.0.0-next.6

index.d.ts

 import type { ApplicationRef } from '@angular/core';
 import { default as default_2 } from 'critters';
+import { EnvironmentProviders } from '@angular/core';
 import type { Type } from '@angular/core';
@@ -64,3 +65,3 @@
      */
-    getHeaders(request: Request): ReadonlyMap<string, string>;
+    getPrerenderHeaders(request: Request): ReadonlyMap<string, string>;
 }
@@ -144,20 +145,16 @@
     /**
-     * An array of `RouteResult` objects representing the application's routes.
+     * An array of `RouteTreeNodeMetadata` objects representing the application's routes.
      *
-     * Each `RouteResult` contains details about a specific route, such as its path and any
+     * Each `RouteTreeNodeMetadata` contains details about a specific route, such as its path and any
      * associated redirection targets. This array is asynchronously generated and
      * provides information on how routes are structured and resolved.
+     */
+    routes: RouteTreeNodeMetadata[];
+    /**
+     * Optional configuration for server routes.
      *
-     * Example:
-     * ```typescript
-     * const result: AngularRouterConfigResult = {
-     *   baseHref: '/app/',
-     *   routes: [
-     *     { route: '/home', redirectTo: '/welcome' },
-     *     { route: '/about' },
-     *   ],
-     * };
-     * ```
+     * This property allows you to specify an array of server routes for configuration.
+     * If not provided, the default configuration or behavior will be used.
      */
-    routes: RouteResult[];
+    serverRoutesConfig?: ServerRoute[] | null;
 }
@@ -203,8 +200,17 @@
      * @param requestContext - Optional additional context for rendering, such as request metadata.
-     * @param serverContext - The rendering context.
      *
      * @returns A promise that resolves to the HTTP response object resulting from the rendering, or null if no match is found.
      */
-    render(request: Request, requestContext?: unknown, serverContext?: ɵServerRenderContext): Promise<Response | null>;
+    render(request: Request, requestContext?: unknown): Promise<Response | null>;
     /**
+     * Renders a page based on the provided URL via server-side rendering and returns the corresponding HTTP response.
+     * The rendering process can be interrupted by an abort signal, where the first resolved promise (either from the abort
+     * or the render process) will dictate the outcome.
+     *
+     * @param url - The full URL to be processed and rendered by the server.
+     * @param signal - (Optional) An `AbortSignal` object that allows for the cancellation of the rendering process.
+     * @returns A promise that resolves to the generated HTTP response object, or `null` if no matching route is found.
+     */
+    renderStatic(url: URL, signal?: AbortSignal): Promise<Response | null>;
+    /**
      * Creates a promise that rejects when the request is aborted.
@@ -221,4 +227,4 @@ *
      * @param request - The incoming HTTP request to be processed.
+     * @param isSsrMode - A boolean indicating whether the rendering is performed in server-side rendering (SSR) mode.
      * @param requestContext - Optional additional context for rendering, such as request metadata.
-     * @param serverContext - The rendering context. Defaults to server-side rendering (SSR).
      *
@@ -342,27 +348,57 @@ * @returns A promise that resolves to the rendered response, or null if no matching route is found.
 /**
- * Represents the result of processing a route.
+ * 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.
+ *
+ * @developerPreview
  */
-declare interface RouteResult {
+export declare enum PrerenderFallback {
     /**
-     * The resolved path of the route.
-     *
-     * This string represents the complete URL path for the route after it has been
-     * resolved, including any parent routes or path segments that have been joined.
+     * Fallback to Server-Side Rendering (SSR) if the pre-rendered path is not available.
+     * This strategy dynamically generates the page on the server at request time.
      */
-    route: string;
+    Server = 0,
     /**
-     * The target path for route redirection, if applicable.
-     *
-     * If this route has a `redirectTo` property in the configuration, this field will
-     * contain the full resolved URL path that the route should redirect to.
+     * Fallback to Client-Side Rendering (CSR) if the pre-rendered path is not available.
+     * This strategy allows the page to be rendered on the client side.
      */
-    redirectTo?: string;
+    Client = 1,
+    /**
+     * No fallback; if the path is not pre-rendered, the server will not handle the request.
+     * This means the application will not provide any response for paths that are not pre-rendered.
+     */
+    None = 2
 }
 
 /**
+ * Configures the necessary providers for server routes configuration.
+ *
+ * @param routes - An array of server routes to be provided.
+ * @returns An `EnvironmentProviders` object that contains the server routes configuration.
+ * @developerPreview
+ */
+export declare function provideServerRoutesConfig(routes: ServerRoute[]): EnvironmentProviders;
+
+/**
+ * Different rendering modes for server routes.
+ * @developerPreview
+ */
+export declare enum RenderMode {
+    /** AppShell rendering mode, typically used for pre-rendered shells of the application. */
+    AppShell = 0,
+    /** Server-Side Rendering (SSR) mode, where content is rendered on the server for each request. */
+    Server = 1,
+    /** Client-Side Rendering (CSR) mode, where content is rendered on the client side in the browser. */
+    Client = 2,
+    /** Static Site Generation (SSG) mode, where content is pre-rendered at build time and served as static files. */
+    Prerender = 3
+}
+
+/**
  * A route tree implementation that supports efficient route matching, including support for wildcard routes.
  * This structure is useful for organizing and retrieving routes in a hierarchical manner,
  * enabling complex routing scenarios with nested paths.
+ *
+ * @typeParam AdditionalMetadata - Type of additional metadata that can be associated with route nodes.
  */
-declare class RouteTree {
+declare class RouteTree<AdditionalMetadata extends Record<string, unknown> = {}> {
     /**
@@ -387,3 +423,3 @@ * The root node of the route tree.
      */
-    insert(route: string, metadata: RouteTreeNodeMetadataWithoutRoute): void;
+    insert(route: string, metadata: RouteTreeNodeMetadataWithoutRoute & AdditionalMetadata): void;
     /**
@@ -397,3 +433,3 @@ * Matches a given route against the route tree and returns the best matching route's metadata.
      */
-    match(route: string): RouteTreeNodeMetadata | undefined;
+    match(route: string): (RouteTreeNodeMetadata & AdditionalMetadata) | undefined;
     /**
@@ -487,2 +523,15 @@ * Converts the route tree into a serialized format representation.
     route: string;
+    /**
+     * Optional status code to return for this route.
+     */
+    status?: number;
+    /**
+     * Optional additional headers to include in the response for this route.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Specifies the rendering mode used for this route.
+     * If not provided, the default rendering mode for the application will be used.
+     */
+    renderMode?: RenderMode;
 }
@@ -495,3 +544,2 @@
 
-
 /**
@@ -504,2 +552,96 @@ * Represents the serialized format of a route tree as an array of node metadata objects.
 /**
+ * Server route configuration.
+ * @developerPreview
+ */
+export declare type ServerRoute = ServerRouteAppShell | ServerRouteClient | ServerRoutePrerender | ServerRoutePrerenderWithParams | ServerRouteServer;
+
+/**
+ * A server route that uses AppShell rendering mode.
+ */
+declare interface ServerRouteAppShell extends Omit<ServerRouteCommon, 'headers' | 'status'> {
+    /** Specifies that the route uses AppShell rendering mode. */
+    renderMode: RenderMode.AppShell;
+}
+
+/**
+ * A server route that uses Client-Side Rendering (CSR) mode.
+ */
+declare interface ServerRouteClient extends ServerRouteCommon {
+    /** Specifies that the route uses Client-Side Rendering (CSR) mode. */
+    renderMode: RenderMode.Client;
+}
+
+/**
+ * Common interface for server routes, providing shared properties.
+ */
+declare interface ServerRouteCommon {
+    /** The path associated with this route. */
+    path: string;
+    /** Optional additional headers to include in the response for this route. */
+    headers?: Record<string, string>;
+    /** Optional status code to return for this route. */
+    status?: number;
+}
+
+/**
+ * A server route that uses Static Site Generation (SSG) mode.
+ */
+declare interface ServerRoutePrerender extends Omit<ServerRouteCommon, 'status'> {
+    /** Specifies that the route uses Static Site Generation (SSG) mode. */
+    renderMode: RenderMode.Prerender;
+    /** Fallback cannot be specified unless `getPrerenderParams` is used. */
+    fallback?: never;
+}
+
+/**
+ * A server route configuration that uses Static Site Generation (SSG) mode, including support for routes with parameters.
+ */
+declare interface ServerRoutePrerenderWithParams extends Omit<ServerRoutePrerender, 'fallback'> {
+    /**
+     * Optional strategy to use if the SSG path is not pre-rendered.
+     * This is especially relevant for routes with parameterized URLs, where some paths may not be pre-rendered at build time.
+     *
+     * This property determines how to handle requests for paths that are not pre-rendered:
+     * - `PrerenderFallback.Server`: Use Server-Side Rendering (SSR) to dynamically generate the page at request time.
+     * - `PrerenderFallback.Client`: Use Client-Side Rendering (CSR) to fetch and render the page on the client side.
+     * - `PrerenderFallback.None`: No fallback; if the path is not pre-rendered, the server will not handle the request.
+     *
+     * @default `PrerenderFallback.Server` if not provided.
+     */
+    fallback?: PrerenderFallback;
+    /**
+     * A function that returns a Promise resolving to an array of objects, each representing a route path with URL parameters.
+     * This function runs in the injector context, allowing access to Angular services and dependencies.
+     *
+     * @returns A Promise resolving to an array where each element is an object with string keys (representing URL parameter names)
+     * and string values (representing the corresponding values for those parameters in the route path).
+     *
+     * @example
+     * ```typescript
+     * export const serverRouteConfig: ServerRoutes[] = [
+     *   {
+     *     path: '/product/:id',
+     *     renderMode: RenderMode.Prerender,
+     *     async getPrerenderParams() {
+     *       const productService = inject(ProductService);
+     *       const ids = await productService.getIds(); // Assuming this returns ['1', '2', '3']
+     *
+     *       return ids.map(id => ({ id })); // Generates paths like: [{ id: '1' }, { id: '2' }, { id: '3' }]
+     *     },
+     *   },
+     * ];
+     * ```
+     */
+    getPrerenderParams: () => Promise<Record<string, string>[]>;
+}
+
+/**
+ * A server route that uses Server-Side Rendering (SSR) mode.
+ */
+declare interface ServerRouteServer extends ServerRouteCommon {
+    /** Specifies that the route uses Server-Side Rendering (SSR) mode. */
+    renderMode: RenderMode.Server;
+}
+
+/**
  * Destroys the existing `AngularServerApp` instance, releasing associated resources and resetting the
@@ -524,6 +666,7 @@ * reference to `undefined`.
  * If not provided, the default manifest is retrieved using `getAngularAppManifest()`.
- *
+ * @param invokeGetPrerenderParams - A boolean flag indicating whether to invoke `getPrerenderParams` for parameterized SSG routes
+ * to handle prerendering paths. Defaults to `false`.
  * @returns A promise that resolves to a populated `RouteTree` containing all extracted routes from the Angular application.
  */
-export declare function ɵextractRoutesAndCreateRouteTree(url: URL, manifest?: AngularAppManifest): Promise<RouteTree>;
+export declare function ɵextractRoutesAndCreateRouteTree(url: URL, manifest?: AngularAppManifest, invokeGetPrerenderParams?: boolean): Promise<RouteTree>;
 
@@ -543,3 +686,3 @@ /**
  * and retrieves routes from the Angular router configuration. It handles both module-based
- * and function-based bootstrapping. It yields the resulting routes as `RouteResult` objects.
+ * and function-based bootstrapping. It yields the resulting routes as `RouteTreeNodeMetadata` objects.
  *
@@ -551,2 +694,4 @@ * @param bootstrap - A function that returns a promise resolving to an `ApplicationRef` or an Angular module to bootstrap.
  * for ensuring that API requests for relative paths succeed, which is essential for accurate route extraction.
+ * @param invokeGetPrerenderParams - A boolean flag indicating whether to invoke `getPrerenderParams` for parameterized SSG routes
+ * to handle prerendering paths. Defaults to `false`.
  * See:
@@ -557,3 +702,3 @@ *  - https://github.com/angular/angular/blob/d608b857c689d17a7ffa33bbb510301014d24a17/packages/platform-server/src/location.ts#L51
  */
-export declare function ɵgetRoutesFromAngularRouterConfig(bootstrap: AngularBootstrap, document: string, url: URL): Promise<AngularRouterConfigResult>;
+export declare function ɵgetRoutesFromAngularRouterConfig(bootstrap: AngularBootstrap, document: string, url: URL, invokeGetPrerenderParams?: boolean): Promise<AngularRouterConfigResult>;
 
@@ -583,11 +728,2 @@ export declare class ɵInlineCriticalCssProcessor extends CrittersBase {
 /**
- * Enum representing the different contexts in which server rendering can occur.
- */
-export declare enum ɵServerRenderContext {
-    SSR = "ssr",
-    SSG = "ssg",
-    AppShell = "app-shell"
-}
-
-/**
  * Sets the Angular app engine manifest.
@@ -594,0 +730,0 @@ *

node/index.d.ts

@@ -49,3 +49,3 @@ import { ApplicationRef } from '@angular/core';
      *     // Retrieve headers for the current request
-     *     const headers = angularAppEngine.getHeaders(res.req);
+     *     const headers = angularAppEngine.getPrerenderHeaders(res.req);
      *
@@ -60,3 +60,3 @@ *     // Apply the retrieved headers to the response
      */
-    getHeaders(request: IncomingMessage): ReadonlyMap<string, string>;
+    getPrerenderHeaders(request: IncomingMessage): ReadonlyMap<string, string>;
 }
@@ -63,0 +63,0 @@

package.json

 {
   "name": "@angular/ssr",
-  "version": "19.0.0-next.5",
+  "version": "19.0.0-next.6",
   "description": "Angular server side rendering utilities",
@@ -5,0 +5,0 @@ "license": "MIT",

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1442790

increased by2.51%

Lines of code

16005

increased by2.2%

No dependency changes