[rush] Add an optional "description" field for projects in rush.json

common/changes/@microsoft/rush/rush-json-project-description_2026-09-25-01-31-10.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add an optional \"description\" field for project entries in rush.json, exposed as the new `RushConfigurationProject.description` API.",
+      "type": "none",
+      "packageName": "@microsoft/rush"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "3360621+yumikohey@users.noreply.github.com"
+}

common/reviews/api/rush-lib.api.md

@@ -1799,6 +1799,8 @@ export class RushConfigurationProject {
     get cyclicDependencyProjects(): Set<string>;
     readonly decoupledLocalDependencies: Set<string>;
     get dependencyProjects(): ReadonlySet<RushConfigurationProject>;
+    // @beta
+    readonly description: string | undefined;
     // @deprecated
     get downstreamDependencyProjects(): string[];
     // @beta

libraries/rush-lib/assets/rush-init/rush.json

@@ -389,6 +389,13 @@
        */
       "projectFolder": "apps/my-app",
 
+      /**
+       * An optional human-readable description of the project, for example a one-line
+       * summary of its purpose.  Rush does not interpret this value, but it is available
+       * to tools and plugins via the Rush API.
+       */
+      /*[LINE "HYPOTHETICAL"]*/ "description": "The main web application for the example repo",
+
       /**
        * This field is only used if "subspacesEnabled" is true in subspaces.json.
        * It specifies the subspace that this project belongs to.  If omitted, then the

libraries/rush-lib/src/api/RushConfigurationProject.ts

@@ -22,6 +22,7 @@ import type { Subspace } from './Subspace';
 export interface IRushConfigurationProjectJson {
   packageName: string;
   projectFolder: string;
+  description?: string;
   reviewCategory?: string;
   decoupledLocalDependencies: string[];
   cyclicDependencyProjects?: string[];
@@ -95,6 +96,18 @@ export class RushConfigurationProject {
    */
   public readonly projectRelativeFolder: string;
 
+  /**
+   * An optional human-readable description of the project, as specified by the `"description"`
+   * field in `rush.json`, or `undefined` if no description was provided.
+   *
+   * @remarks
+   * Rush does not interpret this value; it is intended to help people and tools understand
+   * the purpose of the project.
+   *
+   * @beta
+   */
+  public readonly description: string | undefined;
+
   /**
    * The project-specific Rush configuration folder.
    *
@@ -211,10 +224,11 @@ export class RushConfigurationProject {
   /** @internal */
   public constructor(options: IRushConfigurationProjectOptions) {
     const { projectJson, rushConfiguration, tempProjectName, allowedProjectTags } = options;
-    const { packageName, projectFolder: projectRelativeFolder } = projectJson;
+    const { packageName, projectFolder: projectRelativeFolder, description } = projectJson;
     this.rushConfiguration = rushConfiguration;
     this.packageName = packageName;
     this.projectRelativeFolder = projectRelativeFolder;
+    this.description = description;
 
     validateRelativePathField(projectRelativeFolder, 'projectFolder', rushConfiguration.rushJsonFile);
 

libraries/rush-lib/src/api/test/RushConfiguration.test.ts

@@ -104,10 +104,12 @@ describe(RushConfiguration.name, () => {
     expect(project1.tempProjectName).toEqual('@rush-temp/project1');
     expect(project1.unscopedTempProjectName).toEqual('project1');
     expect(project1.skipRushCheck).toEqual(false);
+    expect(project1.description).toEqual('An example project with a description');
 
     // Validate project2 settings
     const project2: RushConfigurationProject = rushConfiguration.getProjectByName('project2')!;
     expect(project2.skipRushCheck).toEqual(true);
+    expect(project2.description).toBeUndefined();
   });
 
   it('can load repo/rush-pnpm.json', () => {

libraries/rush-lib/src/api/test/repo/rush-npm.json

@@ -27,6 +27,7 @@
     {
       "packageName": "project1",
       "projectFolder": "project1",
+      "description": "An example project with a description",
       "reviewCategory": "third-party",
       "tags": ["frontend", "ui"],
       "versionPolicyName": "testPolicy"

libraries/rush-lib/src/schemas/rush.schema.json

@@ -356,6 +356,10 @@
             "description": "The path to the project folder relative to the Rush config file.",
             "type": "string"
           },
+          "description": {
+            "description": "An optional human-readable description of the project, for example a one-line summary of its purpose. Rush does not interpret this value, but it is available to tools and plugins via the Rush API.",
+            "type": "string"
+          },
           "reviewCategory": {
             "description": "An optional category for usage in the \"browser-approved-packages.json\" and \"nonbrowser-approved-packages.json\" files.  Only strings from reviewCategories are allowed here.",
             "type": "string"