perf(build): gate cache→dist copy-skip behind experimental flag (#5418)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: adrians5j

scripts/buildPackages/src/buildPackages.ts

@@ -15,7 +15,7 @@ import path from "path";
 import { hideBin } from "yargs/helpers";
 import { PackageBuildError } from "./PackageBuildError";
 import { queueMetaWrite } from "./writeMetaQueue";
-import { writeDistBuildHash } from "./distBuildHash";
+import { writeDistBuildHash, isExperimentalBuildCacheEnabled } from "./distBuildHash";
 
 const argv = yargs(hideBin(process.argv)).parse();
 
@@ -90,13 +90,16 @@ export const buildPackages = async () => {
         try {
             await buildPackage(pkg, options.buildOverrides, "inherit", options.safeReplace);
 
-            // Record the source hash (in dist as a marker and in build meta) so
-            // a later build treats this package as a cache hit and skips the copy.
-            const sourceHash = await getPackageSourceHash(pkg);
-            writeDistBuildHash(pkg, sourceHash);
-            const meta = getBuildMeta();
-            meta.packages[pkg.packageJson.name] = { sourceHash };
-            writeJsonFileSync(META_FILE_PATH, meta);
+            // EXPERIMENTAL (opt-in): record the source hash (in dist as a marker
+            // and in build meta) so a later build treats this package as a cache
+            // hit and skips the copy. Off by default — see distBuildHash.ts.
+            if (isExperimentalBuildCacheEnabled()) {
+                const sourceHash = await getPackageSourceHash(pkg);
+                writeDistBuildHash(pkg, sourceHash);
+                const meta = getBuildMeta();
+                meta.packages[pkg.packageJson.name] = { sourceHash };
+                writeJsonFileSync(META_FILE_PATH, meta);
+            }
 
             sendNotification(`Webiny Build (${projectFolder})`, "Build completed successfully");
         } catch (err) {
@@ -140,9 +143,12 @@ export const buildPackages = async () => {
 
                                         // Store package hash
                                         const sourceHash = await getPackageSourceHash(pkg);
-                                        // Stamp dist so a later no-op build can
-                                        // skip the cache→dist copy for this package.
-                                        writeDistBuildHash(pkg, sourceHash);
+                                        // EXPERIMENTAL (opt-in): stamp dist so a
+                                        // later no-op build can skip the
+                                        // cache→dist copy for this package.
+                                        if (isExperimentalBuildCacheEnabled()) {
+                                            writeDistBuildHash(pkg, sourceHash);
+                                        }
                                         await queueMetaWrite(async () => {
                                             const currentMeta = getBuildMeta();
                                             currentMeta.packages[pkg.packageJson.name] = {

scripts/buildPackages/src/distBuildHash.ts

@@ -8,6 +8,19 @@ import type { Package } from "./types";
 // dist into place when the existing dist is already up to date.
 const MARKER = ".webiny-build-hash";
 
+/**
+ * Whether the experimental "skip cache→dist copy when dist is already fresh"
+ * optimization is enabled. OFF by default: the optimization trusts a dist
+ * marker, which can go stale if something writes dist out of band (e.g.
+ * `webiny watch`), so it is opt-in until that class of issues is fully solved.
+ *
+ * Enable with `WEBINY_EXPERIMENTAL_BUILD_CACHE=true` (or `1`).
+ */
+export function isExperimentalBuildCacheEnabled(): boolean {
+    const value = process.env.WEBINY_EXPERIMENTAL_BUILD_CACHE;
+    return value === "true" || value === "1";
+}
+
 const markerPath = (pkg: Package) => path.join(getBuildOutputFolder(pkg), MARKER);
 
 export function readDistBuildHash(pkg: Package): string | null {

scripts/buildPackages/src/getBatches.ts

@@ -9,7 +9,11 @@ import { getBuildOutputFolder } from "./getBuildOutputFolder";
 import { getPackageSourceHash } from "./getPackageSourceHash";
 import { getBuildMeta } from "./getBuildMeta";
 import { getPackageCacheFolderPath } from "./getPackageCacheFolderPath";
-import { distBuildHashMatches, writeDistBuildHash } from "./distBuildHash";
+import {
+    distBuildHashMatches,
+    writeDistBuildHash,
+    isExperimentalBuildCacheEnabled
+} from "./distBuildHash";
 
 const { green } = chalk;
 
@@ -119,25 +123,30 @@ export async function getBatches(options: GetBatchesOptions = {}) {
             }
         }
 
+        const experimentalCache = isExperimentalBuildCacheEnabled();
+
         let copied = 0;
         for (let i = 0; i < packagesUseCache.length; i++) {
             const workspacePackage = packagesUseCache[i];
             const sourceHash = cacheHitHashes.get(workspacePackage.name)!;
 
-            // Skip the copy when dist was already built/restored from this exact
-            // source hash — the bytes on disk are already identical. This is the
-            // common local-dev case (dist persists between builds).
-            if (distBuildHashMatches(workspacePackage, sourceHash)) {
+            // EXPERIMENTAL (opt-in): skip the copy when dist was already
+            // built/restored from this exact source hash — the bytes on disk are
+            // already identical. Off by default; the marker can go stale if
+            // something writes dist out of band (e.g. `webiny watch`).
+            if (experimentalCache && distBuildHashMatches(workspacePackage, sourceHash)) {
                 continue;
             }
 
             const cacheFolderPath = path.join(CACHE_FOLDER_PATH, workspacePackage.packageJson.name);
             fs.copySync(cacheFolderPath, getBuildOutputFolder(workspacePackage));
-            writeDistBuildHash(workspacePackage, sourceHash);
+            if (experimentalCache) {
+                writeDistBuildHash(workspacePackage, sourceHash);
+            }
             copied++;
         }
 
-        if (copied > 0) {
+        if (experimentalCache && copied > 0) {
             console.log(`Restored ${green(copied)} package(s) from cache into dist.`);
         }
     } else {