[heft-config-file] Let null reset properties

apps/api-extractor/config/heft.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   "extends": "decoupled-local-node-rig/profiles/default/config/heft.json",
 

apps/heft/src/schemas/heft-legacy.schema.json

@@ -20,7 +20,7 @@
     },
 
     "extends": {
-      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
+      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects. To delete an inherited setting, set it to `null` in this file.",
       "type": "string"
     },
 

apps/heft/src/schemas/heft.schema.json

@@ -104,7 +104,7 @@
     },
 
     "extends": {
-      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
+      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects. To delete an inherited setting, set it to `null` in this file.",
       "type": "string"
     },
 

apps/heft/src/schemas/node-service.schema.json

@@ -13,7 +13,7 @@
     },
 
     "extends": {
-      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
+      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects. To delete an inherited setting, set it to `null` in this file.",
       "type": "string"
     },
 

apps/heft/src/schemas/templates/heft.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   // "extends": "base-project/config/heft.json",
 

apps/lockfile-explorer-web/config/heft.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   "extends": "local-web-rig/profiles/app/config/heft.json",
 

apps/lockfile-explorer/config/heft.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   "extends": "local-node-rig/profiles/default/config/heft.json",
 

apps/lockfile-explorer/config/node-service.json

@@ -8,6 +8,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   // "extends": "base-project/config/serve-command.json",
 

build-tests-samples/heft-web-rig-library-tutorial/config/api-extractor.json

@@ -8,6 +8,8 @@
    * Optionally specifies another JSON config file that this file extends from.  This provides a way for
    * standard settings to be shared across multiple projects.
    *
+   * To delete an inherited setting, set it to `null` in this file.
+   *
    * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
    * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
    * resolved using NodeJS require().

build-tests/heft-fastify-test/config/node-service.json

@@ -8,6 +8,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   // "extends": "base-project/config/serve-command.json",
 

build-tests/localization-plugin-test-01/config/heft.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   "extends": "local-node-rig/profiles/default/config/heft.json",
 

build-tests/localization-plugin-test-02/config/heft.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   "extends": "local-node-rig/profiles/default/config/heft.json",
 

common/changes/@microsoft/api-extractor/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@microsoft/api-extractor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@microsoft/rush/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "none",
+      "packageName": "@microsoft/rush"
+    }
+  ],
+  "packageName": "@microsoft/rush",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/heft-api-extractor-plugin/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/heft-api-extractor-plugin"
+    }
+  ],
+  "packageName": "@rushstack/heft-api-extractor-plugin",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/heft-config-file/config-file-null_2025-04-16-00-37.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-config-file",
+      "comment": "Allow use of the value `null` to discard any value set for the property from a parent config file..",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-config-file"
+}

common/changes/@rushstack/heft-node-rig/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/heft-node-rig"
+    }
+  ],
+  "packageName": "@rushstack/heft-node-rig",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/heft-sass-plugin/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/heft-sass-plugin"
+    }
+  ],
+  "packageName": "@rushstack/heft-sass-plugin",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/heft-typescript-plugin/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/heft-typescript-plugin"
+    }
+  ],
+  "packageName": "@rushstack/heft-typescript-plugin",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/heft-web-rig/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/heft-web-rig"
+    }
+  ],
+  "packageName": "@rushstack/heft-web-rig",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/heft/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/heft"
+    }
+  ],
+  "packageName": "@rushstack/heft",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

common/changes/@rushstack/lockfile-explorer/config-file-null_2025-04-16-01-15.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Update documentation for `extends`",
+      "type": "patch",
+      "packageName": "@rushstack/lockfile-explorer"
+    }
+  ],
+  "packageName": "@rushstack/lockfile-explorer",
+  "email": "dmichon-msft@users.noreply.github.com"
+}

heft-plugins/heft-api-extractor-plugin/src/schemas/api-extractor-task.schema.json

@@ -13,7 +13,7 @@
     },
 
     "extends": {
-      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
+      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects. To delete an inherited setting, set it to `null` in this file.",
       "type": "string"
     },
 

heft-plugins/heft-sass-plugin/src/schemas/heft-sass-plugin.schema.json

@@ -13,7 +13,7 @@
     },
 
     "extends": {
-      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
+      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects. To delete an inherited setting, set it to `null` in this file.",
       "type": "string"
     },
 

heft-plugins/heft-sass-plugin/src/templates/sass.json

@@ -7,6 +7,8 @@
   /**
    * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
    * settings to be shared across multiple projects.
+   *
+   * To delete an inherited setting, set it to `null` in this file.
    */
   // "extends": "base-project/config/serve-command.json",
 

heft-plugins/heft-typescript-plugin/src/schemas/typescript.schema.json

@@ -13,7 +13,7 @@
     },
 
     "extends": {
-      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects.",
+      "description": "Optionally specifies another JSON config file that this file extends from.  This provides a way for standard settings to be shared across multiple projects. To delete an inherited setting, set it to `null` in this file.",
       "type": "string"
     },
 

libraries/heft-config-file/src/ConfigurationFileBase.ts

@@ -16,6 +16,8 @@ interface IConfigurationJson {
  * @beta
  *
  * The set of possible mechanisms for merging properties from parent configuration files.
+ * If a child configuration file sets a property value to `null`, that will always delete the value
+ * specified in the parent configuration file, regardless of the inheritance type.
  */
 const InheritanceType = {
   /**
@@ -251,6 +253,7 @@ export interface ICustomPropertyInheritance<TObject> extends IPropertyInheritanc
    * Provides a custom inheritance function. This function takes two arguments: the first is the
    * child file's object, and the second is the parent file's object. The function should return
    * the resulting combined object.
+   * This function will not be invoked if the current value is `null`, the property will simply be deleted.
    */
   inheritanceFunction: PropertyInheritanceCustomFunction<TObject>;
 }
@@ -1085,7 +1088,15 @@ export abstract class ConfigurationFileBase<TConfigurationFile, TExtraOptions ex
         newValue = parentPropertyValue;
       };
 
-      if (propertyValue !== undefined && parentPropertyValue === undefined) {
+      if (propertyValue === null) {
+        if (parentPropertyValue !== undefined) {
+          resultAnnotation.originalValues[propertyName] = this.getPropertyOriginalValue({
+            parentObject: parentObject,
+            propertyName: propertyName
+          });
+        }
+        newValue = undefined;
+      } else if (propertyValue !== undefined && parentPropertyValue === undefined) {
         usePropertyValue();
       } else if (parentPropertyValue !== undefined && propertyValue === undefined) {
         useParentPropertyValue();
@@ -1207,7 +1218,10 @@ export abstract class ConfigurationFileBase<TConfigurationFile, TExtraOptions ex
         }
       }
 
-      result[propertyName] = newValue;
+      if (newValue !== undefined) {
+        // Don't attach the key for undefined values so that they don't enumerate.
+        result[propertyName] = newValue;
+      }
     }
 
     return result;

libraries/heft-config-file/src/test/ConfigurationFile.test.ts

@@ -251,6 +251,7 @@ describe('ConfigurationFile', () => {
       things: string[];
       thingsObj: { A: { B: string }; D: { E: string } };
       booleanProp: boolean;
+      stringProp?: string;
     }
 
     it('Correctly loads the config file', () => {
@@ -266,7 +267,8 @@ describe('ConfigurationFile', () => {
       const expectedConfigFile: ISimpleConfigFile = {
         things: ['A', 'B', 'C'],
         thingsObj: { A: { B: 'C' }, D: { E: 'F' } },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -284,7 +286,8 @@ describe('ConfigurationFile', () => {
       const expectedConfigFile: ISimpleConfigFile = {
         things: ['A', 'B', 'C'],
         thingsObj: { A: { B: 'C' }, D: { E: 'F' } },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -317,7 +320,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(__dirname, configFileFolderName, 'C') },
           D: { E: nodeJsPath.resolve(__dirname, configFileFolderName, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -350,7 +354,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(__dirname, configFileFolderName, 'C') },
           D: { E: nodeJsPath.resolve(__dirname, configFileFolderName, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -383,7 +388,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(projectRoot, 'C') },
           D: { E: nodeJsPath.resolve(projectRoot, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -416,7 +422,8 @@ describe('ConfigurationFile', () => {
           A: { B: nodeJsPath.resolve(projectRoot, 'C') },
           D: { E: nodeJsPath.resolve(projectRoot, 'F') }
         },
-        booleanProp: true
+        booleanProp: true,
+        stringProp: 'someValue'
       };
       expect(JSON.stringify(loadedConfigFile)).toEqual(JSON.stringify(expectedConfigFile));
     });
@@ -435,6 +442,7 @@ describe('ConfigurationFile', () => {
       things: string[];
       thingsObj: { A: { B?: string; D?: string }; D?: { E: string }; F?: { G: string } };
       booleanProp: boolean;
+      stringProp?: string;
     }
 
     it('Correctly loads the config file with default config meta', () => {