perf(core): optimize project graph cache validation #33736

adwait1290 · 2025-12-08T03:46:58Z

Current Behavior

The shouldRecomputeWholeGraph function runs on every Nx command that touches the project graph (build, test, run, etc.). The current implementation uses JSON.stringify for comparison:

// Path mappings - O(n) JSON.stringify calls in a loop
Object.keys(cache.pathMappings).some((t) => {
  const cached = JSON.stringify(cache.pathMappings[t]);
  const notCached = JSON.stringify(tsConfig.compilerOptions.paths[t]);
  return cached !== notCached;
});

// Plugins - 2 JSON.stringify calls
JSON.stringify(getNxJsonPluginsData(nxJson, packageJsonDeps)) !== JSON.stringify(cache.nxJsonPlugins)

// Config - 2 JSON.stringify calls
JSON.stringify(nxJson?.pluginsConfig) !== JSON.stringify(cache.pluginsConfig)

Additionally, deepClone uses the slower JSON.parse(JSON.stringify()) pattern.

Expected Behavior

Use pre-computed hashes for O(1) comparison instead of O(n) JSON.stringify calls. Use structuredClone which is 2-3x faster than JSON round-trip for deep cloning.

Changes

1. Hash-based cache validation (`nx-deps-cache.ts`)

Added optional hash fields to FileMapCache interface:
- pathMappingsHash?: string
- nxJsonPluginsHash?: string
- pluginsConfigHash?: string
Pre-compute hashes when creating cache in createProjectFileMapCache
Compare hashes in shouldRecomputeWholeGraph instead of using JSON.stringify
Maintain backward compatibility: legacy caches without hashes fall back to original logic

2. Faster deep clone (`project-configuration-utils.ts`)

Replace JSON.parse(JSON.stringify(obj)) with structuredClone(obj)
Added TypeScript generic for type safety

Performance Impact

Operation	Before	After	Improvement
Cache validation	O(n) JSON.stringify per path	O(1) hash comparison	Significant for large monorepos
Deep clone	JSON round-trip	structuredClone	2-3x faster
Hash computation	N/A	Uses native xxhash	Very fast

The native hasher (hashObject from hasher/file-hasher.ts) uses Rust's xxhash implementation which is significantly faster than JavaScript's JSON.stringify.

Backward Compatibility

Optional hash fields ensure old caches work seamlessly
Missing hashes trigger fallback to original JSON.stringify comparison
Cache version remains 6.0 (no breaking change)

Related Issue(s)

Contributes to #32265

Testing

All 129 project-graph tests pass, including the 17 cache-specific tests.

Merge Dependencies

This PR has no dependencies and can be merged independently.

Must be merged BEFORE: #33739, #33746

Improve performance of `shouldRecomputeWholeGraph` which runs on every Nx command that touches the project graph. Changes: 1. Add pre-computed hashes to FileMapCache for pathMappings, nxJsonPlugins, and pluginsConfig - computed once when cache is written, compared on read 2. Replace JSON.stringify comparison with hash comparison using native hasher 3. Maintain backward compatibility with legacy caches (fallback to old logic) 4. Replace JSON.parse(JSON.stringify) deep clone with structuredClone Performance impact: - Cache validation: O(1) hash comparison vs O(n) JSON.stringify per item - Deep clone: structuredClone is 2-3x faster than JSON round-trip - Hot path: runs on every `nx build`, `nx test`, `nx run`, etc. The native hasher uses xxhash which is significantly faster than JSON.stringify for comparison purposes.

netlify · 2025-12-08T03:47:02Z

👷 Deploy request for nx-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`061186c`

vercel · 2025-12-08T03:47:03Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nx-dev	Ready	Preview	Dec 9, 2025 4:59pm

JamesHenry · 2025-12-09T07:05:52Z

packages/nx/src/project-graph/utils/project-configuration-utils.ts

-function deepClone(obj) {
-  return JSON.parse(JSON.stringify(obj));
+function deepClone<T>(obj: T): T {
+  return structuredClone(obj);


Looks like we're safe to use it now based on our minimum node floor

Thanks for confirming! structuredClone is available in Node 17+ and our minimum is higher than that now.

packages/nx/src/project-graph/nx-deps-cache.ts

JamesHenry · 2025-12-09T07:10:31Z

packages/nx/src/project-graph/nx-deps-cache.ts

+  const pluginsConfig = nxJson?.pluginsConfig;
+
  const newValue: FileMapCache = {
    version: '6.0',


I'll need to defer to @FrozenPandaz on if this version should change based on this PR, but otherwise the change LGTM, thank you!

I've bumped the version to 6.1 since we're adding new optional fields (pathMappingsHash, nxJsonPluginsHash, pluginsConfigHash) to the FileMapCache interface. This ensures older caches
without these fields will be invalidated. Happy to revert if @FrozenPandaz prefers otherwise.

nx-cloud · 2025-12-09T07:12:29Z

View your CI Pipeline Execution ↗ for commit 753c3ad

Command	Status	Duration	Result
`nx affected --targets=lint,test,test-kt,build,e...`	❌ Failed	1h 39m 58s	View ↗
`nx run-many -t check-imports check-lock-files c...`	✅ Succeeded	2m 38s	View ↗
`nx-cloud record -- nx-cloud conformance:check`	✅ Succeeded	11s	View ↗
`nx-cloud record -- nx format:check`	✅ Succeeded	2s	View ↗
`nx-cloud record -- nx sync:check`	✅ Succeeded	<1s	View ↗

☁️ Nx Cloud last updated this comment at 2025-12-09 08:56:07 UTC

nx-cloud

Nx Cloud has identified a possible root cause for your failed CI:

Our analysis shows these Gradle E2E test failures are caused by the Foojay toolchain resolver service (api.foojay.io) returning HTTP 503 errors, preventing Java 21 auto-provisioning. This is an external infrastructure issue unrelated to the PR's cache optimization changes, and the same failures exist in the master branch. We should wait for the Foojay service to recover before re-running these tests.

No code changes were suggested for this issue.

If the issue was transient, you can trigger a rerun by pushing an empty commit:

git commit --allow-empty -m "chore: trigger rerun"
git push

View detailed reasoning on Nx Cloud ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

… version to 6.1

adwait1290 requested a review from a team as a code owner December 8, 2025 03:46

adwait1290 requested a review from AgentEnder December 8, 2025 03:46

vercel bot deployed to Preview December 8, 2025 03:57 View deployment

This was referenced Dec 8, 2025

perf(core): optimize TypeScript compiler caching and hash operations #33739

Closed

perf: critical performance optimizations - eliminate redundant serialization and pattern compilation #33746

Closed

JamesHenry reviewed Dec 9, 2025

View reviewed changes

packages/nx/src/project-graph/nx-deps-cache.ts Outdated Show resolved Hide resolved

JamesHenry reviewed Dec 9, 2025

View reviewed changes

nx-cloud bot reviewed Dec 9, 2025

View reviewed changes

adwait1290 requested review from FrozenPandaz and vsavkin as code owners December 9, 2025 16:52

chore: address review comments - remove version reference, bump cache…

061186c

… version to 6.1

adwait1290 force-pushed the perf/nx-core-cache-optimization branch from 2782ba2 to 061186c Compare December 9, 2025 16:53

vercel bot deployed to Preview December 9, 2025 16:59 View deployment

JamesHenry assigned FrozenPandaz Dec 11, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

perf(core): optimize project graph cache validation #33736

perf(core): optimize project graph cache validation #33736

Uh oh!

adwait1290 commented Dec 8, 2025 •

edited

Loading

Uh oh!

netlify bot commented Dec 8, 2025 •

edited

Loading

Uh oh!

vercel bot commented Dec 8, 2025 •

edited

Loading

Uh oh!

JamesHenry Dec 9, 2025

Uh oh!

adwait1290 Dec 9, 2025

Uh oh!

Uh oh!

JamesHenry Dec 9, 2025

Uh oh!

adwait1290 Dec 9, 2025 •

edited

Loading

Uh oh!

nx-cloud bot commented Dec 9, 2025 •

edited

Loading

Uh oh!

nx-cloud bot left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

perf(core): optimize project graph cache validation #33736

Are you sure you want to change the base?

perf(core): optimize project graph cache validation #33736

Uh oh!

Conversation

adwait1290 commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Current Behavior

Expected Behavior

Changes

1. Hash-based cache validation (nx-deps-cache.ts)

2. Faster deep clone (project-configuration-utils.ts)

Performance Impact

Backward Compatibility

Related Issue(s)

Testing

Merge Dependencies

Uh oh!

netlify bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

👷 Deploy request for nx-docs pending review.

Uh oh!

vercel bot commented Dec 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JamesHenry Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

adwait1290 Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JamesHenry Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

adwait1290 Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nx-cloud bot commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nx-cloud bot left a comment

Choose a reason for hiding this comment

Nx Cloud has identified a possible root cause for your failed CI:

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adwait1290 commented Dec 8, 2025 •

edited

Loading

1. Hash-based cache validation (`nx-deps-cache.ts`)

2. Faster deep clone (`project-configuration-utils.ts`)

netlify bot commented Dec 8, 2025 •

edited

Loading

vercel bot commented Dec 8, 2025 •

edited

Loading

adwait1290 Dec 9, 2025 •

edited

Loading

nx-cloud bot commented Dec 9, 2025 •

edited

Loading