@opennextjs/aws 4.1.13 → 4.1.14

package/dist/adapters/cache.d.ts

@@ -12,9 +12,29 @@ export default class Cache {
     getIncrementalCache(key: string): Promise<CacheHandlerValue | null>;
     set(key: string, data?: IncrementalCacheValue, ctx?: IncrementalCacheContext): Promise<void>;
     private writeCache;
+    /**
+     * Revalidates cache entries associated with one or more tags.
+     *
+     * The tag cache is updated before the CDN is invalidated. CDN handlers that
+     * support tag invalidation receive the original tags; other handlers retain
+     * the existing path-based invalidation behavior.
+     *
+     * @param tags Tags whose cache entries should be revalidated.
+     * @param durations Optional stale and expiry durations.
+     * @returns A promise that resolves when revalidation is complete.
+     */
     revalidateTag(tags: string | string[], durations?: {
         expire?: number;
     }): Promise<void>;
     private updateTagsOnSet;
-    private extractRevalidateForSet;
+    /**
+     * Returns the lifetime Next.js passed to `set()`.
+     *
+     * It is stored with the entry so that `get()` can report it. Only the newest context
+     * shape carries an `expire`.
+     *
+     * @param ctx The context passed to `set()`
+     * @returns The lifetime, empty when there is none
+     */
+    private extractCacheControlForSet;
 }

package/dist/adapters/cache.js

@@ -1,7 +1,7 @@
 import { getStaleLastModified, getTagsFromValue, hasBeenRevalidated, isStale, writeTags, } from "../utils/cache.js";
 import { isBinaryContentType } from "../utils/binary";
 import { CACHE_TAGS_HEADER } from "../utils/cacheHeaders";
-import { getPathFromRouteCacheKey } from "../utils/routeCacheKey";
+import { getPathFromRouteCacheKey, useRouteCacheKeys, } from "../utils/routeCacheKey";
 import { compareSemver } from "../utils/semver";
 import { debug, error, warn } from "./logger";
 export const SOFT_TAG_PREFIX = "_N_T_/";
@@ -16,6 +16,78 @@ function isFetchCache(options) {
     }
     return false;
 }
+/**
+ * Returns the lifetime to report to Next.js for a cache entry.
+ *
+ * Next.js takes it from a per-route record that only the instance which rendered the page
+ * has filled, with the prerender manifest as a fallback. A page rendered on demand by a
+ * dynamic route is in neither, and Next.js then falls back to `revalidate: 1`. The
+ * lifetime stored with the entry fills that gap.
+ *
+ * A stale entry is signalled by offsetting `lastModified` by `revalidate` (see
+ * `getStaleLastModified`), which needs a numeric `revalidate`. Without one, Next.js would use
+ * its own lifetime: `revalidate: false` serves the entry as a hit, and the `expire` of the
+ * prerender manifest turns it into a blocking revalidation. `{ revalidate: 1 }` is reported
+ * instead, Next.js records the actual lifetime again when the entry is re-rendered.
+ *
+ * @param value The cache entry
+ * @param isEntryStale Whether the tag cache reported the entry as stale
+ * @returns The lifetime to report, or `undefined` to leave it to Next.js
+ */
+function getCacheControl({ revalidate, expire }, isEntryStale) {
+    if (isEntryStale && typeof revalidate !== "number") {
+        return { revalidate: 1 };
+    }
+    // A build time entry has no stored lifetime, the prerender manifest has it.
+    if (revalidate === undefined) {
+        return undefined;
+    }
+    return { revalidate, expire };
+}
+// `null` until the module is loaded, `undefined` when it can not be loaded.
+let sharedCacheControls = null;
+/**
+ * Returns the map Next.js keeps the lifetime of routes in.
+ *
+ * The module is loaded lazily, and only once: a static import would pull `next` into the
+ * external middleware bundle. `next` is external to the compiled cache handler, so this is
+ * the map the server reads.
+ *
+ * @returns The map, or `undefined` when the module can not be loaded
+ */
+async function getSharedCacheControls() {
+    if (sharedCacheControls === null) {
+        try {
+            const { SharedCacheControls } = await import("next/dist/server/lib/incremental-cache/shared-cache-controls.external.js");
+            // `cacheControls` is only private to TypeScript.
+            sharedCacheControls = SharedCacheControls.cacheControls;
+        }
+        catch (e) {
+            debug("Failed to load the Next.js cache controls", e);
+            sharedCacheControls = undefined;
+        }
+    }
+    return sharedCacheControls;
+}
+/**
+ * Records the lifetime of a cache entry where Next.js < 16.4 reads it.
+ *
+ * Next.js 16.4+ reads the `cacheControl` returned by `get()` instead. The map is keyed by
+ * route cache key, which is the key passed to the cache handler. Versions without route
+ * cache keys are skipped. Like 16.4, the lifetime of the entry overwrites the recorded one.
+ *
+ * @param key The key of the cache entry
+ * @param cacheControl The lifetime to record
+ */
+async function recordCacheControl(key, cacheControl) {
+    const nextVersion = globalThis.nextVersion;
+    if (!cacheControl ||
+        compareSemver(nextVersion, ">=", "16.4.0") ||
+        !useRouteCacheKeys(nextVersion)) {
+        return;
+    }
+    (await getSharedCacheControls())?.set(key, cacheControl);
+}
 // We need to use globalThis client here as this class can be defined at load time in next 12 but client is not available at load time
 export default class Cache {
     async get(key, 
@@ -101,9 +173,12 @@ export default class Cache {
             if (_isStale) {
                 _lastModified = getStaleLastModified(cacheData.revalidate);
             }
+            const _cacheControl = getCacheControl(cacheData, _isStale);
+            await recordCacheControl(key, _cacheControl);
             if (cacheData?.type === "route") {
                 return {
                     lastModified: _lastModified,
+                    cacheControl: _cacheControl,
                     value: {
                         kind: compareSemver(globalThis.nextVersion, ">=", "15.0.0")
                             ? "APP_ROUTE"
@@ -137,6 +212,7 @@ export default class Cache {
                     }
                     return {
                         lastModified: _lastModified,
+                        cacheControl: _cacheControl,
                         value: {
                             kind: "APP_PAGE",
                             html: cacheData.html,
@@ -163,6 +239,7 @@ export default class Cache {
                 }
                 return {
                     lastModified: _lastModified,
+                    cacheControl: _cacheControl,
                     value: {
                         kind: compareSemver(globalThis.nextVersion, ">=", "15.0.0")
                             ? "PAGES"
@@ -177,6 +254,7 @@ export default class Cache {
             if (cacheData?.type === "redirect") {
                 return {
                     lastModified: _lastModified,
+                    cacheControl: _cacheControl,
                     value: {
                         kind: "REDIRECT",
                         props: cacheData.props,
@@ -214,7 +292,7 @@ export default class Cache {
                 await globalThis.incrementalCache.delete(key);
             }
             else {
-                const revalidate = this.extractRevalidateForSet(ctx);
+                const cacheControl = this.extractCacheControlForSet(ctx);
                 switch (data.kind) {
                     case "ROUTE":
                     case "APP_ROUTE": {
@@ -228,7 +306,7 @@ export default class Cache {
                                 status,
                                 headers,
                             },
-                            revalidate,
+                            ...cacheControl,
                         }, "cache");
                         break;
                     }
@@ -245,7 +323,7 @@ export default class Cache {
                                     status,
                                     headers,
                                 },
-                                revalidate,
+                                ...cacheControl,
                             }, "cache");
                         }
                         else {
@@ -253,7 +331,7 @@ export default class Cache {
                                 type: "page",
                                 html,
                                 json: pageData,
-                                revalidate,
+                                ...cacheControl,
                             }, "cache");
                         }
                         break;
@@ -275,7 +353,7 @@ export default class Cache {
                                 headers,
                                 postponed,
                             },
-                            revalidate,
+                            ...cacheControl,
                             segmentData: segmentData ? segmentToWrite : undefined,
                         }, "cache");
                         break;
@@ -287,7 +365,7 @@ export default class Cache {
                         await globalThis.incrementalCache.set(key, {
                             type: "redirect",
                             props: data.props,
-                            revalidate,
+                            ...cacheControl,
                         }, "cache");
                         break;
                     case "IMAGE":
@@ -302,6 +380,17 @@ export default class Cache {
             error("Failed to set cache", e);
         }
     }
+    /**
+     * Revalidates cache entries associated with one or more tags.
+     *
+     * The tag cache is updated before the CDN is invalidated. CDN handlers that
+     * support tag invalidation receive the original tags; other handlers retain
+     * the existing path-based invalidation behavior.
+     *
+     * @param tags Tags whose cache entries should be revalidated.
+     * @param durations Optional stale and expiry durations.
+     * @returns A promise that resolves when revalidation is complete.
+     */
     async revalidateTag(tags, durations) {
         const config = globalThis.openNextConfig.dangerous;
         if (config?.disableTagCache || config?.disableIncrementalCache) {
@@ -312,8 +401,8 @@ export default class Cache {
             return;
         }
         try {
+            const cdnInvalidationHandler = globalThis.cdnInvalidationHandler;
             if (globalThis.tagCache.mode === "nextMode") {
-                const paths = (await globalThis.tagCache.getPathsByTags?.(_tags)) ?? [];
                 const now = Date.now();
                 const tagsToWrite = _tags.map((tag) => {
                     if (durations) {
@@ -333,21 +422,25 @@ export default class Cache {
                     };
                 });
                 await writeTags(tagsToWrite);
-                if (paths.length > 0) {
-                    // TODO: we should introduce a new method in cdnInvalidationHandler to invalidate paths by tags for cdn that supports it
-                    // It also means that we'll need to provide the tags used in every request to the wrapper or converter.
-                    // Fixed Next.js releases store route-scoped cache keys in the tag cache.
-                    await globalThis.cdnInvalidationHandler.invalidatePaths(paths.map(getPathFromRouteCacheKey).map((path) => ({
-                        initialPath: path,
-                        rawPath: path,
-                        resolvedRoutes: [
-                            {
-                                route: path,
-                                // TODO: ideally here we should check if it's an app router page or route
-                                type: "app",
-                            },
-                        ],
-                    })));
+                if (cdnInvalidationHandler.invalidateTags) {
+                    await cdnInvalidationHandler.invalidateTags(_tags);
+                }
+                else {
+                    const paths = (await globalThis.tagCache.getPathsByTags?.(_tags)) ?? [];
+                    if (paths.length > 0) {
+                        // Fixed Next.js releases store route-scoped cache keys in the tag cache.
+                        await cdnInvalidationHandler.invalidatePaths(paths.map(getPathFromRouteCacheKey).map((path) => ({
+                            initialPath: path,
+                            rawPath: path,
+                            resolvedRoutes: [
+                                {
+                                    route: path,
+                                    // TODO: ideally here we should check if it's an app router page or route
+                                    type: "app",
+                                },
+                            ],
+                        })));
+                    }
                 }
                 return;
             }
@@ -406,6 +499,9 @@ export default class Cache {
                 }
                 // Update all keys with the given tag with revalidatedAt set to now
                 await writeTags(toInsert);
+                if (cdnInvalidationHandler.invalidateTags) {
+                    continue;
+                }
                 // We can now invalidate all paths in the CDN
                 // This only applies to `revalidateTag`, not to `res.revalidate()`
                 const uniquePaths = Array.from(new Set(toInsert
@@ -414,7 +510,7 @@ export default class Cache {
                     // Fixed Next.js releases store route-scoped cache keys in the tag cache.
                     .map((t) => getPathFromRouteCacheKey(`/${t.path}`))));
                 if (uniquePaths.length > 0) {
-                    await globalThis.cdnInvalidationHandler.invalidatePaths(uniquePaths.map((path) => ({
+                    await cdnInvalidationHandler.invalidatePaths(uniquePaths.map((path) => ({
                         initialPath: path,
                         rawPath: path,
                         resolvedRoutes: [
@@ -427,6 +523,9 @@ export default class Cache {
                     })));
                 }
             }
+            if (cdnInvalidationHandler.invalidateTags) {
+                await cdnInvalidationHandler.invalidateTags(_tags);
+            }
         }
         catch (e) {
             error("Failed to revalidate tag", e);
@@ -471,19 +570,28 @@ export default class Cache {
             })));
         }
     }
-    extractRevalidateForSet(ctx) {
+    /**
+     * Returns the lifetime Next.js passed to `set()`.
+     *
+     * It is stored with the entry so that `get()` can report it. Only the newest context
+     * shape carries an `expire`.
+     *
+     * @param ctx The context passed to `set()`
+     * @returns The lifetime, empty when there is none
+     */
+    extractCacheControlForSet(ctx) {
         if (ctx === undefined) {
-            return undefined;
+            return {};
         }
         if (typeof ctx === "number" || ctx === false) {
-            return ctx;
+            return { revalidate: ctx };
         }
         if ("revalidate" in ctx) {
-            return ctx.revalidate;
+            return { revalidate: ctx.revalidate };
         }
         if ("cacheControl" in ctx) {
-            return ctx.cacheControl?.revalidate;
+            return { ...ctx.cacheControl };
         }
-        return undefined;
+        return {};
     }
 }

package/dist/adapters/config/index.js

@@ -1,10 +1,11 @@
 import path from "node:path";
 import { debug } from "../logger";
-import { loadAppPathRoutesManifest, loadAppPathsManifest, loadAppPathsManifestKeys, loadBuildId, loadConfig, loadConfigHeaders, loadFunctionsConfigManifest, loadHtmlPages, loadMiddlewareManifest, loadPagesManifest, loadPrerenderManifest, loadRoutesManifest, } from "./util.js";
+import { getOpenNextBuildId, loadAppPathRoutesManifest, loadAppPathsManifest, loadAppPathsManifestKeys, loadBuildId, loadConfig, loadConfigHeaders, loadFunctionsConfigManifest, loadHtmlPages, loadMiddlewareManifest, loadPagesManifest, loadPrerenderManifest, loadRoutesManifest, } from "./util.js";
 export const NEXT_DIR = path.join(__dirname, ".next");
 export const OPEN_NEXT_DIR = path.join(__dirname, ".open-next");
 debug({ NEXT_DIR, OPEN_NEXT_DIR });
 export const NextConfig = /* @__PURE__ */ loadConfig(NEXT_DIR);
+// Next.js build id, only use it for URLs (see `getOpenNextBuildId`)
 export const BuildId = /* @__PURE__ */ loadBuildId(NEXT_DIR);
 export const HtmlPages = /* @__PURE__ */ loadHtmlPages(NEXT_DIR);
 // export const PublicAssets = loadPublicAssets(OPEN_NEXT_DIR);
@@ -23,9 +24,18 @@ export const AppPathRoutesManifest =
 export const FunctionsConfigManifest = 
 /* @__PURE__ */ loadFunctionsConfigManifest(NEXT_DIR);
 /**
- * @deprecated Do not use NEXT_BUILD_ID above Next 16.2, as it could be a fixed value if used in conjonction with deploymentId
- * We keep it for backward compatibility
+ * Next.js build id (`.next/BUILD_ID`).
+ *
+ * Only use it for URLs generated by Next (i.e. `/_next/data/<BUILD_ID>/...`).
+ * Do not use it to scope storage: since Next 16.2 it is a constant when `deploymentId` is set.
+ * Use `OPEN_NEXT_BUILD_ID` instead.
  */
 process.env.NEXT_BUILD_ID = BuildId;
-process.env.OPEN_NEXT_BUILD_ID = NextConfig.deploymentId ?? BuildId;
+/**
+ * Open Next build id, unique per deployment.
+ *
+ * Use it to prefix the cache keys (incremental cache, tag cache, ...).
+ * See `getOpenNextBuildId` for details.
+ */
+process.env.OPEN_NEXT_BUILD_ID = getOpenNextBuildId(NextConfig, BuildId);
 process.env.NEXT_PREVIEW_MODE_ID = PrerenderManifest?.preview?.previewModeId;

package/dist/adapters/config/util.d.ts

@@ -2,6 +2,25 @@ import type { FunctionsConfigManifest, MiddlewareManifest, NextConfig, Prerender
 import type { PublicFiles } from "../../build";
 export declare function loadConfig(nextDir: string): NextConfig;
 export declare function loadBuildId(nextDir: string): string;
+/**
+ * Returns the Open Next build id, used to scope data to a deployment.
+ *
+ * Next.js uses two different ids:
+ * - The build id (`.next/BUILD_ID`) is part of the URLs generated by Next (i.e. `/_next/data/<BUILD_ID>/...`).
+ *   Since Next 16.2 it is a constant (`build-TfctsWXpff2fKS`) when `deploymentId` is set without `generateBuildId`.
+ * - The deployment id (`deploymentId`) is unique per deployment when set.
+ *
+ * The Open Next build id is the deployment id when set, the build id otherwise.
+ * It must be used to prefix anything stored across deployments (incremental cache, tag cache, ...),
+ * both at build time (seeded data) and at runtime (via `process.env.OPEN_NEXT_BUILD_ID`).
+ *
+ * Use the Next build id for URLs, and the Open Next build id for storage keys.
+ *
+ * @param nextConfig The Next.js config (from `required-server-files.json`).
+ * @param buildId The Next.js build id (from `.next/BUILD_ID`).
+ * @returns The Open Next build id.
+ */
+export declare function getOpenNextBuildId(nextConfig: Pick<NextConfig, "deploymentId">, buildId: string): string;
 export declare function loadPagesManifest(nextDir: string): Record<string, string>;
 export declare function loadHtmlPages(nextDir: string): string[];
 export declare function loadPublicAssets(openNextDir: string): PublicFiles;

package/dist/adapters/config/util.js

@@ -10,6 +10,27 @@ export function loadBuildId(nextDir) {
     const filePath = path.join(nextDir, "BUILD_ID");
     return fs.readFileSync(filePath, "utf-8").trim();
 }
+/**
+ * Returns the Open Next build id, used to scope data to a deployment.
+ *
+ * Next.js uses two different ids:
+ * - The build id (`.next/BUILD_ID`) is part of the URLs generated by Next (i.e. `/_next/data/<BUILD_ID>/...`).
+ *   Since Next 16.2 it is a constant (`build-TfctsWXpff2fKS`) when `deploymentId` is set without `generateBuildId`.
+ * - The deployment id (`deploymentId`) is unique per deployment when set.
+ *
+ * The Open Next build id is the deployment id when set, the build id otherwise.
+ * It must be used to prefix anything stored across deployments (incremental cache, tag cache, ...),
+ * both at build time (seeded data) and at runtime (via `process.env.OPEN_NEXT_BUILD_ID`).
+ *
+ * Use the Next build id for URLs, and the Open Next build id for storage keys.
+ *
+ * @param nextConfig The Next.js config (from `required-server-files.json`).
+ * @param buildId The Next.js build id (from `.next/BUILD_ID`).
+ * @returns The Open Next build id.
+ */
+export function getOpenNextBuildId(nextConfig, buildId) {
+    return nextConfig.deploymentId || buildId;
+}
 export function loadPagesManifest(nextDir) {
     const filePath = path.join(nextDir, "server/pages-manifest.json");
     const json = fs.readFileSync(filePath, "utf-8");

package/dist/adapters/image-optimization-adapter.js

@@ -1,13 +1,14 @@
 import { createHash } from "node:crypto";
 import https from "node:https";
 import path from "node:path";
-import { loadBuildId, loadConfig } from "./config/util.js";
+import { getOpenNextBuildId, loadBuildId, loadConfig } from "./config/util.js";
 import { OpenNextNodeResponse } from "../http/openNextResponse.js";
 // @ts-ignore
 import { defaultConfig } from "next/dist/server/config-shared";
 import { ImageOptimizerCache,
 // @ts-ignore
  } from "next/dist/server/image-optimizer";
+import { compareSemver } from "../utils/semver.js";
 import { emptyReadableStream, toReadableStream } from "../utils/stream.js";
 import { createGenericHandler } from "../core/createGenericHandler.js";
 import { resolveImageLoader } from "../core/resolve.js";
@@ -18,6 +19,11 @@ setNodeEnv();
 const nextDir = path.join(__dirname, ".next");
 const config = loadConfig(nextDir);
 const buildId = loadBuildId(nextDir);
+// Used to compute the static ETag, it must change on every deployment.
+// Since Next 16.2, the build id is a constant when `deploymentId` is set.
+const etagBuildId = compareSemver(globalThis.nextVersion, ">=", "16.2.0")
+    ? getOpenNextBuildId(config, buildId)
+    : buildId;
 const nextConfig = {
     ...defaultConfig,
     images: {
@@ -96,7 +102,7 @@ function computeEtag(imageParams) {
         href: imageParams.href,
         width: imageParams.width,
         quality: imageParams.quality,
-        buildId,
+        buildId: etagBuildId,
     }))
         .digest("base64");
 }

package/dist/build/createAssets.d.ts

@@ -14,6 +14,9 @@ export declare function createStaticAssets(options: buildHelper.BuildOptions, {
 /**
  * Create the cache assets.
  *
+ * The cache entries, the fetch cache entries and the tag cache seed are prefixed with the Open Next build id
+ * so that they match the keys used at runtime.
+ *
  * @param options Build options.
  * @returns Whether the tag cache is used, and the meta files collected.
  */

package/dist/build/createAssets.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { loadConfig } from "../adapters/config/util.js";
+import { getOpenNextBuildId, loadConfig } from "../adapters/config/util.js";
 import { safeParseJsonFile } from "../utils/safe-json-parse.js";
 import logger from "../logger.js";
 import { isBinaryContentType } from "../utils/binary.js";
@@ -59,6 +59,9 @@ export function createStaticAssets(options, { useBasePath = false } = {}) {
 /**
  * Create the cache assets.
  *
+ * The cache entries, the fetch cache entries and the tag cache seed are prefixed with the Open Next build id
+ * so that they match the keys used at runtime.
+ *
  * @param options Build options.
  * @returns Whether the tag cache is used, and the meta files collected.
  */
@@ -66,9 +69,9 @@ export function createCacheAssets(options) {
     logger.info("Bundling cache assets...");
     const { appBuildOutputPath, outputDir } = options;
     const packagePath = buildHelper.getPackagePath(options);
-    const buildId = buildHelper.getBuildId(options);
     const nextConfig = loadConfig(path.join(appBuildOutputPath, ".next"));
-    const openNextBuildId = nextConfig.deploymentId ?? buildId;
+    // Must match `process.env.OPEN_NEXT_BUILD_ID` used at runtime to read the cache entries and the tags
+    const openNextBuildId = getOpenNextBuildId(nextConfig, buildHelper.getBuildId(options));
     let useTagCache = false;
     const dotNextPath = path.join(appBuildOutputPath, ".next/standalone", packagePath);
     const outputCachePath = path.join(outputDir, "cache", openNextBuildId);
@@ -180,8 +183,8 @@ export function createCacheAssets(options) {
                 .split(",")
                 .forEach((tag) => {
                 metaFiles.push({
-                    tag: { S: path.posix.join(buildId, tag.trim()) },
-                    path: { S: path.posix.join(buildId, cacheKey) },
+                    tag: { S: path.posix.join(openNextBuildId, tag.trim()) },
+                    path: { S: path.posix.join(openNextBuildId, cacheKey) },
                     revalidatedAt: { N: "1" },
                 });
             });
@@ -190,7 +193,7 @@ export function createCacheAssets(options) {
     // Copy fetch-cache to cache folder
     const fetchCachePath = path.join(appBuildOutputPath, ".next/cache/fetch-cache");
     if (fs.existsSync(fetchCachePath)) {
-        const fetchOutputPath = path.join(outputDir, "cache", "__fetch", buildId);
+        const fetchOutputPath = path.join(outputDir, "cache", "__fetch", openNextBuildId);
         fs.mkdirSync(fetchOutputPath, { recursive: true });
         fs.cpSync(fetchCachePath, fetchOutputPath, { recursive: true });
         buildHelper.traverseFiles(fetchCachePath, () => true, ({ absolutePath, relativePath }) => {
@@ -198,9 +201,9 @@ export function createCacheAssets(options) {
             const fileData = safeParseJsonFile(fileContent, absolutePath);
             fileData?.tags?.forEach((tag) => {
                 metaFiles.push({
-                    tag: { S: path.posix.join(buildId, tag) },
+                    tag: { S: path.posix.join(openNextBuildId, tag) },
                     path: {
-                        S: path.posix.join(buildId, relativePath),
+                        S: path.posix.join(openNextBuildId, relativePath),
                     },
                     revalidatedAt: { N: "1" },
                 });

package/dist/build/createImageOptimizationBundle.js

@@ -83,7 +83,6 @@ export async function createImageOptimizationBundle(options) {
         arch: isDev ? undefined : "arm64",
         // Use the local platform in dev
         os: isDev ? os.platform() : "linux",
-        nodeVersion: "18",
         libc: "glibc",
     });
 }

package/dist/build/helper.js

@@ -381,7 +381,7 @@ export function getPackagePath(options) {
  * @returns the Next.js runtime used: "webpack" or "turbopack"
  */
 export function getBundlerRuntime(options) {
-    const dotNextServerPath = path.join(options.appPath, ".next/server");
+    const dotNextServerPath = path.join(options.appBuildOutputPath, ".next/server");
     if (fs.existsSync(path.join(dotNextServerPath, "webpack-runtime.js"))) {
         return "webpack";
     }

package/dist/build/installDeps.js

@@ -12,20 +12,19 @@ export function installDependencies(outputDir, installOptions) {
         // First we create a tempDir
         const tempInstallDir = fs.mkdtempSync(path.join(os.tmpdir(), `open-next-install-${name}`));
         logger.info(`Installing dependencies for ${name}...`);
+        if (installOptions.nodeVersion) {
+            logger.warn("install.nodeVersion is deprecated and ignored (npm no longer supports --target)");
+        }
         // We then need to run install in the tempDir
         // We don't install in the output dir directly because it could contain a package.json, and npm would then try to reinstall not complete deps from tracing the files
-        const archOption = installOptions.arch
-            ? `--arch=${installOptions.arch}`
-            : "";
-        const targetOption = installOptions.nodeVersion
-            ? `--target=${installOptions.nodeVersion}`
-            : "";
+        // npm filters platform-specific optional dependencies (e.g. sharp's @img/* packages) by --cpu; npm 12 rejects (npm 11 warns) both --arch and --target
+        const cpuOption = installOptions.arch ? `--cpu=${installOptions.arch}` : "";
         const libcOption = installOptions.libc
             ? `--libc=${installOptions.libc}`
             : "";
         const osOption = `--os=${installOptions.os ?? "linux"}`;
         const additionalArgs = installOptions.additionalArgs ?? "";
-        const installCommand = `npm install ${osOption} ${archOption} ${targetOption} ${libcOption} ${additionalArgs} ${installOptions.packages.join(" ")}`;
+        const installCommand = `npm install ${osOption} ${cpuOption} ${libcOption} ${additionalArgs} ${installOptions.packages.join(" ")}`;
         execSync(installCommand, {
             stdio: "pipe",
             cwd: tempInstallDir,

package/dist/build/patch/patches/patchNextServer.d.ts

@@ -3,6 +3,31 @@ export declare const disablePreloadingRule = "\nrule:\n  kind: statement_block\n
 export declare const removeMiddlewareManifestRule = "\nrule:\n  kind: statement_block\n  inside:\n    kind: method_definition\n    has:\n      kind: property_identifier\n      regex: ^getMiddlewareManifest$\nfix:\n  '{return null;}'\n";
 export declare const emptyHandleNextImageRequestRule = "\nrule:\n  kind: assignment_expression\n  pattern: this.handleNextImageRequest = $VALUE\n  inside:\n    kind: method_definition\n    stopBy: end\n    has:\n      kind: property_identifier\n      regex: ^constructor$\n    inside:\n      kind: class_body\nfix:\n  this.handleNextImageRequest = async (req, res, parsedUrl) => false\n";
 export declare const provideInternalWaitUntil = "\nrule:\n  kind: return_statement\n  inside:\n    kind: method_definition\n    stopBy: end\n    has:\n      kind: property_identifier\n      regex: getInternalWaitUntil\n\nfix:\n return globalThis.__openNextAls.getStore()?.waitUntil;\n";
+/**
+ * Exposes `NextNodeServer#revalidate` to `res.revalidate()` of the Pages Router API routes.
+ *
+ * Starting with Next 15.4, `res.revalidate()` uses the `revalidate` function of the router server
+ * context (`globalThis[Symbol.for("@next/router-server-methods")]`) to revalidate in-process.
+ * The context is populated by the router server which is not used by OpenNext.
+ * Without it, `res.revalidate()` throws
+ * `Invariant: missing internal router-server-methods this is an internal bug`.
+ *
+ * `NextNodeServer#handleCatchallRenderRequest` creates the context for environments without
+ * router server, this rule adds `revalidate` to it:
+ *
+ * ```js
+ * routerServerGlobal[RouterServerContextSymbol][relativeProjectDir] = {
+ *   render404: this.render404.bind(this),
+ *   // added by the rule
+ *   revalidate: this.revalidate.bind(this),
+ * };
+ * ```
+ *
+ * OpenNext wraps `NextNodeServer#revalidate` at runtime, see `core/revalidate.ts`.
+ *
+ * https://github.com/vercel/next.js/blob/4e6c27b/packages/next/src/server/api-utils/node/api-resolver.ts
+ */
+export declare const exposeRevalidateRule = "\nrule:\n  pattern:\n    context: \"({ render404: this.render404.bind(this) })\"\n    selector: pair\n  inside:\n    kind: object\n    not:\n      has:\n        kind: pair\n        has:\n          field: key\n          regex: ^revalidate$\nfix: |-\n  render404: this.render404.bind(this),\n  revalidate: this.revalidate.bind(this)\n";
 /**
  * Swaps the body for a throwing implementation
  *

package/dist/build/patch/patches/patchNextServer.js

@@ -60,6 +60,47 @@ rule:
 fix:
  return globalThis.__openNextAls.getStore()?.waitUntil;
 `;
+/**
+ * Exposes `NextNodeServer#revalidate` to `res.revalidate()` of the Pages Router API routes.
+ *
+ * Starting with Next 15.4, `res.revalidate()` uses the `revalidate` function of the router server
+ * context (`globalThis[Symbol.for("@next/router-server-methods")]`) to revalidate in-process.
+ * The context is populated by the router server which is not used by OpenNext.
+ * Without it, `res.revalidate()` throws
+ * `Invariant: missing internal router-server-methods this is an internal bug`.
+ *
+ * `NextNodeServer#handleCatchallRenderRequest` creates the context for environments without
+ * router server, this rule adds `revalidate` to it:
+ *
+ * ```js
+ * routerServerGlobal[RouterServerContextSymbol][relativeProjectDir] = {
+ *   render404: this.render404.bind(this),
+ *   // added by the rule
+ *   revalidate: this.revalidate.bind(this),
+ * };
+ * ```
+ *
+ * OpenNext wraps `NextNodeServer#revalidate` at runtime, see `core/revalidate.ts`.
+ *
+ * https://github.com/vercel/next.js/blob/4e6c27b/packages/next/src/server/api-utils/node/api-resolver.ts
+ */
+export const exposeRevalidateRule = `
+rule:
+  pattern:
+    context: "({ render404: this.render404.bind(this) })"
+    selector: pair
+  inside:
+    kind: object
+    not:
+      has:
+        kind: pair
+        has:
+          field: key
+          regex: ^revalidate$
+fix: |-
+  render404: this.render404.bind(this),
+  revalidate: this.revalidate.bind(this)
+`;
 /**
  * Swaps the body for a throwing implementation
  *
@@ -138,6 +179,13 @@ export const patchNextServer = {
             contentFilter: /getInternalWaitUntil/,
             patchCode: createPatchCode(provideInternalWaitUntil),
         },
+        // Expose `NextNodeServer#revalidate` to `res.revalidate()`
+        {
+            versions: ">=15.4.0",
+            pathFilter,
+            contentFilter: /render404: this\.render404\.bind\(this\)/,
+            patchCode: createPatchCode(exposeRevalidateRule),
+        },
         ...babelPatches,
     ],
 };

package/dist/core/requestHandler.js

@@ -33,6 +33,11 @@ export async function openNextHandler(internalEvent, options) {
         if (initialHeaders["x-forwarded-host"]) {
             initialHeaders.host = initialHeaders["x-forwarded-host"];
         }
+        const requestStore = globalThis.__openNextAls.getStore();
+        if (requestStore) {
+            // Used by `res.revalidate()`, see `core/revalidate.ts`
+            requestStore.host = initialHeaders.host;
+        }
         debug("internalEvent", internalEvent);
         // These 3 will get overwritten by the routing handler if not using an external middleware
         const internalHeaders = {

package/dist/core/resolve.d.ts

@@ -51,5 +51,12 @@ export declare function resolveProxyRequest(proxyRequest: OverrideOptions["proxy
 /**
  * @__PURE__
  */
-export declare function resolveCdnInvalidation(cdnInvalidation: OverrideOptions["cdnInvalidation"]): Promise<import("../types/overrides.js").CDNInvalidationHandler>;
+export declare function resolveCdnInvalidation(cdnInvalidation: OverrideOptions["cdnInvalidation"]): Promise<{
+    name: string;
+    invalidatePaths: (_: {
+        initialPath: string;
+        rawPath: string;
+        resolvedRoutes: import("../types/open-next.js").ResolvedRoute[];
+    }[]) => Promise<void>;
+}>;
 export {};

package/dist/core/revalidate.d.ts

@@ -0,0 +1,68 @@
+import type { ResolvedRoute } from "../types/open-next.js";
+/**
+ * Arguments passed by Next to the router server `revalidate` function.
+ *
+ * Next renamed `revalidateHeaders` to `headers` in 16.x.
+ */
+export interface RevalidateArgs {
+    urlPath: string;
+    headers?: Record<string, string | string[] | undefined>;
+    revalidateHeaders?: Record<string, string | string[] | undefined>;
+    opts: {
+        unstable_onlyGenerated?: boolean;
+    };
+}
+export type RevalidateFn = (args: RevalidateArgs) => Promise<void>;
+/**
+ * Resolve the route of a path.
+ *
+ * Static routes take precedence over dynamic routes, as in Next.
+ *
+ * @param urlPath The path passed to `res.revalidate()`, may include the basePath and a locale
+ * @returns The resolved route or `undefined` when no route matches
+ */
+export declare function resolveRoute(urlPath: string): ResolvedRoute | undefined;
+/**
+ * Convert a resolved route to the format used in `functions[name].routes` of the OpenNext config.
+ *
+ * i.e. `pages/index`, `pages/blog/[slug]`, `app/page`, `app/blog/[slug]/page`, ...
+ *
+ * @param route The resolved route
+ * @returns The candidate route templates (app routes may have several because of route groups)
+ */
+export declare function getRouteTemplates(route: ResolvedRoute): string[];
+/**
+ * Returns whether the route is served by the current function.
+ *
+ * Routes that are not listed in any split function are served by the default function.
+ * Paths that do not match any route are considered local so that Next handles them.
+ *
+ * @param route The resolved route
+ * @returns `true` when the route is served by the current function
+ */
+export declare function isServedByCurrentFunction(route: ResolvedRoute | undefined): boolean;
+/**
+ * Revalidate a page served by another function by sending a `HEAD` request to the app.
+ *
+ * Only the revalidate headers provided by Next are forwarded (no cookies).
+ * The function serving the page takes care of the CDN invalidation.
+ *
+ * TODO: the host comes from the request headers, use a trusted origin instead.
+ *
+ * @param args The arguments passed by Next to `revalidate`
+ * @throws When the host is unknown or the page has not been revalidated
+ */
+export declare function revalidateRemote({ urlPath, headers, revalidateHeaders, opts, }: RevalidateArgs): Promise<void>;
+/**
+ * Wrap `NextNodeServer#revalidate` used by `res.revalidate()` in the Pages Router API routes.
+ *
+ * - Pages served by the current function are revalidated in-process, then invalidated in the CDN.
+ * - Pages served by another split function are revalidated with a `HEAD` request.
+ *
+ * `NextNodeServer#revalidate` is exposed to `res.revalidate()` by a build time patch,
+ * see `exposeRevalidateRule` in `build/patch/patches/patchNextServer.ts`.
+ *
+ * @param revalidateInProcess The original `NextNodeServer#revalidate`
+ * @returns The wrapped revalidate function
+ */
+export declare function createRevalidate(revalidateInProcess: RevalidateFn): RevalidateFn;

package/dist/core/revalidate.js

@@ -0,0 +1,143 @@
+import { AppPathRoutesManifest } from "../adapters/config/index.js";
+import { NEXTJS_CACHE_HEADER } from "../utils/cacheHeaders.js";
+import { RequestCache } from "../utils/requestCache.js";
+import { debug, error } from "../adapters/logger";
+import { dynamicRouteMatcher, staticRouteMatcher, } from "./routing/routeMatcher";
+/**
+ * Timeout of the request revalidating a page served by another function.
+ */
+const REMOTE_REVALIDATE_TIMEOUT_MS = 30_000;
+/**
+ * Resolve the route of a path.
+ *
+ * Static routes take precedence over dynamic routes, as in Next.
+ *
+ * @param urlPath The path passed to `res.revalidate()`, may include the basePath and a locale
+ * @returns The resolved route or `undefined` when no route matches
+ */
+export function resolveRoute(urlPath) {
+    const pathname = urlPath.split(/[?#]/)[0];
+    return staticRouteMatcher(pathname)[0] ?? dynamicRouteMatcher(pathname)[0];
+}
+/**
+ * Convert a resolved route to the format used in `functions[name].routes` of the OpenNext config.
+ *
+ * i.e. `pages/index`, `pages/blog/[slug]`, `app/page`, `app/blog/[slug]/page`, ...
+ *
+ * @param route The resolved route
+ * @returns The candidate route templates (app routes may have several because of route groups)
+ */
+export function getRouteTemplates(route) {
+    if (route.type === "page") {
+        return [`pages${route.route === "/" ? "/index" : route.route}`];
+    }
+    return Object.entries(AppPathRoutesManifest)
+        .filter(([, path]) => path === route.route)
+        .map(([appPath]) => `app${appPath}`);
+}
+/**
+ * Returns whether the route is served by the current function.
+ *
+ * Routes that are not listed in any split function are served by the default function.
+ * Paths that do not match any route are considered local so that Next handles them.
+ *
+ * @param route The resolved route
+ * @returns `true` when the route is served by the current function
+ */
+export function isServedByCurrentFunction(route) {
+    const functions = globalThis.openNextConfig?.functions ?? {};
+    if (!route || Object.keys(functions).length === 0) {
+        return true;
+    }
+    const templates = getRouteTemplates(route);
+    const owner = Object.entries(functions).find(([, fn]) => fn.routes?.some((r) => templates.includes(r)))?.[0];
+    // `globalThis.fnName` is `undefined` in the default function
+    return owner === (globalThis.fnName || undefined);
+}
+/**
+ * Revalidate a page served by another function by sending a `HEAD` request to the app.
+ *
+ * Only the revalidate headers provided by Next are forwarded (no cookies).
+ * The function serving the page takes care of the CDN invalidation.
+ *
+ * TODO: the host comes from the request headers, use a trusted origin instead.
+ *
+ * @param args The arguments passed by Next to `revalidate`
+ * @throws When the host is unknown or the page has not been revalidated
+ */
+export async function revalidateRemote({ urlPath, headers, revalidateHeaders, opts, }) {
+    const host = globalThis.__openNextAls.getStore()?.host;
+    if (!host) {
+        throw new Error(`Unable to revalidate ${urlPath}: unknown host`);
+    }
+    const requestHeaders = new Headers();
+    for (const [key, value] of Object.entries(headers ?? revalidateHeaders ?? {})) {
+        if (value === undefined)
+            continue;
+        for (const v of Array.isArray(value) ? value : [value]) {
+            requestHeaders.append(key, v);
+        }
+    }
+    const url = `https://${host}${urlPath}`;
+    debug("Revalidating page served by another function", { url });
+    const res = await globalThis.internalFetch(url, {
+        method: "HEAD",
+        headers: requestHeaders,
+        redirect: "manual",
+        signal: AbortSignal.timeout(REMOTE_REVALIDATE_TIMEOUT_MS),
+    });
+    // Same check as Next, see `NextNodeServer#revalidate`
+    if (res.headers.get(NEXTJS_CACHE_HEADER)?.toUpperCase() !== "REVALIDATED" &&
+        res.status !== 200 &&
+        !(res.status === 404 && opts.unstable_onlyGenerated)) {
+        throw new Error(`Invalid response ${res.status}`);
+    }
+}
+/**
+ * Wrap `NextNodeServer#revalidate` used by `res.revalidate()` in the Pages Router API routes.
+ *
+ * - Pages served by the current function are revalidated in-process, then invalidated in the CDN.
+ * - Pages served by another split function are revalidated with a `HEAD` request.
+ *
+ * `NextNodeServer#revalidate` is exposed to `res.revalidate()` by a build time patch,
+ * see `exposeRevalidateRule` in `build/patch/patches/patchNextServer.ts`.
+ *
+ * @param revalidateInProcess The original `NextNodeServer#revalidate`
+ * @returns The wrapped revalidate function
+ */
+export function createRevalidate(revalidateInProcess) {
+    return async (args) => {
+        const route = resolveRoute(args.urlPath);
+        if (!isServedByCurrentFunction(route)) {
+            return revalidateRemote(args);
+        }
+        // Render the page in a context isolated from the API route request
+        // so that per-request state (i.e. `lastModified`, request cache) does not leak.
+        // The promise runner and `waitUntil` are shared to keep background work alive.
+        const store = globalThis.__openNextAls.getStore();
+        const renderInProcess = () => revalidateInProcess(args);
+        // Throws when the page has not been revalidated
+        await (store
+            ? globalThis.__openNextAls.run({
+                ...store,
+                lastModified: undefined,
+                writtenTags: new Set(),
+                requestCache: new RequestCache(),
+            }, renderInProcess)
+            : renderInProcess());
+        const path = args.urlPath.split(/[?#]/)[0];
+        try {
+            await globalThis.cdnInvalidationHandler?.invalidatePaths([
+                {
+                    initialPath: path,
+                    rawPath: path,
+                    resolvedRoutes: route ? [route] : [{ route: path, type: "page" }],
+                },
+            ]);
+        }
+        catch (e) {
+            // The page has been revalidated, only the CDN may serve stale content
+            error(`Failed to invalidate ${path} in the CDN`, e);
+        }
+    };
+}

package/dist/core/util.js

@@ -3,6 +3,7 @@ import { AppPathsManifestKeys, NextConfig, RoutesManifest, } from "../adapters/c
 import NextServer from "next/dist/server/next-server.js";
 import { debug, error } from "../adapters/logger.js";
 import { applyOverride as applyNextjsRequireHooksOverride, overrideHooks as overrideNextjsRequireHooks, } from "./require-hooks.js";
+import { createRevalidate } from "./revalidate.js";
 // WORKAROUND: Set `__NEXT_PRIVATE_PREBUNDLED_REACT` to use prebundled Reac
 // See https://opennext.js.org/aws/v2/advanced/workaround#workaround-set-__next_private_prebundled_react-to-use-prebundled-react
 // Step 1: Need to override the require hooks for React before Next.js server
@@ -67,6 +68,10 @@ const nextServer = new NextServer.default({
     dev: false,
     dir: __dirname,
 });
+// `res.revalidate()` in Pages Router API routes (Next 15.4+)
+if (typeof nextServer.revalidate === "function") {
+    nextServer.revalidate = createRevalidate(nextServer.revalidate.bind(nextServer));
+}
 let routesLoaded = false;
 globalThis.__next_route_preloader = async (stage) => {
     if (routesLoaded) {

package/dist/overrides/cdnInvalidation/cloudfront.js

@@ -11,7 +11,8 @@ export default {
                 ? [`/${path}`, `/${path}?_rsc=*`]
                 : [
                     `/${path}`,
-                    `/_next/data/${process.env.OPEN_NEXT_BUILD_ID}${path === "/" ? "/index" : `/${path}`}.json*`,
+                    // Data URLs are generated by Next and use the Next build id, not the Open Next build id
+                    `/_next/data/${process.env.NEXT_BUILD_ID}${path === "/" ? "/index" : `/${path}`}.json*`,
                 ];
         });
         await cloudfront.send(new CreateInvalidationCommand({

package/dist/plugins/edge.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
-import { loadAppPathRoutesManifest, loadAppPathsManifest, loadAppPathsManifestKeys, loadBuildId, loadConfig, loadConfigHeaders, loadFunctionsConfigManifest, loadHtmlPages, loadMiddlewareManifest, loadPagesManifest, loadPrerenderManifest, loadRoutesManifest, } from "../adapters/config/util.js";
+import { getOpenNextBuildId, loadAppPathRoutesManifest, loadAppPathsManifest, loadAppPathsManifestKeys, loadBuildId, loadConfig, loadConfigHeaders, loadFunctionsConfigManifest, loadHtmlPages, loadMiddlewareManifest, loadPagesManifest, loadPrerenderManifest, loadRoutesManifest, } from "../adapters/config/util.js";
 import logger from "../logger.js";
 import { normalizePath } from "../utils/normalize-path.js";
 import { getCrossPlatformPathRegex } from "../utils/regex.js";
@@ -109,6 +109,7 @@ ${contents}
             build.onLoad({ filter: getCrossPlatformPathRegex("adapters/config/index") }, async () => {
                 const NextConfig = loadConfig(nextDir);
                 const BuildId = loadBuildId(nextDir);
+                const OpenNextBuildId = getOpenNextBuildId(NextConfig, BuildId);
                 const HtmlPages = loadHtmlPages(nextDir);
                 const RoutesManifest = loadRoutesManifest(nextDir);
                 const ConfigHeaders = loadConfigHeaders(nextDir);
@@ -145,7 +146,7 @@ ${contents}
   export const PagesManifest = ${JSON.stringify(PagesManifest)};
 
   process.env.NEXT_BUILD_ID = BuildId;
-  process.env.OPEN_NEXT_BUILD_ID = NextConfig.deploymentId ?? BuildId;
+  process.env.OPEN_NEXT_BUILD_ID = ${JSON.stringify(OpenNextBuildId)};
   process.env.NEXT_PREVIEW_MODE_ID = PrerenderManifest?.preview?.previewModeId;
 `;
                 return { contents };

package/dist/types/cache.d.ts

@@ -57,11 +57,22 @@ export interface CacheHandlerContext {
     _requestHeaders: never;
     fetchCacheKeyPrefix?: string;
 }
+/**
+ * The lifetime of a cache entry, as Next.js passes it to `set()` in `ctx.cacheControl`.
+ */
+export interface CacheControl {
+    revalidate: number | false;
+    expire?: number;
+}
 export interface CacheHandlerValue {
     lastModified?: number;
     age?: number;
     cacheState?: string;
     value: IncrementalCacheValue | null;
+    /**
+     * The lifetime of the entry, only read by Next.js 16.4+.
+     */
+    cacheControl?: CacheControl;
 }
 export type Extension = "cache" | "fetch" | "composable";
 type MetaHeaders = {
@@ -104,10 +115,7 @@ interface SetIncrementalFetchCacheContext {
 }
 interface SetIncrementalResponseCacheContext {
     fetchCache?: false;
-    cacheControl?: {
-        revalidate: number | false;
-        expire?: number;
-    };
+    cacheControl?: CacheControl;
     /**
      * True if the route is enabled for PPR.
      */

package/dist/types/global.d.ts

@@ -58,6 +58,13 @@ interface OpenNextRequestContext {
     writtenTags: Set<string>;
     /** Per-request in-memory cache. Overrides can use this to store data scoped to the current request. */
     requestCache: RequestCache;
+    /**
+     * Host of the request (`x-forwarded-host` or `host` header).
+     *
+     * Used by `res.revalidate()` to revalidate pages served by another split function.
+     * Only available in main functions.
+     */
+    host?: string;
 }
 declare global {
     /**

package/dist/types/open-next.d.ts

@@ -192,7 +192,10 @@ export interface InstallOptions {
     packages: string[];
     /** @default undefined */
     arch?: "x64" | "arm64";
-    /** @default undefined */
+    /**
+     * @default undefined
+     * @deprecated npm no longer supports the `--target` flag, so this option is ignored.
+     */
     nodeVersion?: string;
     /** @default undefined */
     libc?: "glibc" | "musl";

package/dist/types/overrides.d.ts

@@ -98,6 +98,11 @@ export type CacheValue<CacheType extends CacheEntryType> = (CacheType extends "f
      * This is available for page cache entry, but only at runtime.
      */
     revalidate?: number | false;
+    /**
+     * This is available for page cache entry, but only at runtime.
+     * The cache interceptor does not use it.
+     */
+    expire?: number;
 };
 export type IncrementalCache = {
     get<CacheType extends CacheEntryType = "cache">(key: string, cacheType?: CacheType): Promise<WithLastModified<CacheValue<CacheType>> | null>;
@@ -240,12 +245,54 @@ export type OriginResolver = BaseOverride & {
 export type ProxyExternalRequest = BaseOverride & {
     proxy: (event: InternalEvent) => Promise<InternalResult>;
 };
+/**
+ * Describes a path whose CDN entries must be invalidated.
+ *
+ * Includes the path before and after routing as well as the routes that matched
+ * while resolving the request.
+ */
 type CDNPath = {
+    /** The original request pathname before route resolution. */
     initialPath: string;
+    /** The effective request pathname after route resolution. */
     rawPath: string;
+    /** The routes that matched while resolving the request. */
     resolvedRoutes: ResolvedRoute[];
 };
+/**
+ * Invalidates CDN entries after on-demand revalidation.
+ *
+ * Implementations must support path invalidation and may additionally support
+ * native cache-tag invalidation.
+ */
 export type CDNInvalidationHandler = BaseOverride & {
+    /**
+     * Invalidates CDN entries associated with resolved paths.
+     *
+     * @param paths Paths and routing metadata for the entries to invalidate.
+     * @returns A promise that resolves when invalidation is complete.
+     */
     invalidatePaths: (paths: CDNPath[]) => Promise<void>;
+    /**
+     * Invalidates CDN entries associated with cache tags.
+     *
+     * Called once per `revalidateTag` call, after the tag cache has been updated,
+     * with the tags passed to Next.js as is: hard tags from `revalidateTag()` and
+     * soft tags (prefixed with `_N_T_/`) from `revalidatePath()`. Tags are not
+     * expanded, i.e. the hard tags of the paths matching a soft tag are not added.
+     *
+     * When provided, `invalidatePaths` is no longer called for tag revalidation.
+     * It is still used for `res.revalidate()` in the Pages Router.
+     * When omitted, OpenNext resolves the tags to paths and calls `invalidatePaths`.
+     *
+     * The CDN integration must associate cached entries with the same tags, both
+     * hard and soft, for invalidation to have an effect. For response-based CDN
+     * caches, the wrapper or converter must propagate the request's cache tags to
+     * the provider's response metadata.
+     *
+     * @param tags Cache tags associated with the entries to invalidate.
+     * @returns A promise that resolves when invalidation is complete.
+     */
+    invalidateTags?: (tags: string[]) => Promise<void>;
 };
 export {};

package/dist/utils/cache.js

@@ -45,7 +45,7 @@ export function getStaleLastModified(revalidate) {
         return 1;
     }
     if (typeof revalidate !== "number") {
-        // Without a revalidate value Next cannot derive an expire time either,
+        // The cache adapter then reports `{ revalidate: 1 }` without `expire` (see `getCacheControl`),
         // so the historical sentinel is still safe here.
         return 1;
     }

package/package.json

@@ -3,7 +3,7 @@
     "access": "public"
   },
   "name": "@opennextjs/aws",
-  "version": "4.1.13",
+  "version": "4.1.14",
   "bin": {
     "open-next": "./dist/index.js"
   },