src: add an option to make compile cache path relative#58797

Aditi-1400 · 2025-06-23T00:06:25Z

Adds an option (NODE_COMPILE_CACHE_RELATIVE_PATH) 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.

Fixes: #58755
Refs: #52696

Thanks @joyeecheung for all the help :)

codecov · 2025-06-23T01:00:33Z

Codecov Report

❌ Patch coverage is 86.07595% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.89%. Comparing base (9bcc5a8) to head (b879f6b).
⚠️ Report is 319 commits behind head on main.

Files with missing lines	Patch %	Lines
src/compile_cache.cc	81.48%	1 Missing and 4 partials ⚠️
src/path.cc	73.68%	2 Missing and 3 partials ⚠️
src/env.cc	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #58797 +/- ## ========================================== + Coverage 89.37% 89.89% +0.52%  ========================================== Files 654 667 +13 Lines 192554 196670 +4116 Branches 37434 38617 +1183 ========================================== + Hits 172086 176794 +4708 + Misses 12995 12331 -664 - Partials 7473 7545 +72

Files with missing lines	Coverage Δ
lib/internal/modules/helpers.js	`98.29% <100.00%> (+0.92%)`	⬆️
src/compile_cache.h	`100.00% <ø> (ø)`
src/env.h	`98.14% <ø> (ø)`
src/node_modules.cc	`77.06% <100.00%> (-0.25%)`	⬇️
src/env.cc	`80.83% <87.50%> (-0.05%)`	⬇️
src/compile_cache.cc	`80.78% <81.48%> (-0.01%)`	⬇️
src/path.cc	`72.81% <73.68%> (+3.76%)`	⬆️

... and 195 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

joyeecheung

Can you add some integration to module.enableCompileCache() as well? I think having it in options bag when the first argument is an object might work well enough. The path can be options.path in that case.

doc/api/cli.md

src/compile_cache.cc

test/parallel/test-compile-cache-relative-path.js

doc/api/module.md

doc/node.1

src/compile_cache.cc

doc/api/module.md

src/compile_cache.cc

doc/api/module.md

src/compile_cache.cc

src/compile_cache.h

test/parallel/test-compile-cache-portable.js

jasnell

The file:// URL handling in this is incorrect. Either support for file:// URLs here at all should be dropped or they should be correctly handled.

nodejs-github-bot · 2025-09-08T15:22:48Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69131/

nodejs-github-bot · 2025-09-09T09:13:50Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69153/

nodejs-github-bot · 2025-09-11T16:39:37Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69186/

nodejs-github-bot · 2025-09-11T19:07:37Z

CI: https://ci.nodejs.org/job/node-test-pull-request/69189/

nodejs-github-bot · 2025-09-12T11:00:41Z

Landed in 94422e8

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. PR-URL: #58797Fixes: #58755 Refs: #52696 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: James M Snell <[email protected]>

joyeecheung · 2025-09-18T20:49:40Z

lib/internal/modules/helpers.js

+ * - `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


I just noticed an issue with the new options - it should be directory instead of path to align with the return value. Marking the PR with dont-land labels to fix it before it gets released.

Notable changes: http: * (SEMVER-MINOR) add shouldUpgradeCallback to let servers control HTTP upgrades (Tim Perry) #59824 sqlite: * (SEMVER-MINOR) cleanup ERM support and export Session class (James M Snell) #58378 * (SEMVER-MINOR) add tagged template (0hm☘️) #58748 src: * (SEMVER-MINOR) add an option to make compile cache portable (Aditi) #58797 worker: * (SEMVER-MINOR) add heap profile API (theanarkh) #59846 PR-URL: #59997

targos · 2025-10-10T07:18:07Z

#59896 (comment)

Should land with #59931

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. PR-URL: #58797Fixes: #58755 Refs: #52696 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: James M Snell <[email protected]>

Notable changes: http: * (SEMVER-MINOR) add optimizeEmptyRequests server option (Rafael Gonzaga) #59778 src: * (SEMVER-MINOR) add watch config namespace (Marco Ippolito) #60178 * (SEMVER-MINOR) add an option to make compile cache portable (Aditi) #58797 v8: * (SEMVER-MINOR) add cpu profile (theanarkh) #59807 PR-URL: #60615

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. PR-URL: #58797Fixes: #58755 Refs: #52696 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: James M Snell <[email protected]>

Notable changes: http: * (SEMVER-MINOR) add optimizeEmptyRequests server option (Rafael Gonzaga) #59778 lib: * (SEMVER-MINOR) add options to util.deprecate (Rafael Gonzaga) #59982 module: * (SEMVER-MINOR) mark type stripping as stable (Marco Ippolito) #60600 node-api: * (SEMVER-MINOR) add napi_create_object_with_properties (Miguel Marcondes Filho) #59953 sqlite: * (SEMVER-MINOR) allow setting defensive flag (Bart Louwers) #60217 src: * (SEMVER-MINOR) add watch config namespace (Marco Ippolito) #60178 * (SEMVER-MINOR) add an option to make compile cache portable (Aditi) #58797 src,permission: * (SEMVER-MINOR) add --allow-inspector ability (Rafael Gonzaga) #59711 v8: * (SEMVER-MINOR) add cpu profile (theanarkh) #59807 PR-URL: #61001

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jun 23, 2025

joyeecheung reviewed Jun 23, 2025
View reviewed changes

doc/api/cli.md Outdated Show resolvedHide resolved
src/compile_cache.cc Outdated Show resolvedHide resolved
test/parallel/test-compile-cache-relative-path.jsShow resolvedHide resolved

joyeecheung mentioned this pull request Jul 3, 2025
Tracking issue: compile cache #52696
Open
13 tasks

mcollina added the semver-minor PRs that contain new features and should be released in the next minor version. label Jul 4, 2025

Aditi-1400 force-pushed the compile-cache branch from 0d4fb87 to b6eb597Compare July 20, 2025 20:33

jasnell reviewed Jul 20, 2025
View reviewed changes

doc/api/module.md Outdated Show resolvedHide resolved

Aditi-1400 force-pushed the compile-cache branch from b6eb597 to 4143c2fCompare July 23, 2025 15:52

joyeecheung reviewed Jul 28, 2025
View reviewed changes

doc/api/module.md Outdated Show resolvedHide resolved
doc/api/module.md Outdated Show resolvedHide resolved
doc/node.1 Outdated Show resolvedHide resolved
src/compile_cache.cc Outdated Show resolvedHide resolved
src/compile_cache.ccShow resolvedHide resolved

Aditi-1400 force-pushed the compile-cache branch 2 times, most recently from 5abcfc9 to de78d1aCompare August 1, 2025 13:15