feat(core): introduce the NX_PROJECT_GRAPH_CACHE_DIRECTORY to allow s…

docs/shared/using-nx/caching.md

@@ -179,7 +179,7 @@ nx affected --target=build --skip-nx-cache
 
 ## Customizing the Cache Location
 
-The cache is stored in `node_modules/.cache/nx` by default. To change the cache location, update the `cacheDirectory` option for the task runner:
+The cache is stored in `node_modules/.cache/nx` by default. To change the cache location, set a `NX_CACHE_DIRECTORY` environment variable or update the `cacheDirectory` option for the task runner:
 
 ```json
 {
@@ -209,7 +209,11 @@ You can connect your workspace to Nx Cloud by running:
 nx connect-to-nx-cloud
 ```
 
-You can also distribute the cache manually using your own storage mechanisms.
+You can also distribute the cache manually using your own storage mechanisms. Be warned, it is not as simple as it might sound initially.
+
+- _If possible_, pull a copy of the cache which doesn't mutate the cache currently in use by other consumers. Push an updated copy afterwards.
+- By default, Nx also caches some computations necessary for calculating the project graph in the cache directory as well.
+  - If you are using a shared volume where mutations to the cache are reflected immediately in other consumers, you should set `NX_PROJECT_GRAPH_CACHE_DIRECTORY` to a separate directory to separate it from the computation cache.
 
 ## Example
 

packages/nx/src/command-line/reset.ts

@@ -1,6 +1,6 @@
 import { removeSync } from 'fs-extra';
 import { stop as stopDaemon } from '../daemon/client/client';
-import { cacheDir } from '../utils/cache-directory';
+import { cacheDir, projectGraphCacheDirectory } from '../utils/cache-directory';
 import { output } from '../utils/output';
 
 export function resetHandler() {
@@ -10,6 +10,9 @@ export function resetHandler() {
   });
   stopDaemon();
   removeSync(cacheDir);
+  if (projectGraphCacheDirectory !== cacheDir) {
+    removeSync(projectGraphCacheDirectory);
+  }
   output.success({
     title: 'Successfully reset the Nx workspace.',
   });

packages/nx/src/daemon/tmp-dir.ts

@@ -5,9 +5,12 @@
  */
 import { statSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import { cacheDir } from '../utils/cache-directory';
+import { projectGraphCacheDirectory } from '../utils/cache-directory';
 
-export const DAEMON_DIR_FOR_CURRENT_WORKSPACE = join(cacheDir, 'd');
+export const DAEMON_DIR_FOR_CURRENT_WORKSPACE = join(
+  projectGraphCacheDirectory,
+  'd'
+);
 
 export const DAEMON_OUTPUT_LOG_FILE = join(
   DAEMON_DIR_FOR_CURRENT_WORKSPACE,

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

@@ -2,7 +2,7 @@ import { existsSync } from 'fs';
 import { ensureDirSync } from 'fs-extra';
 import { join } from 'path';
 import { performance } from 'perf_hooks';
-import { cacheDir } from '../utils/cache-directory';
+import { projectGraphCacheDirectory } from '../utils/cache-directory';
 import { directoryExists, fileExists } from '../utils/fileutils';
 import {
   FileData,
@@ -29,12 +29,12 @@ export interface ProjectGraphCache {
   dependencies: Record<string, ProjectGraphDependency[]>;
 }
 
-export const nxDepsPath = join(cacheDir, 'nxdeps.json');
+export const nxDepsPath = join(projectGraphCacheDirectory, 'nxdeps.json');
 
 export function ensureCacheDirectory(): void {
   try {
-    if (!existsSync(cacheDir)) {
-      ensureDirSync(cacheDir);
+    if (!existsSync(projectGraphCacheDirectory)) {
+      ensureDirSync(projectGraphCacheDirectory);
     }
   } catch (e) {
     /*
@@ -47,8 +47,10 @@ export function ensureCacheDirectory(): void {
      * In this case, we're creating the directory. If the operation failed, we ensure that the directory
      * exists before continuing (or raise an exception).
      */
-    if (!directoryExists(cacheDir)) {
-      throw new Error(`Failed to create directory: ${cacheDir}`);
+    if (!directoryExists(projectGraphCacheDirectory)) {
+      throw new Error(
+        `Failed to create directory: ${projectGraphCacheDirectory}`
+      );
     }
   }
 }

packages/nx/src/utils/cache-directory.ts

@@ -35,3 +35,6 @@ export const cacheDir = cacheDirectory(
   workspaceRoot,
   readCacheDirectoryProperty(workspaceRoot)
 );
+
+export const projectGraphCacheDirectory =
+  process.env.NX_PROJECT_GRAPH_CACHE_DIRECTORY ?? cacheDir;