From 64d0294e4ef55c52a87a873f1b33c0c12cf639cd Mon Sep 17 00:00:00 2001
From: Jack Hsu <jack.hsu@gmail.com>
Date: Thu, 19 Jun 2025 08:23:15 -0400
Subject: [PATCH] docs(core): clarify package.json vs project.json usage and
 capabilities (#31642)

Adds comprehensive explanation that both files support executors and all
Nx features through the 'nx' property in package.json. Clarifies that
project.json is optional.

Preview:
https://nx-dev-git-issues-28715-nrwl.vercel.app/reference/project-configuration#project-level-configuration-files

## Current Behavior

The documentation for project configuration does not clearly explain
that both package.json and project.json support the same Nx features,
including executors.

## Expected Behavior

The documentation now clearly states that:
- Both package.json and project.json support targets through the "nx"
property in package.json
- The choice between the two is primarily a matter of preference
- Includes an updated example showing how to use `nx.targets` in
package.json

## Related Issue(s)

Fixes #28715
---
 .../shared/reference/project-configuration.md | 23 +++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/shared/reference/project-configuration.md b/docs/shared/reference/project-configuration.md
index 7dcb6994dc..58ae871ab7 100644
--- a/docs/shared/reference/project-configuration.md
+++ b/docs/shared/reference/project-configuration.md
@@ -65,8 +65,16 @@ The project details view also shows where each setting is defined so that you kn
 
 ## Project Level Configuration Files
 
-If you need to edit your project settings or modify an inferred task, you can do so in either `package.json` or `project.json` files. The examples on this page show both styles, and the only functional difference is that tasks that use executors must be defined in a `project.json`. Nx merges the two
-files to get each project's configuration. The full [machine readable schema](https://github.com/nrwl/nx/blob/master/packages/nx/schemas/project-schema.json) is available on GitHub.
+If you need to edit your project settings or modify an inferred task, you can do so in either `package.json` or `project.json` files. The examples on this page show both styles. Nx merges the two files to get each project's configuration. The full [machine readable schema](https://github.com/nrwl/nx/blob/master/packages/nx/schemas/project-schema.json) is available on GitHub.
+
+### When to Use package.json vs project.json
+
+Both `package.json` and `project.json` can be used to configure Nx targets, and both support the same configuration options including executors:
+
+- **package.json**: Use the `"nx"` property to define targets with executors, options, and other Nx-specific configuration
+- **project.json**: A dedicated Nx configuration file that keeps your `package.json` focused on package metadata
+
+The choice between `package.json` and `project.json` is primarily a matter of preference. The `package.json` is standard for JavaScript projects, so you may prefer to use that over the Nx-specific `project.json` file.
 
 The following configuration creates `build` and `test` targets for Nx.
 
@@ -77,8 +85,15 @@ The following configuration creates `build` and `test` targets for Nx.
 {
   "name": "mylib",
   "scripts": {
-    "test": "jest",
-    "build": "tsc -p tsconfig.lib.json" // the actual command here is arbitrary
+    "test": "jest"
+  },
+  "nx": {
+    // you could also do this in "scripts", but this "targets" configuration also supports Nx executors
+    "targets": {
+      "build": {
+        "command": "tsc -p tsconfig.lib.json"
+      }
+    }
   }
 }
 ```