Skip to main content

ISRHandlerConfig

ISRHandlerConfig is the configuration object passed to the ISRHandler constructor. Every field is listed below. Defaults are applied in the ISRHandler constructor / render pipeline, not on the interface itself.

Import

import { ISRHandlerConfig } from '@rx-angular/isr/models';

Fields​

FieldTypeDefaultMeaning
indexHtmlstring— (required)Path to the HTML file served for any incoming request (the Angular index.html).
invalidateSecretTokenstring | nullnull (coerced via || null in the constructor)Secret token sent in the request body to authorize on-demand cache invalidation. Required (may be null to disable).
cacheCacheHandlernew InMemoryCacheHandler()Cache handler for storing/retrieving cached responses; defaults to in-memory. See CacheHandler.
commonEngineCommonEngine (from @angular/ssr/node)—CommonEngine instance used to render the application HTML.
angularAppEngineAngularNodeAppEngine (from @angular/ssr/node)—AngularNodeAppEngine instance used to render the application HTML (modern @angular/ssr path).
bootstrapCommonEngineRenderOptions['bootstrap']nullApplication bootstrap function used by the render engine.
serverDistFolderstringnullPath to the server dist folder (server bundle).
browserDistFolderstringnullPath to the browser dist folder (browser bundle).
inlineCriticalCssbooleantrueInline critical CSS to reduce render-blocking requests.
buildIdstring | nullnull (coerced via || null in the constructor)Build ID used to generate unique cache keys; a mismatch bypasses a cached entry.
enableLoggingbooleanfalseWhen true, logs additional debug information.
skipCachingOnHttpErrorbooleantrue (coerced via !== false in the constructor)When true, skips caching any response that returns an HTTP error status code.
variantsRenderVariant[]—Defines multiple page variants (each with identifier + detectVariant, optional simulateVariant) to cache separate versions. See RenderVariant.
allowedQueryParamsstring[]undefined (all query params part of the cache key)Query params allowed in the cache key. undefined = all included; [] = none included; an array = only the listed params.
modifyGeneratedHtmlModifyHtmlCallbackFndefaultModifyGeneratedHtml (adds a generated-at HTML comment)Callback to modify generated HTML on-the-fly before caching/serving. Use with caution (per-serve performance cost).
nonBlockingRenderboolean—When true, returns rendered HTML without waiting for the cache write to complete. This avoids client-side waiting times if the remote cache storage is down.
backgroundRevalidationboolean—When true, serves cached HTML immediately and revalidates the cache in the background. This lets sites serve stale content when live backend APIs are down, slow, or rate-limited.
cacheKeyGeneratorCacheKeyGeneratorFndefault cache-key generation logicCustom cache-key generation callback.

Signature​

interface ISRHandlerConfig {
indexHtml: string;
invalidateSecretToken: string | null;
cache?: CacheHandler;
commonEngine?: CommonEngine;
angularAppEngine?: AngularNodeAppEngine;
bootstrap?: CommonEngineRenderOptions['bootstrap'];
serverDistFolder?: string;
browserDistFolder?: string;
inlineCriticalCss?: boolean;
buildId?: string | null;
enableLogging?: boolean;
skipCachingOnHttpError?: boolean;
variants?: RenderVariant[];
allowedQueryParams?: string[];
modifyGeneratedHtml?: ModifyHtmlCallbackFn;
nonBlockingRender?: boolean;
backgroundRevalidation?: boolean;
cacheKeyGenerator?: CacheKeyGeneratorFn;
}

Sub-config interfaces​

Types consumed by ISRHandler methods and by config fields.

InvalidateConfig​

InvalidateConfig is the config argument of ISRHandler.invalidate.

interface InvalidateConfig {
providers?: Provider[];
}
FieldTypeMeaning
providersProvider[]Extra DI providers used while handling the invalidate() request.

RenderConfig​

RenderConfig is the config argument of ISRHandler.render.

interface RenderConfig {
providers?: Provider[];
/** @deprecated superseded by ISRHandlerConfig.modifyGeneratedHtml */
modifyGeneratedHtml?: (req: Request, html: string) => string;
}
FieldTypeMeaning
providersProvider[]Extra DI providers used while rendering.
modifyGeneratedHtml(req: Request, html: string) => string@deprecated, superseded by ISRHandlerConfig.modifyGeneratedHtml; marked for removal in a future major. Use the config field instead.

ServeFromCacheConfig​

ServeFromCacheConfig is the config argument of ISRHandler.serveFromCache.

interface ServeFromCacheConfig {
providers?: Provider[];
modifyCachedHtml?: (req: Request, html: string) => string;
}
FieldTypeMeaning
providersProvider[]Extra DI providers used while serving from cache.
modifyCachedHtml(req: Request, html: string) => stringModify cached HTML per-request on serve (e.g. inject webp/avif support classes based on the accept header). Use with caution (per-serve performance cost).

RouteISRConfig​

Per-route data config. Attached to a route via data: { revalidate } as RouteISRConfig. This is a peer models export (not a nested field of ISRHandlerConfig).

interface RouteISRConfig {
revalidate?: number | null;
}
FieldTypeMeaning
revalidatenumber | nullRevalidation window for the route. null = never cache (regenerate every request); 0 = cache forever until manual invalidation; N = cache N seconds, then regenerate on the next hit after expiry.

Example

import { Routes } from '@angular/router';
import { RouteISRConfig } from '@rx-angular/isr/models';

export const routes: Routes = [
{
path: 'my-page',
component: MyPageComponent,
data: { revalidate: 60 } as RouteISRConfig,
},
];

CacheKeyGeneratorFn​

Function type for ISRHandlerConfig.cacheKeyGenerator.

type CacheKeyGeneratorFn = (url: string, allowedQueryParams: string[] | null | undefined, variant: RenderVariant | null) => string;
ParamTypeMeaning
urlstringThe request URL.
allowedQueryParamsstring[] | null | undefinedThe configured allow-list (see allowedQueryParams above).
variantRenderVariant | nullThe matched variant, or null for the base page.
returnsstringThe computed cache key.

ModifyHtmlCallbackFn​

Function type for ISRHandlerConfig.modifyGeneratedHtml.

type ModifyHtmlCallbackFn = (req: Request, html: string, revalidateTime?: number | null) => string;
ParamTypeMeaning
reqRequestThe Express request.
htmlstringThe generated HTML.
revalidateTimenumber | nullOptional. The route's revalidate value.
returnsstringThe modified HTML.

See also​