feat(Vercel) Build cache improvements

package.json

@@ -17,6 +17,7 @@
     "dev:developer-docs": "yarn enforce-redirects && NEXT_PUBLIC_DEVELOPER_DOCS=1 yarn dev",
     "build:developer-docs": "yarn enforce-redirects && git submodule init && git submodule update && NEXT_PUBLIC_DEVELOPER_DOCS=1 yarn build",
     "build": "yarn enforce-redirects && next build && yarn generate-md-exports",
+    "build:preview": "yarn enforce-redirects && next build",
     "generate-md-exports": "node scripts/generate-md-exports.mjs",
     "vercel:build:developer-docs": "yarn enforce-redirects && git submodule init && git submodule update && NEXT_PUBLIC_DEVELOPER_DOCS=1 yarn build",
     "start:dev": "NODE_ENV=development yarn build && yarn start",

src/docTree.ts

@@ -39,9 +39,11 @@ export function getDocsRootNode(): Promise<DocNode> {
 }
 
 async function getDocsRootNodeUncached(): Promise<DocNode> {
-  return frontmatterToTree(
-    await (isDeveloperDocs ? getDevDocsFrontMatter() : getDocsFrontMatter())
-  );
+  const frontmatter = await (isDeveloperDocs
+    ? getDevDocsFrontMatter()
+    : getDocsFrontMatter());
+  const tree = frontmatterToTree(frontmatter);
+  return tree;
 }
 
 const sidebarOrderSorter = (a: FrontMatter, b: FrontMatter) => {

src/mdx.ts

@@ -65,6 +65,55 @@ if (process.env.CI) {
   mkdirSync(CACHE_DIR, {recursive: true});
 }
 
+// Cache registry hash per worker to avoid recomputing for every file
+let cachedRegistryHash: string | null = null;
+async function getRegistryHash(): Promise<string> {
+  if (cachedRegistryHash) {
+    return cachedRegistryHash;
+  }
+  const [apps, packages] = await Promise.all([getAppRegistry(), getPackageRegistry()]);
+  cachedRegistryHash = md5(JSON.stringify({apps, packages}));
+  return cachedRegistryHash;
+}
+
+// Track cache statistics per worker (silent tracking)
+const cacheStats = {
+  registryHits: 0,
+  registryMisses: 0,
+  uniqueRegistryFiles: new Set<string>(),
+};
+
+// Log summary periodically and at end
+let lastSummaryLog = Date.now();
+function logCacheSummary(force = false) {
+  const now = Date.now();
+  // Log every 30 seconds or when forced
+  if (!force && now - lastSummaryLog < 30000) {
+    return;
+  }
+  lastSummaryLog = now;
+
+  const total = cacheStats.registryHits + cacheStats.registryMisses;
+  if (total === 0) {
+    return;
+  }
+
+  const hitRate = ((cacheStats.registryHits / total) * 100).toFixed(1);
+  const uniqueFiles = cacheStats.uniqueRegistryFiles.size;
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `📊 [MDX Cache] ${cacheStats.registryHits}/${total} registry files cached (${hitRate}% hit rate, ${uniqueFiles} unique files)`
+  );
+}
+
+// Log final summary when worker exits
+if (typeof process !== 'undefined') {
+  process.on('beforeExit', () => {
+    logCacheSummary(true);
+  });
+}
+
 const md5 = (data: BinaryLike) => createHash('md5').update(data).digest('hex');
 
 async function readCacheFile<T>(file: string): Promise<T> {
@@ -209,6 +258,7 @@ export async function getDevDocsFrontMatterUncached(): Promise<FrontMatter[]> {
       )
     )
   ).filter(isNotNil);
+
   return frontMatters;
 }
 
@@ -396,6 +446,7 @@ async function getAllFilesFrontMatter(): Promise<FrontMatter[]> {
       );
     }
   }
+
   return allFrontMatter;
 }
 
@@ -531,22 +582,37 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
   const outdir = path.join(root, 'public', 'mdx-images');
   await mkdir(outdir, {recursive: true});
 
-  // If the file contains content that depends on the Release Registry (such as an SDK's latest version), avoid using the cache for that file, i.e. always rebuild it.
-  // This is because the content from the registry might have changed since the last time the file was cached.
-  // If a new component that injects content from the registry is introduced, it should be added to the patterns below.
-  const skipCache =
+  // Check if file depends on Release Registry
+  const dependsOnRegistry =
     source.includes('@inject') ||
     source.includes('<PlatformSDKPackageName') ||
     source.includes('<LambdaLayerDetail');
 
   if (process.env.CI) {
-    if (skipCache) {
-      // eslint-disable-next-line no-console
-      console.info(
-        `Not using cached version of ${sourcePath}, as its content depends on the Release Registry`
-      );
+    // Build cache key from source content
+    const sourceHash = md5(source);
+
+    // For files that depend on registry, include registry version in cache key
+    // This prevents serving stale content when registry is updated
+    if (dependsOnRegistry) {
+      try {
+        // Get registry hash (cached per worker to avoid redundant fetches)
+        const registryHash = await getRegistryHash();
+        cacheKey = `${sourceHash}-${registryHash}`;
+      } catch (err) {
+        // If registry fetch fails, skip caching for safety
+        // eslint-disable-next-line no-console
+        console.warn(
+          `Failed to fetch registry for cache key, skipping cache: ${err.message}`
+        );
+        cacheKey = null;
+      }
     } else {
-      cacheKey = md5(source);
+      // Regular files without registry dependencies
+      cacheKey = sourceHash;
+    }
+
+    if (cacheKey) {
       cacheFile = path.join(CACHE_DIR, `${cacheKey}.br`);
       assetsCacheDir = path.join(CACHE_DIR, cacheKey);
 
@@ -555,6 +621,12 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
           readCacheFile<SlugFile>(cacheFile),
           cp(assetsCacheDir, outdir, {recursive: true}),
         ]);
+        // Track cache hit silently
+        if (dependsOnRegistry) {
+          cacheStats.registryHits++;
+          cacheStats.uniqueRegistryFiles.add(sourcePath);
+          logCacheSummary(); // Periodically log summary (every 30s)
+        }
         return cached;
       } catch (err) {
         if (
@@ -570,6 +642,13 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
     }
   }
 
+  // Track cache miss silently
+  if (dependsOnRegistry) {
+    cacheStats.registryMisses++;
+    cacheStats.uniqueRegistryFiles.add(sourcePath);
+    logCacheSummary(); // Periodically log summary (every 30s)
+  }
+
   process.env.ESBUILD_BINARY_PATH = path.join(
     root,
     'node_modules',
@@ -700,7 +779,8 @@ export async function getFileBySlug(slug: string): Promise<SlugFile> {
     },
   };
 
-  if (assetsCacheDir && cacheFile && !skipCache) {
+  // Save to cache if we have a cache key (we now cache everything, including registry-dependent files)
+  if (assetsCacheDir && cacheFile && cacheKey) {
     await cp(assetsCacheDir, outdir, {recursive: true});
     writeCacheFile(cacheFile, JSON.stringify(resultObj)).catch(e => {
       // eslint-disable-next-line no-console

vercel.json

@@ -1,4 +1,6 @@
 {
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "sh vercel.sh",
   "headers": [
     {
       "source": "/(.*)",

vercel.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+if [[ $VERCEL_ENV == "production"  ]] ; then
+  yarn run build
+else
+  yarn run build:preview
+fi