fix(add-caching): explicitly set targetDefaults for all scripts (#3929)

fahslaj · web-flow · commit dae18c927a47 · 2024-01-04T15:54:54.000-07:00
diff --git a/packages/lerna/src/commands/add-caching/README.md b/packages/lerna/src/commands/add-caching/README.md
@@ -32,6 +32,9 @@ If you mark `build` as needing topological order, the `nx.json` file will look l
 }
 ```
 
+> **Note:** Before running `add-caching`, Lerna assumes that all scripts need to be run in order.
+> After running `add-caching`, Lerna will only run scripts in order if they are marked as needing topological order.
+
 ### Which scripts are cacheable?
 
 Each script selected will be cached by Lerna. Only select scripts that do not depend on any external inputs (like network calls). `build` and `test` are usually cacheable. `start` and `serve` are usually not cacheable. Sometimes `e2e` is cacheable.
@@ -40,14 +43,9 @@ If you mark `build` as cacheable, the `nx.json` file will look like this:
 
 ```jsonc
 {
-  "tasksRunnerOptions": {
-    "default": {
-      "runner": "nx/tasks-runners/default",
-      "options": {
-        "cacheableOperations": [
-          "build" // cache the build script
-        ]
-      }
+  "targetDefaults": {
+    "build": {
+      "cache": true
     }
   }
 }
diff --git a/packages/lerna/src/commands/add-caching/index.ts b/packages/lerna/src/commands/add-caching/index.ts
@@ -6,6 +6,8 @@ import {
   workspaceRoot,
   writeJsonFile,
 } from "@nx/devkit";
+import execa from "execa";
+import { appendFile } from "fs-extra";
 import inquirer from "inquirer";
 import log from "npmlog";
 
@@ -47,6 +49,13 @@ class AddCachingCommand extends Command {
   }
 
   override async execute() {
+    const nxJsonPath = joinPathFragments(workspaceRoot, "nx.json");
+    let nxJson: NxJsonConfiguration = {};
+    try {
+      nxJson = readJsonFile(nxJsonPath);
+      // eslint-disable-next-line no-empty
+    } catch {}
+
     this.logger.info(
       "add-caching",
       "Please answer the following questions about the scripts found in your workspace in order to generate task runner configuration"
@@ -55,16 +64,23 @@ class AddCachingCommand extends Command {
 
     log.pause();
 
+    const existingTargetDefaults = this.uniqueScriptNames.filter(
+      (scriptName) => nxJson.targetDefaults?.[scriptName]?.dependsOn?.length
+    );
     const { targetDefaults } = await inquirer.prompt<{ targetDefaults: UserAnswers["targetDefaults"] }>([
       {
         type: "checkbox",
         name: "targetDefaults",
         message:
           "Which scripts need to be run in order? (e.g. before building a project, dependent projects must be built.)\n",
         choices: this.uniqueScriptNames,
+        default: existingTargetDefaults,
       },
     ]);
 
+    const existingCacheableOperations = this.uniqueScriptNames.filter(
+      (scriptName) => nxJson.targetDefaults?.[scriptName]?.cache
+    );
     const { cacheableOperations } = await inquirer.prompt<{
       cacheableOperations: UserAnswers["cacheableOperations"];
     }>([
@@ -74,13 +90,13 @@ class AddCachingCommand extends Command {
         message:
           "Which scripts are cacheable? (Produce the same output given the same input, e.g. build, test and lint usually are, serve and start are not.)\n",
         choices: this.uniqueScriptNames,
+        default: existingCacheableOperations,
       },
     ]);
 
     const scriptOutputs: UserAnswers["scriptOutputs"] = {};
 
     for (const scriptName of cacheableOperations) {
-      // eslint-disable-next-line no-await-in-loop
       scriptOutputs[scriptName] = await inquirer.prompt<Record<string, string>>([
         {
           type: "input",
@@ -94,7 +110,9 @@ class AddCachingCommand extends Command {
 
     process.stdout.write("\n");
 
-    this.convertAnswersToNxConfig({ cacheableOperations, targetDefaults, scriptOutputs });
+    this.convertAnswersToNxConfig({ cacheableOperations, targetDefaults, scriptOutputs }, nxJsonPath, nxJson);
+
+    await this.configureGitIgnore();
 
     this.logger["success"]("add-caching", "Successfully updated task runner configuration in `nx.json`");
 
@@ -108,29 +126,7 @@ class AddCachingCommand extends Command {
     );
   }
 
-  convertAnswersToNxConfig(answers: UserAnswers) {
-    const nxJsonPath = joinPathFragments(workspaceRoot, "nx.json");
-    let nxJson: NxJsonConfiguration = {};
-    try {
-      nxJson = readJsonFile(nxJsonPath);
-      // eslint-disable-next-line no-empty
-    } catch {}
-
-    nxJson.tasksRunnerOptions = nxJson.tasksRunnerOptions || {};
-    nxJson.tasksRunnerOptions["default"] = nxJson.tasksRunnerOptions["default"] || {};
-    nxJson.tasksRunnerOptions["default"].runner =
-      nxJson.tasksRunnerOptions["default"].runner || "nx/tasks-runners/default";
-    nxJson.tasksRunnerOptions["default"].options = nxJson.tasksRunnerOptions["default"].options || {};
-
-    if (nxJson.tasksRunnerOptions["default"].options.cacheableOperations) {
-      this.logger.warn(
-        "add-caching",
-        "The `tasksRunnerOptions.default.cacheableOperations` property already exists in `nx.json` and will be overwritten by your answers"
-      );
-    }
-
-    nxJson.tasksRunnerOptions["default"].options.cacheableOperations = answers.cacheableOperations;
-
+  private convertAnswersToNxConfig(answers: UserAnswers, nxJsonPath: string, nxJson: NxJsonConfiguration) {
     if (nxJson.targetDefaults) {
       this.logger.warn(
         "add-caching",
@@ -140,14 +136,21 @@ class AddCachingCommand extends Command {
 
     nxJson.targetDefaults = nxJson.targetDefaults || {};
 
-    for (const scriptName of answers.targetDefaults) {
+    for (const scriptName of this.uniqueScriptNames) {
       nxJson.targetDefaults[scriptName] = nxJson.targetDefaults[scriptName] || {};
-      nxJson.targetDefaults[scriptName] = { dependsOn: [`^${scriptName}`] };
+      if (answers.cacheableOperations.includes(scriptName)) {
+        nxJson.targetDefaults[scriptName].cache = true;
+      } else {
+        delete nxJson.targetDefaults[scriptName].cache;
+      }
+      // always set dependsOn, even if empty array, so that `lerna run` knows not to assume any dependencies
+      nxJson.targetDefaults[scriptName].dependsOn = answers.targetDefaults.includes(scriptName)
+        ? [`^${scriptName}`]
+        : [];
     }
 
     for (const [scriptName, scriptAnswerData] of Object.entries(answers.scriptOutputs)) {
       if (!scriptAnswerData[scriptName]) {
-        // eslint-disable-next-line no-continue
         continue;
       }
       nxJson.targetDefaults[scriptName] = nxJson.targetDefaults[scriptName] || {};
@@ -156,6 +159,22 @@ class AddCachingCommand extends Command {
 
     writeJsonFile(nxJsonPath, nxJson);
   }
+
+  private async configureGitIgnore(): Promise<void> {
+    try {
+      await execa("git", ["check-ignore", ".nx/cache"]);
+      // .nx/cache is already ignored - no need to update .gitignore
+    } catch (e) {
+      try {
+        await appendFile(joinPathFragments(workspaceRoot, ".gitignore"), "\n.nx/cache\n");
+      } catch (e) {
+        this.logger.warn(
+          "add-caching",
+          "Failed to update `.gitignore` with `.nx/cache`. Please update manually."
+        );
+      }
+    }
+  }
 }
 
 module.exports.AddCachingCommand = AddCachingCommand;
diff --git a/website/docs/api-reference/configuration.md b/website/docs/api-reference/configuration.md
@@ -67,14 +67,6 @@ Find the available options in [the API docs](/docs/api-reference/commands).
 
 ```json title="nx.json"
 {
-  "tasksRunnerOptions": {
-    "default": {
-      "runner": "nx/tasks-runners/default",
-      "options": {
-        "cacheableOperations": ["build", "test"]
-      }
-    }
-  },
   "namedInputs": {
     "default": ["{projectRoot}/**/*"],
     "prod": ["!{projectRoot}/**/*.spec.tsx"]
@@ -83,32 +75,27 @@ Find the available options in [the API docs](/docs/api-reference/commands).
     "build": {
       "dependsOn": ["prebuild", "^build"],
       "inputs": ["prod", "^prod"],
-      "outputs": ["{projectRoot}/dist"]
+      "outputs": ["{projectRoot}/dist"],
+      "cache": true
     },
     "test": {
-      "inputs": ["default", "^prod", "{workspaceRoot}/jest.config.ts"]
+      "inputs": ["default", "^prod", "{workspaceRoot}/jest.config.ts"],
+      "cache": true
     }
   }
 }
 ```
 
-## taskRunnerOptions
-
-### runner
-
-Everything in Nx is customizable, including running npm scripts. Most of the time you will either use the default runner
-or the `@nrwl/nx-cloud` runner.
-
-### cacheableOperations
-
-The `cacheableOperations` array defines the list of npm scripts/operations that are cached by Nx. In most repos all
-non-long running tasks (i.e., not `serve`) should be cacheable.
-
 ## Target Defaults
 
 Targets are npm script names. You can add metadata associated with say the build script of each project in the repo in
 the `targetDefaults` section.
 
+### cache
+
+When set to `true`, tells Nx to cache the results of running the script. In most repos all
+non-long running tasks (i.e., not `serve`) should be cacheable.
+
 ### dependsOn
 
 Targets can depend on other targets. A common scenario is having to build dependencies of a project first before
@@ -288,3 +275,7 @@ Using pseudocode `outputs = packageJson.targets.build.outputs || nxJson.targetDe
 The `"implicitDependencies": ["projecta", "!projectb"]` line tells Nx that the parent project depends on `projecta` even
 though there is no dependency in its `package.json`. Nx will treat such a dependency in the same way it treats explicit
 dependencies. It also tells Nx that even though there is an explicit dependency on `projectb`, it should be ignored.
+
+## Additional Configuration
+
+For additional ways to configure tasks and caching, see the relevant [Nx documentation](https://nx.dev/recipes/running-tasks).
diff --git a/website/docs/concepts/how-caching-works.md b/website/docs/concepts/how-caching-works.md
@@ -189,20 +189,6 @@ npx lerna run build --skip-nx-cache
 npx lerna run test --skip-nx-cache
 ```
 
-## Customizing the Cache Location
+## Additional Configuration
 
-The cache is stored in `node_modules/.cache/nx` by default. To change the cache location, update the `cacheDirectory`
-option for the task runner in `nx.json`:
-
-```json
-{
-  "tasksRunnerOptions": {
-    "default": {
-      "options": {
-        "cacheableOperations": ["build", "test"],
-        "cacheDirectory": "/tmp/mycache"
-      }
-    }
-  }
-}
-```
+For additional ways to configure tasks and caching, see the relevant [Nx documentation](https://nx.dev/recipes/running-tasks).
diff --git a/website/docs/concepts/task-pipeline-configuration.md b/website/docs/concepts/task-pipeline-configuration.md
@@ -24,22 +24,6 @@ following:
 npx lerna run build --concurrency=5
 ```
 
-Note, you can also change the default in `nx.json`, like this:
-
-```json title="nx.json"
-{
-  "tasksRunnerOptions": {
-    "default": {
-      "runner": "nx/tasks-runners/default",
-      "options": {
-        "cacheableOperations": [],
-        "parallel": 5
-      }
-    }
-  }
-}
-```
-
 ## Define Task Dependencies (aka Task Pipelines)
 
 Without our help Lerna cannot know what targets (scripts) have prerequisites and which ones don't. You can define task dependencies in the `nx.json` file:
diff --git a/website/docs/features/cache-tasks.md b/website/docs/features/cache-tasks.md
@@ -23,24 +23,24 @@ If you don't have `nx.json`, run `npx lerna add-caching`.
 
 :::
 
-To enable caching for `build` and `test`, edit the `cacheableOperations` property in `nx.json` to include the `build` and `test` tasks:
+To enable caching for `build` and `test`, edit the `targetDefaults` property in `nx.json` to include the `build` and `test` tasks:
 
 ```json title="nx.json"
 {
-  "tasksRunnerOptions": {
-    "default": {
-      "runner": "nx/tasks-runners/default",
-      "options": {
-        "cacheableOperations": ["build", "test"]
-      }
+  "targetDefaults": {
+    "build": {
+      "cache": true
+    },
+    "test": {
+      "cache": true
     }
   }
 }
 ```
 
 :::info
 
-Note, `cacheableOperations` need to be side effect free, meaning that given the same input they should always result in
+Note, cacheable operations need to be side effect free, meaning that given the same input they should always result in
 the same output. As an example, e2e test runs that hit the backend API cannot be cached as the backend might influence
 the result of the test run.
 
diff --git a/website/package-lock.json b/website/package-lock.json
diff --git a/website/package.json b/website/package.json

Original file line number	Diff line number	Diff line change
@@ -32,6 +32,9 @@ If you mark `build` as needing topological order, the `nx.json` file will look l
`32`	`32`	`}`
`33`	`33`	```
`34`	`34`
	`35`	+> Note: Before running `add-caching`, Lerna assumes that all scripts need to be run in order.
	`36`	+> After running `add-caching`, Lerna will only run scripts in order if they are marked as needing topological order.
	`37`	`+`
`35`	`38`	`### Which scripts are cacheable?`
`36`	`39`
`37`	`40`	Each script selected will be cached by Lerna. Only select scripts that do not depend on any external inputs (like network calls). `build` and `test` are usually cacheable. `start` and `serve` are usually not cacheable. Sometimes `e2e` is cacheable.
@@ -40,14 +43,9 @@ If you mark `build` as cacheable, the `nx.json` file will look like this:
`40`	`43`
`41`	`44`	```jsonc
`42`	`45`	`{`
`43`		`- "tasksRunnerOptions": {`
`44`		`- "default": {`
`45`		`- "runner": "nx/tasks-runners/default",`
`46`		`- "options": {`
`47`		`- "cacheableOperations": [`
`48`		`- "build" // cache the build script`
`49`		`- ]`
`50`		`- }`
	`46`	`+ "targetDefaults": {`
	`47`	`+ "build": {`
	`48`	`+ "cache": true`
`51`	`49`	`}`
`52`	`50`	`}`
`53`	`51`	`}`