docs(misc): improve docs around target defaults (#22456)

docs/shared/recipes/repo-types/integrated-in-package-based.md

@@ -4,7 +4,7 @@ In a package-based repository, you've intentionally opted out of some of Nx's fe
 
 To add an integrated project:
 
-1. Install the plugin you want to use (i.e. `npm install @nx/react`)
+1. Install the plugin you want to use (i.e. `nx add @nx/react`)
 2. Generate an application or library using that plugin (i.e. `nx g @nx/react:app`)
 
 The integrated project is now ready to use. Next, we'll discuss some of the changes that were applied to your codebase.
@@ -19,7 +19,7 @@ Even if the project you added only uses javascript, a `tsconfig.base.json` file
 
 ## project.json
 
-The project itself will have a `project.json` file that defines all the tasks that can be run on the project. This includes tasks like `build`, `serve` and `test`. See [Executors and Configurations](/concepts/executors-and-configurations) for more information.
+The project itself will have [a `project.json` file](/reference/project-configuration#project-level-configuration-files) where some tasks might be explicitly defined while other [tasks will be inferred by the plugin](/concepts/inferred-tasks) used. This can include tasks like `build`, `serve` and `test`.
 
 ## Other Configuration Files
 

docs/shared/recipes/running-tasks/configure-inputs.md

@@ -69,7 +69,7 @@ Doing so will show a view such as the one below:
 {% project-details  jsonFile="shared/concepts/myreactapp.json"%}
 {% /project-details %}
 
-Nx Console has a button which will show a preview of this screen when a project level configuration file (`project.json` or `package.json`) is opened in the IDE.
+Nx Console has a button which will show a preview of this screen when a project level configuration file (`project.json` or `package.json`) is opened in the IDE. Read more at [Nx Console Project Details View](/recipes/nx-console/console-project-details).
 
 Another way of accessing this information is to run `nx show project myreactapp --web` and the view above will be opened in a browser.
 

docs/shared/recipes/running-tasks/reduce-repetitive-configuration.md

@@ -169,7 +169,7 @@ If you scan through these three files, they look very similar. The only differen
 
 ## Reduce Configuration with targetDefaults
 
-Let's use the `targetDefaults` property in `nx.json` to reduce some of this duplicate configuration code.
+Let's use [the `targetDefaults` property](/reference/nx-json#target-defaults) in `nx.json` to reduce some of this duplicate configuration code.
 
 ```json {% fileName="nx.json" %}
 {
@@ -276,6 +276,10 @@ Now the `project.json` files can be reduced to this:
 {% /tab %}
 {% /tabs %}
 
+{% callout type="warning" title="Target defaults" %}
+This recipe assumes every target with the same name uses the same executor. If you have targets with the same name using different executors and you're providing target defaults for executor options, don't place the executor options under a default target using the target name as the key. Instead, separate target default configurations can be added using the executors as the keys, each with their specific configuration.
+{% /callout %}
+
 ## Ramifications
 
 This change adds 33 lines of code to `nx.json` and removes 84 lines of code from the `project.json` files. That's a net reduction of 51 lines of code. And you'll get more benefits from this strategy the more projects you have in your repo.

docs/shared/reference/nx-json.md

@@ -22,14 +22,19 @@ The following is an expanded example showing all options. Your `nx.json` will li
     "production": ["!{projectRoot}/**/*.spec.tsx"]
   },
   "targetDefaults": {
-    "build": {
+    "@nx/js:tsc": {
       "inputs": ["production", "^production"],
       "dependsOn": ["^build"],
-      "executor": "@nrwl/js:tsc",
       "options": {
         "main": "{projectRoot}/src/index.ts"
       },
       "cache": true
+    },
+    "test": {
+      "cache": true,
+      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+      "executor": "@nx/jest:jest"
     }
   },
   "release": {
@@ -129,12 +134,18 @@ Tells Nx which base branch to use when calculating affected projects.
 
 ## Target Defaults
 
-Target defaults provide ways to set common options for a particular target in your workspace. When building your project's configuration, we merge it with up to 1 default from this map. For a given target, we look at its name and its executor. We then check target defaults for any of the following combinations:
+Target defaults provide ways to set common options for a particular target in your workspace. When building your project's configuration, we merge it with up to 1 default from this map. For a given target, we look at its name and its executor. We then check target defaults looking for a configuration whose key matches any of the following:
 
 - `` `${executor}` ``
-- `` `${targetName}` ``
+- `` `${targetName}` `` (if the configuration specifies the executor, this needs to match the target's executor as well)
 
-Whichever of these we find first, we use as the base for that target's configuration. Some common scenarios for this follow.
+Target defaults matching the executor takes precedence over those matching the target name. If we find a target default for a given target, we use it as the base for that target's configuration.
+
+{% callout type="warning" title="Beware" %}
+When using a target name as the key of a target default, make sure all the targets with that name use the same executor or that the target defaults you're setting make sense to all targets regardless of the executor they use. Anything set in a target default will also override the configuration of [tasks inferred by plugins](/concepts/inferred-tasks).
+{% /callout %}
+
+Some common scenarios for this follow.
 
 ### inputs & namedInputs
 
@@ -145,12 +156,13 @@ Using pseudocode `inputs = projectJson.targets.build.inputs || nxJson.targetDefa
 
 You can also define and redefine named inputs. This enables one key use case, where your `nx.json` can define things like this (which applies to every project):
 
-```
-"test": {
-  "inputs": [
-    "default",
-    "^production"
-  ]
+```json {% fileName="nx.json" %}
+{
+  "targetDefaults": {
+    "test": {
+      "inputs": ["default", "^production"]
+    }
+  }
 }
 ```
 
@@ -190,7 +202,7 @@ defining `targetDefaults` in `nx.json` is helpful.
 }
 ```
 
-The configuration above is identical to adding `{"dependsOn": ["^build"]}` to every build target of every project.
+The configuration above is identical to adding `{"dependsOn": ["^build"]}` to every `build` target of every project.
 
 {% cards %}
 {% card title="Project Configuration reference" type="documentation" description="For full documentation of the `dependsOn` property, see the project configuration reference" url="/reference/project-configuration#dependson" /%}
@@ -211,7 +223,7 @@ Another target default you can configure is `outputs`:
 }
 ```
 
-When defining any options or configurations inside of a target default, you may use the `{workspaceRoot}` and `{projectRoot}` tokens. This is useful for defining things like the outputPath or tsconfig for many build targets.
+When defining any options or configurations inside of a target default, you may use the `{workspaceRoot}` and `{projectRoot}` tokens. This is useful for defining options whose values are paths.
 
 ```json {% fileName="nx.json" %}
 {
@@ -238,7 +250,7 @@ When defining any options or configurations inside of a target default, you may
 ```
 
 {% callout type="note" title="Target Default Priority" %}
-Note that the inputs and outputs are respecified on the @nx/js:tsc default configuration. This is **required**, as when reading target defaults Nx will only ever look at one key. If there is a default configuration based on the executor used, it will be read first. If not, Nx will fall back to looking at the configuration based on target name. For instance, running `nx build project` will read the options from `targetDefaults[@nx/js:tsc]` if the target configuration for build uses the @nx/js:tsc executor. It **would not** read any of the configuration from the `build` target default configuration unless the executor does not match.
+Note that the inputs and outputs are specified on both the `@nx/js:tsc` and `build` default configurations. This is **required**, as when reading target defaults Nx will only ever look at one key. If there is a default configuration based on the executor used, it will be read first. If not, Nx will fall back to looking at the configuration based on target name. For instance, running `nx build project` will read the options from `targetDefaults[@nx/js:tsc]` if the target configuration for `build` uses the `@nx/js:tsc executor`. It **would not** read any of the configuration from the `build` target default configuration unless the executor does not match.
 {% /callout %}
 
 {% cards %}