src: add an option to make compile cache portable

Aditi-1400 · Aditi-1400 · commit d03bf275a3c1 · 2025-08-11T22:00:15.000+05:30
Adds an option (NODE_COMPILE_CACHE_PORTABLE) for
the built-in compile cache to encode the hashes with
relative file paths. On enabling the option,
the source directory along with cache directory can be
bundled and moved, and the cache continues to work.

When enabled, paths encoded in hash are relative to
compile cache directory.
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -3284,6 +3284,10 @@ added: v22.1.0
 Enable the [module compile cache][] for the Node.js instance. See the documentation of
 [module compile cache][] for details.
 
+### `NODE_COMPILE_CACHE_PORTABLE=1`
+
+When set to 1, the path for [module compile cache][] is considered relative.
+
 ### `NODE_DEBUG=module[,…]`
 
 <!-- YAML
diff --git a/doc/api/module.md b/doc/api/module.md
@@ -399,6 +399,28 @@ the [`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or defaults
 to `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. To locate the compile cache
 directory used by a running Node.js instance, use [`module.getCompileCacheDir()`][].
 
+By default, caches are invalidated when the absolute paths of the modules being
+cached are changed. To keep the cache working after moving the
+project directory, enable portable compile cache. This allows previously compiled
+modules to be reused across different directory locations as long as the layout relative
+to the cache directory remains the same. This would be done on a best-effort basis. If
+Node.js cannot compute the location of a module relative to the cache directory, the module
+will not be cached.
+
+There are two ways to enable the portable mode:
+
+1. Using the portable option in module.enableCompileCache():
+
+   ```js
+   // Absolute paths (default): cache breaks if project is moved
+   module.enableCompileCache({ path: '.cache' });
+
+   // Relative paths (portable): cache works after moving project
+   module.enableCompileCache({ path: '.cache', portable: true });
+   ```
+
+2. Setting the environment variable: [`NODE_COMPILE_CACHE_PORTABLE=1`][]
+
 Currently when using the compile cache with [V8 JavaScript code coverage][], the
 coverage being collected by V8 may be less precise in functions that are
 deserialized from the code cache. It's recommended to turn this off when
@@ -1789,6 +1811,7 @@ returned object contains the following keys:
 [`--import`]: cli.md#--importmodule
 [`--require`]: cli.md#-r---require-module
 [`NODE_COMPILE_CACHE=dir`]: cli.md#node_compile_cachedir
+[`NODE_COMPILE_CACHE_PORTABLE=1`]: cli.md#node_compile_cache_portable1
 [`NODE_DISABLE_COMPILE_CACHE=1`]: cli.md#node_disable_compile_cache1
 [`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir
 [`SourceMap`]: #class-modulesourcemap
diff --git a/doc/node.1 b/doc/node.1
@@ -718,6 +718,13 @@ Enable the
 .Sy module compile cache
 for the Node.js instance.
 .
+.It Ev NODE_COMPILE_CACHE_PORTABLE
+When set to '1' or 'true', the
+.Sy module compile cache
+will be hit as long as the location of the modules relative to the cache directory remain
+consistent. This can be used in conjunction with .Ev NODE_COMPILE_CACHE
+to enable portable on-disk caching.
+.
 .It Ev NODE_DEBUG Ar modules...
 Comma-separated list of core modules that should print debug information.
 .
diff --git a/lib/internal/modules/helpers.js b/lib/internal/modules/helpers.js
@@ -383,18 +383,31 @@ function stringify(body) {
 }
 
 /**
- * Enable on-disk compiled cache for all user modules being complied in the current Node.js instance
+ * Enable on-disk compiled cache for all user modules being compiled in the current Node.js instance
  * after this method is called.
- * If cacheDir is undefined, defaults to the NODE_MODULE_CACHE environment variable.
- * If NODE_MODULE_CACHE isn't set, default to path.join(os.tmpdir(), 'node-compile-cache').
- * @param {string|undefined} cacheDir
+ * This method accepts either:
+ * - A string `cacheDir`: the path to the cache directory.
+ * - An options object `{path?: string, portable?: boolean}`:
+ *   - `path`: A string path to the cache directory.
+ *   - `portable`: If `portable` is true, the cache directory will be considered relative. Defaults to false.
+ * If cache path is undefined, it defaults to the NODE_MODULE_CACHE environment variable.
+ * If `NODE_MODULE_CACHE` isn't set, it defaults to `path.join(os.tmpdir(), 'node-compile-cache')`.
+ * @param {string | { path?: string, portable?: boolean } | undefined} options
  * @returns {{status: number, message?: string, directory?: string}}
  */
-function enableCompileCache(cacheDir) {
+function enableCompileCache(options) {
+  let cacheDir;
+  let portable = false;
+
+  if (typeof options === 'object' && options !== null) {
+    ({ path: cacheDir, portable = false } = options);
+  } else {
+    cacheDir = options;
+  }
   if (cacheDir === undefined) {
     cacheDir = join(lazyTmpdir(), 'node-compile-cache');
   }
-  const nativeResult = _enableCompileCache(cacheDir);
+  const nativeResult = _enableCompileCache(cacheDir, portable);
   const result = { status: nativeResult[0] };
   if (nativeResult[1]) {
     result.message = nativeResult[1];
diff --git a/src/compile_cache.cc b/src/compile_cache.cc
@@ -13,6 +13,9 @@
 #include <unistd.h>  // getuid
 #endif
 
+#ifdef _WIN32
+#include <windows.h>
+#endif
 namespace node {
 
 using v8::Function;
@@ -223,13 +226,48 @@ void CompileCacheHandler::ReadCacheFile(CompileCacheEntry* entry) {
   Debug(" success, size=%d\n", total_read);
 }
 
+static std::string GetRelativePath(std::string_view path,
+                                   std::string_view base) {
+// On Windows, the native encoding is UTF-16, so we need to convert
+// the paths to wide strings before using std::filesystem::path.
+// On other platforms, std::filesystem::path can handle UTF-8 directly.
+#ifdef _WIN32
+  std::filesystem::path module_path(
+      ConvertToWideString(std::string(path), CP_UTF8));
+  std::filesystem::path base_path(
+      ConvertToWideString(std::string(base), CP_UTF8));
+#else
+  std::filesystem::path module_path(path);
+  std::filesystem::path base_path(base);
+#endif
+  std::filesystem::path relative = module_path.lexically_relative(base_path);
+  auto u8str = relative.u8string();
+  return std::string(u8str.begin(), u8str.end());
+}
+
 CompileCacheEntry* CompileCacheHandler::GetOrInsert(Local<String> code,
                                                     Local<String> filename,
                                                     CachedCodeType type) {
   DCHECK(!compile_cache_dir_.empty());
 
+  Environment* env = Environment::GetCurrent(isolate_->GetCurrentContext());
   Utf8Value filename_utf8(isolate_, filename);
-  uint32_t key = GetCacheKey(filename_utf8.ToStringView(), type);
+  std::string file_path = filename_utf8.ToString();
+  // If the relative path is enabled, we try to use a relative path
+  // from the compile cache directory to the file path
+  if (portable_ && IsAbsoluteFilePath(file_path)) {
+    // Normalize the path to ensure it is consistent.
+    std::string normalized_file_path = NormalizeFileURLOrPath(env, file_path);
+    std::string relative_path =
+        GetRelativePath(normalized_file_path, normalized_compile_cache_dir_);
+    if (!relative_path.empty()) {
+      file_path = relative_path;
+      Debug("[compile cache] using relative path %s from %s\n",
+            file_path.c_str(),
+            absolute_compile_cache_dir_.c_str());
+    }
+  }
+  uint32_t key = GetCacheKey(file_path, type);
 
   // TODO(joyeecheung): don't encode this again into UTF8. If we read the
   // UTF8 content on disk as raw buffer (from the JS layer, while watching out
@@ -500,11 +538,15 @@ CompileCacheHandler::CompileCacheHandler(Environment* env)
 //   - $NODE_VERSION-$ARCH-$CACHE_DATA_VERSION_TAG-$UID
 //     - $FILENAME_AND_MODULE_TYPE_HASH.cache: a hash of filename + module type
 CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
-                                                     const std::string& dir) {
+                                                     const std::string& dir,
+                                                     bool portable) {
   std::string cache_tag = GetCacheVersionTag();
-  std::string absolute_cache_dir_base = PathResolve(env, {dir});
-  std::string cache_dir_with_tag =
-      absolute_cache_dir_base + kPathSeparator + cache_tag;
+  std::string base_dir = dir;
+  if (!portable) {
+    base_dir = PathResolve(env, {dir});
+  }
+
+  std::string cache_dir_with_tag = base_dir + kPathSeparator + cache_tag;
   CompileCacheEnableResult result;
   Debug("[compile cache] resolved path %s + %s -> %s\n",
         dir,
@@ -546,8 +588,11 @@ CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
     return result;
   }
 
-  result.cache_directory = absolute_cache_dir_base;
+  result.cache_directory = base_dir;
   compile_cache_dir_ = cache_dir_with_tag;
+  absolute_compile_cache_dir_ = PathResolve(env, {compile_cache_dir_});
+  portable_ = portable;
+  normalized_compile_cache_dir_ = NormalizeFileURLOrPath(env, absolute_compile_cache_dir_);
   result.status = CompileCacheEnableStatus::ENABLED;
   return result;
 }
diff --git a/src/compile_cache.h b/src/compile_cache.h
@@ -65,7 +65,9 @@ struct CompileCacheEnableResult {
 class CompileCacheHandler {
  public:
   explicit CompileCacheHandler(Environment* env);
-  CompileCacheEnableResult Enable(Environment* env, const std::string& dir);
+  CompileCacheEnableResult Enable(Environment* env,
+                                  const std::string& dir,
+                                  bool portable);
 
   void Persist();
 
@@ -103,6 +105,9 @@ class CompileCacheHandler {
   bool is_debug_ = false;
 
   std::string compile_cache_dir_;
+  std::string absolute_compile_cache_dir_;
+  std::string normalized_compile_cache_dir_;
+  bool portable_ = false;
   std::unordered_map<uint32_t, std::unique_ptr<CompileCacheEntry>>
       compiler_cache_store_;
 };
diff --git a/src/env.cc b/src/env.cc
@@ -1122,11 +1122,21 @@ void Environment::InitializeCompileCache() {
       dir_from_env.empty()) {
     return;
   }
-  EnableCompileCache(dir_from_env);
+  std::string portable_env;
+  bool portable = credentials::SafeGetenv(
+                      "NODE_COMPILE_CACHE_PORTABLE", &portable_env, this) &&
+                  !portable_env.empty() &&
+                  (portable_env == "1" || portable_env == "true");
+  if (portable) {
+    Debug(this,
+          DebugCategory::COMPILE_CACHE,
+          "[compile cache] using relative path\n");
+  }
+  EnableCompileCache(dir_from_env, portable);
 }
 
 CompileCacheEnableResult Environment::EnableCompileCache(
-    const std::string& cache_dir) {
+    const std::string& cache_dir, bool portable) {
   CompileCacheEnableResult result;
   std::string disable_env;
   if (credentials::SafeGetenv(
@@ -1143,7 +1153,7 @@ CompileCacheEnableResult Environment::EnableCompileCache(
   if (!compile_cache_handler_) {
     std::unique_ptr<CompileCacheHandler> handler =
         std::make_unique<CompileCacheHandler>(this);
-    result = handler->Enable(this, cache_dir);
+    result = handler->Enable(this, cache_dir, portable);
     if (result.status == CompileCacheEnableStatus::ENABLED) {
       compile_cache_handler_ = std::move(handler);
       AtExit(
diff --git a/src/env.h b/src/env.h
@@ -1022,7 +1022,8 @@ class Environment final : public MemoryRetainer {
   void InitializeCompileCache();
   // Enable built-in compile cache if it has not yet been enabled.
   // The cache will be persisted to disk on exit.
-  CompileCacheEnableResult EnableCompileCache(const std::string& cache_dir);
+  CompileCacheEnableResult EnableCompileCache(const std::string& cache_dir,
+                                              bool portable);
   void FlushCompileCache();
 
   void RunAndClearNativeImmediates(bool only_refed = false);
diff --git a/src/node_file.h b/src/node_file.h
@@ -531,6 +531,8 @@ int SyncCallAndThrowOnError(Environment* env,
                             FSReqWrapSync* req_wrap,
                             Func fn,
                             Args... args);
+
+std::string ConvertWideToUTF8(const std::wstring& wstr);
 }  // namespace fs
 
 }  // namespace node
diff --git a/src/node_modules.cc b/src/node_modules.cc
@@ -513,8 +513,14 @@ void EnableCompileCache(const FunctionCallbackInfo<Value>& args) {
     THROW_ERR_INVALID_ARG_TYPE(env, "cacheDir should be a string");
     return;
   }
+
+  bool portable = false;
+  if (args.Length() > 1 && args[1]->IsTrue()) {
+    portable = true;
+  }
+
   Utf8Value value(isolate, args[0]);
-  CompileCacheEnableResult result = env->EnableCompileCache(*value);
+  CompileCacheEnableResult result = env->EnableCompileCache(*value, portable);
   Local<Value> values[3];
   values[0] = v8::Integer::New(isolate, static_cast<uint8_t>(result.status));
   if (ToV8Value(context, result.message).ToLocal(&values[1]) &&
diff --git a/src/path.cc b/src/path.cc
@@ -1,8 +1,10 @@
 #include "path.h"
 #include <string>
 #include <vector>
+#include "ada.h"
 #include "env-inl.h"
 #include "node_internals.h"
+#include "node_url.h"
 
 namespace node {
 
@@ -88,6 +90,10 @@ std::string NormalizeString(const std::string_view path,
 }
 
 #ifdef _WIN32
+constexpr bool IsWindowsDriveLetter(const std::string_view path) noexcept {
+  return path.size() > 2 && IsWindowsDeviceRoot(path[0]) &&
+         (path[1] == ':' && (path[2] == '/' || path[2] == '\\'));
+}
 constexpr bool IsWindowsDeviceRoot(const char c) noexcept {
   return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
 }
@@ -333,4 +339,42 @@ void FromNamespacedPath(std::string* path) {
 #endif
 }
 
+// Check if a path looks like an absolute path or file URL.
+bool IsAbsoluteFilePath(std::string_view path) {
+  if (path.rfind("file://", 0) == 0) {
+    return true;
+  }
+#ifdef _WIN32
+  if (path.size() > 0 && path[0] == '\\') return true;
+  if (IsWindowsDriveLetter(path)) return true;
+#endif
+  if (path.size() > 0 && path[0] == '/') return true;
+  return false;
+}
+
+// Normalizes paths by resolving file URLs and converting to a consistent
+// format with forward slashes.
+std::string NormalizeFileURLOrPath(Environment* env, std::string_view path) {
+  std::string normalized_string(path);
+  constexpr std::string_view file_scheme = "file://";
+  if (normalized_string.rfind(file_scheme, 0) == 0) {
+    auto out = ada::parse<ada::url_aggregator>(normalized_string);
+    auto file_path = url::FileURLToPath(env, *out);
+    CHECK(file_path.has_value());
+    normalized_string = file_path.value();
+  }
+  normalized_string = NormalizeString(normalized_string, false, "/");
+#ifdef _WIN32
+  if (IsWindowsDriveLetter(normalized_string)) {
+    normalized_string[0] = ToLower(normalized_string[0]);
+  }
+  for (char& c : normalized_string) {
+    if (c == '\\') {
+      c = '/';
+    }
+  }
+#endif
+  return normalized_string;
+}
+
 }  // namespace node
diff --git a/src/path.h b/src/path.h
@@ -18,9 +18,12 @@ std::string NormalizeString(const std::string_view path,
 
 std::string PathResolve(Environment* env,
                         const std::vector<std::string_view>& paths);
+std::string NormalizeFileURLOrPath(Environment* env, std::string_view path);
+bool IsAbsoluteFilePath(std::string_view path);
 
 #ifdef _WIN32
 constexpr bool IsWindowsDeviceRoot(const char c) noexcept;
+constexpr bool IsWindowsDriveLetter(const std::string_view path) noexcept;
 #endif  // _WIN32
 
 void ToNamespacedPath(Environment* env, BufferValue* path);
diff --git a/test/parallel/test-compile-cache-api-error.js b/test/parallel/test-compile-cache-api-error.js
@@ -6,6 +6,6 @@ require('../common');
 const { enableCompileCache } = require('module');
 const assert = require('assert');
 
-for (const invalid of [0, null, false, () => {}, {}, []]) {
+for (const invalid of [0, null, false, 1, NaN, true, Symbol(0)]) {
   assert.throws(() => enableCompileCache(invalid), { code: 'ERR_INVALID_ARG_TYPE' });
 }
diff --git a/test/parallel/test-compile-cache-api-portable.js b/test/parallel/test-compile-cache-api-portable.js
diff --git a/test/parallel/test-compile-cache-portable-esm.js b/test/parallel/test-compile-cache-portable-esm.js
diff --git a/test/parallel/test-compile-cache-portable.js b/test/parallel/test-compile-cache-portable.js

Original file line number	Diff line number	Diff line change
`@@ -718,6 +718,13 @@ Enable the`
`718`	`718`	`.Sy module compile cache`
`719`	`719`	`for the Node.js instance.`
`720`	`720`	`.`
	`721`	`+.It Ev NODE_COMPILE_CACHE_PORTABLE`
	`722`	`+When set to '1' or 'true', the`
	`723`	`+.Sy module compile cache`
	`724`	`+will be hit as long as the location of the modules relative to the cache directory remain`
	`725`	`+consistent. This can be used in conjunction with .Ev NODE_COMPILE_CACHE`
	`726`	`+to enable portable on-disk caching.`
	`727`	`+.`
`721`	`728`	`.It Ev NODE_DEBUG Ar modules...`
`722`	`729`	`Comma-separated list of core modules that should print debug information.`
`723`	`730`	`.`