A library for loading JSON configuration files in the Heft build
system. It supports extends-based inheritance between config files, configurable property merge strategies,
automatic path resolution, and JSON schema validation.
Links
CHANGELOG.md - Find
out what's new in the latest version
@rushstack/heft-config-file provides a structured way to load JSON config files that:
Extend a parent config file via an "extends" field (including across packages)
Merge parent and child properties with configurable inheritance strategies (append, merge, replace, or custom)
Resolve paths in property values relative to the config file, project root, or via Node.js module resolution
Validate the merged result against a JSON schema
Support rigs by falling back to a rig package profile if the project doesn't have its own config file
For config file authors (Heft users)
If you're writing or customizing a config file that uses this system (e.g. heft.json, typescript.json, or
a plugin's config file), here's what you need to know.
The extends field
Config files can inherit from a parent file using "extends":
The "extends" value is resolved using Node.js module resolution, so it can be:
A relative path: "extends": "../shared/base.json"
A package reference: "extends": "@my-company/rig/profiles/default/config/heft.json"
Circular extends chains are detected and will throw an error.
How property inheritance works
When a child config extends a parent, each top-level property is merged according to its inheritance type.
The inheritance type is configured by the package that defines the config file schema (not by the user).
The built-in inheritance types are:
Type
Applies to
Behavior
replace
any
Child value completely replaces the parent value (default for objects)
append
arrays only
Child array elements are appended after parent array elements (default for arrays)
If the schema allows it, you can override the inheritance type for an individual property directly in your
config file using the "$<propertyName>.inheritanceType" annotation:
The inline annotation takes precedence over any default set by the loader.
Note:$propertyName.inheritanceType is a loader-level annotation and is stripped from the final config
object; it will not appear in the merged result or be validated by the schema.
Path resolution
Properties that represent file system paths may be automatically resolved by the loader. The resolution
method is determined by the loader's configuration, not the config file author. The original (unresolved)
value is preserved and can be retrieved via the API.
For API consumers (plugin/loader authors)
If you're writing a Heft plugin that needs to load a config file, use ProjectConfigurationFile or
NonProjectConfigurationFile.
ProjectConfigurationFile
Use this for config files stored at a known path relative to the project root, with optional rig support.
import { ProjectConfigurationFile, InheritanceType, PathResolutionMethod } from '@rushstack/heft-config-file';interface IMyPluginConfig { outputFolder: string; plugins: string[]; settings?: { strict: boolean; }; extends?: string;}const loader = new ProjectConfigurationFile<IMyPluginConfig>({ // Path relative to the project root projectRelativeFilePath: 'config/my-plugin.json', // Provide either jsonSchemaPath or jsonSchemaObject jsonSchemaPath: require.resolve('./schemas/my-plugin.schema.json'), // Configure how properties merge when a config file uses "extends" propertyInheritance: { plugins: { inheritanceType: InheritanceType.append }, settings: { inheritanceType: InheritanceType.merge } // Properties not listed here use the default for their type }, // Optionally override the default inheritance for all arrays or all objects propertyInheritanceDefaults: { array: { inheritanceType: InheritanceType.append }, // built-in default object: { inheritanceType: InheritanceType.replace } // built-in default }, // Automatically resolve path properties to absolute paths jsonPathMetadata: { '$.outputFolder': { pathResolutionMethod: PathResolutionMethod.resolvePathRelativeToConfigurationFile } }});// Load config for a project (throws if not found)const config = loader.loadConfigurationFileForProject(terminal, projectPath);// Load config with rig fallbackconst config = loader.loadConfigurationFileForProject(terminal, projectPath, rigConfig);// Returns undefined instead of throwing if the file doesn't existconst config = loader.tryLoadConfigurationFileForProject(terminal, projectPath, rigConfig);// Async variants are also available:// loader.loadConfigurationFileForProjectAsync(...)// loader.tryLoadConfigurationFileForProjectAsync(...)
When a rigConfig is provided and the project does not have its own config file, the loader falls back to
the same relative path inside the rig's profile folder.
NonProjectConfigurationFile
Use this for config files at arbitrary absolute paths (not bound to a project root):
import { NonProjectConfigurationFile } from '@rushstack/heft-config-file';const loader = new NonProjectConfigurationFile<IMyConfig>({ jsonSchemaPath: '/path/to/schema.json'});const config = loader.loadConfigurationFile(terminal, '/absolute/path/to/config.json');// Also: tryLoadConfigurationFile, loadConfigurationFileAsync, tryLoadConfigurationFileAsync
JSON schema
Supply either a file path or an inline object:
// From a file path{ jsonSchemaPath: require.resolve('./schemas/my-plugin.schema.json') }// Inline{ jsonSchemaObject: { type: 'object', properties: { ... } } }
Schema validation runs after all inheritance merging, so the schema describes the shape of the final
merged result.
Custom validation
For validation logic that JSON schema cannot express, supply a customValidationFunction:
const loader = new ProjectConfigurationFile<IMyPluginConfig>({ projectRelativeFilePath: 'config/my-plugin.json', jsonSchemaPath: require.resolve('./schemas/my-plugin.schema.json'), customValidationFunction: (configFile, configFilePath, terminal) => { if (configFile.outputFolder === configFile.inputFolder) { terminal.writeErrorLine('outputFolder and inputFolder must be different'); return false; } return true; }});
The function is called after schema validation. If it returns anything other than true, an error is thrown.
The function may also throw its own error to provide a custom message.
Path resolution
Use jsonPathMetadata to automatically resolve string properties that represent file system paths. Keys are
JSONPath expressions, so wildcards work for arrays and nested objects:
After loading, you can query where objects came from and what their pre-resolution values were:
const config = loader.loadConfigurationFileForProject(terminal, projectPath);// Which config file did this object come from?const sourceFile = loader.getObjectSourceFilePath(config);// e.g. "/my-project/config/my-plugin.json"// What was the raw value of a property before path resolution?const originalValue = loader.getPropertyOriginalValue({ parentObject: config, propertyName: 'outputFolder'});// e.g. "./dist" (before being resolved to an absolute path)
These methods work on any object that was loaded as part of the config file (including nested objects).
Custom inheritance functions
For cases where the built-in merge strategies aren't enough:
The function receives (childValue, parentValue) and must return the merged result. It is not called if the
child sets the property to null - in that case the property is simply deleted.
Inheritance precedence
When a child config file is merged with its parent, the inheritance type for each property is resolved in
this order (highest precedence first):
Inline annotation in the config file: "$myProp.inheritanceType": "append"
propertyInheritance option passed to the loader constructor
propertyInheritanceDefaults option (per type: array or object)
Built-in defaults: append for arrays, replace for objects
Testing
TestUtilities.stripAnnotations removes the internal tracking metadata from a loaded config object,
which is useful when writing snapshot tests:
import { TestUtilities } from '@rushstack/heft-config-file';const config = loader.loadConfigurationFileForProject(terminal, projectPath);expect(TestUtilities.stripAnnotations(config)).toMatchSnapshot();