Rush StackShopBlogEvents
Skip to main content

@rushstack/heft-config-file

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": "https://developer.microsoft.com/json-schemas/heft/v0/example-config-file.schema.json",
  "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.