Rush StackShopBlogEvents
Skip to main content


The @rushstack/heft-config-file library is the standard engine used to load Heft's config files. It provides a number of features such as:

  • JSON schema validation
  • "extends" inheritance with intuitive error messages
  • Support for rig package resolution
  • Four different "extends" inheritance types (append, merge, replace, computed) with preconfigured defaults
  • Property inheritance directives to customize them

Property inheritance directives

When using "extends" inheritance, Heft config files are generally preconfigured with an intuitive default strategy for each JSON field. (For a real world example, take a look at the propertyInheritance field from JestPlugin.ts.)

If you need a different inheritance type for a particular setting, you can add property inheritance directives to your JSON file. For example, suppose that we are extending a hypothetical file with a previously defined exampleObject value that is a keyed object, and a exampleArray value that is an array object:

"$schema": "",
"extends": "base-project/config/example-config-file.json",

"$exampleObject.inheritanceType": "merge", // valid choices are: "merge", "replace"
"exampleObject": {
"$exampleObjectMember.inheritanceType": "merge", // valid choices are: "merge", "replace"
"exampleObjectMember": { ... },

"$exampleArrayMember.inheritanceType": "append", // valid choices are: "append", "replace"
"exampleArrayMember": [ ... ]

"$exampleArray.inheritanceType": "replace", // valid choices are: "append", "replace"
"exampleArray": [ ... ]

Once an object is set to a inheritanceType of override, all sub-property inheritanceType values will be ignored, since the top-most object already overrides all sub-properties.

One thing to note is that different logic is used for keyed objects versus arrays. This is to make it explicit that arrays will be appended as-is, and no additional processing (eg. deduplicating if the array is intended to be a set) is done during merge. If such behavior is required, it can be done on the implementation side. Deduplicating arrays within the @rushstack/heft-config-file package doesn't quite make sense, since deduplicating arrays of non-primitive objects is not easily defined.