RoadmapShopEvents
Skip to main content

Home > @microsoft/rush-lib > RushConfiguration

RushConfiguration class

This represents the Rush configuration for a repository, based on the "rush.json" configuration file.

Signature:

export declare class RushConfiguration 

Properties

PropertyModifiersTypeDescription
allowMostlyStandardPackageNamesreadonlyboolean

Today the npmjs.com registry enforces fairly strict naming rules for packages, but in the early days there was no standard and hardly any enforcement. A few large legacy projects are still using nonstandard package names, and private registries sometimes allow it. Set "allowMostlyStandardPackageNames" to true to relax Rush's enforcement of package names. This allows upper case letters and in the future may relax other rules, however we want to minimize these exceptions. Many popular tools use certain punctuation characters as delimiters, based on the assumption that they will never appear in a package name; thus if we relax the rules too much it is likely to cause very confusing malfunctions.

The default value is false.

approvedPackagesPolicyreadonlyApprovedPackagesPolicyThe "approvedPackagesPolicy" settings.
changesFolderreadonlystringThe folder that contains all change files.
committedShrinkwrapFilenamereadonlystringThe full path of the shrinkwrap file that is tracked by Git. (The "rush install" command uses a temporary copy, whose path is tempShrinkwrapFilename.)
commonAutoinstallersFolderreadonlystringThe fully resolved path for the "autoinstallers" folder. Example: C:\MyRepo\common\autoinstallers
commonFolderreadonlystringThe fully resolved path for the "common" folder where Rush will store settings that affect all Rush projects. This is always a subfolder of the folder containing "rush.json". Example: C:\MyRepo\common
commonRushConfigFolderreadonlystring

The folder where Rush's additional config files are stored. This folder is always a subfolder called config\rush inside the common folder. (The common\config folder is reserved for configuration files used by other tools.) To avoid confusion or mistakes, Rush will report an error if this this folder contains any unrecognized files.

Example: C:\MyRepo\common\config\rush

commonScriptsFolderreadonlystringThe folder where automation scripts are stored. This is always a subfolder called "scripts" under the common folder. Example: C:\MyRepo\common\scripts
commonTempFolderreadonlystringThe folder where temporary files will be stored. This is always a subfolder called "temp" under the common folder. Example: C:\MyRepo\common\temp
commonVersionsreadonlyCommonVersionsConfigurationSettings from the common-versions.json config file.
currentInstalledVariantreadonlystring | undefinedGets the currently-installed variant, if an installation has occurred. For Rush operations which do not take a --variant parameter, this method determines which variant, if any, was last specified when performing "rush install" or "rush update".
currentVariantJsonFilenamereadonlystring

The filename of the variant dependency data file. By default this is called 'current-variant.json' resides in the Rush common folder. Its data structure is defined by ICurrentVariantJson.

Example: C:\MyRepo\common\temp\current-variant.json

ensureConsistentVersionsreadonlybooleanIf true, then consistent version specifiers for dependencies will be enforced. I.e. "rush check" is run before some commands.
eventHooksreadonlyEventHooks(BETA) The rush hooks. It allows customized scripts to run at the specified point.
experimentsConfigurationreadonlyExperimentsConfiguration(BETA) This configuration object contains settings repo maintainers have specified to enable and disable experimental Rush features.
gitAllowedEmailRegExpsreadonlystring[][Part of the "gitPolicy" feature.] A list of regular expressions describing allowable email patterns for Git commits. They are case-insensitive anchored JavaScript RegExps. Example: ".*@example.com" This array will never be undefined.
gitChangeLogUpdateCommitMessagereadonlystring | undefined[Part of the "gitPolicy" feature.] The commit message to use when committing change log files 'rush version'
gitSampleEmailreadonlystring[Part of the "gitPolicy" feature.] An example valid email address that conforms to one of the allowedEmailRegExps. Example: "foxtrot@example.com" This will never be undefined, and will always be nonempty if gitAllowedEmailRegExps is used.
gitTagSeparatorreadonlystring | undefined[Part of the "gitPolicy" feature.] The separator between package name and version in git tag.
gitVersionBumpCommitMessagereadonlystring | undefined[Part of the "gitPolicy" feature.] The commit message to use when committing changes during 'rush publish'
hotfixChangeEnabledreadonlyboolean[Part of the "hotfixChange" feature.] Enables creating hotfix changes
npmCacheFolderreadonlystring

The local folder that will store the NPM package cache. Rush does not rely on the npm's default global cache folder, because npm's caching implementation does not reliably handle multiple processes. (For example, if a build box is running "rush install" simultaneously for two different working folders, it may fail randomly.)

Example: C:\MyRepo\common\temp\npm-cache

npmOptionsreadonlyNpmOptionsConfigurationOptions that are only used when the NPM package manager is selected.
npmTmpFolderreadonlystring

The local folder where npm's temporary files will be written during installation. Rush does not rely on the global default folder, because it may be on a different hard disk.

Example: C:\MyRepo\common\temp\npm-tmp

packageManagerreadonlyPackageManagerNameThe name of the package manager being used to install dependencies
packageManagerOptionsreadonlyPackageManagerOptionsConfigurationBaseThe configuration options used by the current package manager.
packageManagerToolFilenamereadonlystringThe absolute path to the locally installed NPM tool. If "rush install" has not been run, then this file may not exist yet. Example: C:\MyRepo\common\temp\npm-local\node_modules.bin\npm
packageManagerToolVersionreadonlystringThe version of the locally installed NPM tool. (Example: "1.2.3")
packageManagerWrapperreadonlyPackageManager(BETA) An abstraction for controlling the supported package managers: PNPM, NPM, and Yarn.
packageNameParserreadonlyPackageNameParserThe rush hooks. It allows customized scripts to run at the specified point.
pnpmOptionsreadonlyPnpmOptionsConfigurationOptions that are only used when the PNPM package manager is selected.
projectFolderMaxDepthreadonlynumberThe maximum allowable folder depth for the projectFolder field in the rush.json file. This setting provides a way for repository maintainers to discourage nesting of project folders that makes the directory tree more difficult to navigate. The default value is 2, which implements on a standard convention of <categoryFolder>/<projectFolder>/package.json.
projectFolderMinDepthreadonlynumberThe minimum allowable folder depth for the projectFolder field in the rush.json file. This setting provides a way for repository maintainers to discourage nesting of project folders that makes the directory tree more difficult to navigate. The default value is 2, which implements a standard 2-level hierarchy of <categoryFolder>/<projectFolder>/package.json.
projectsreadonlyRushConfigurationProject[]
projectsByNamereadonlyMap<string, RushConfigurationProject>
projectsByTagreadonlyReadonlyMap<string, ReadonlySet<RushConfigurationProject>>(BETA) Obtains the mapping from custom tags to projects.
repositoryDefaultBranchreadonlystringThe default branch name. This tells "rush change" which remote branch to compare against.
repositoryDefaultFullyQualifiedRemoteBranchreadonlystringThe default fully-qualified git remote branch of the repository. This helps "rush change" find the right branch to compare against.
repositoryDefaultRemotereadonlystringThe default remote. This tells "rush change" which remote to compare against if the remote URL is not set or if a remote matching the provided remote URL is not found.
repositoryUrlsreadonlystring[]Remote URL(s) of the repository. If a value is provided, "rush change" will use one of these to find the right remote to compare against. Specifying multiple URLs is useful if a GitHub repository is renamed or for <projectName>.visualstudio.com versus dev.azure.com/<projectName> URLs.
rushJsonFilereadonlystringThe absolute path to the "rush.json" configuration file that was loaded to construct this object.
rushJsonFolderreadonlystringThe absolute path of the folder that contains rush.json for this project.
rushLinkJsonFilenamereadonlystring

The filename of the build dependency data file. By default this is called 'rush-link.json' resides in the Rush common folder. Its data structure is defined by IRushLinkJson.

Example: C:\MyRepo\common\temp\rush-link.json

rushPluginOptionsFolderreadonlystringThe folder where rush-plugin options json files are stored. Example: C:\MyRepo\common\config\rush-plugins
shrinkwrapFilenamereadonlystringThe filename (without any path) of the shrinkwrap file that is used by the package manager.
shrinkwrapFilePhrasereadonlystringReturns an English phrase such as "shrinkwrap file" that can be used in logging messages to refer to the shrinkwrap file using appropriate terminology for the currently selected package manager.
suppressNodeLtsWarningreadonlyboolean

Odd-numbered major versions of Node.js are experimental. Even-numbered releases spend six months in a stabilization period before the first Long Term Support (LTS) version. For example, 8.9.0 was the first LTS version of Node.js 8. Pre-LTS versions are not recommended for production usage because they frequently have bugs. They may cause Rush itself to malfunction.

Rush normally prints a warning if it detects a pre-LTS Node.js version. If you are testing pre-LTS versions in preparation for supporting the first LTS version, you can use this setting to disable Rush's warning.

telemetryEnabledreadonlyboolean(BETA) Indicates whether telemetry collection is enabled for Rush runs.
tempShrinkwrapFilenamereadonlystringThe full path of the temporary shrinkwrap file that is used during "rush install". This file may get rewritten by the package manager during installation.
tempShrinkwrapPreinstallFilenamereadonlystringThe full path of a backup copy of tempShrinkwrapFilename. This backup copy is made before installation begins, and can be compared to determine how the package manager modified tempShrinkwrapFilename.
versionPolicyConfigurationreadonlyVersionPolicyConfiguration(BETA)
versionPolicyConfigurationFilePathreadonlystring(BETA)
yarnCacheFolderreadonlystring

The local folder that will store the Yarn package cache.

Example: C:\MyRepo\common\temp\yarn-cache

yarnOptionsreadonlyYarnOptionsConfigurationOptions that are only used when the yarn package manager is selected.

Methods

MethodModifiersDescription
findProjectByShorthandName(shorthandProjectName)This is used e.g. by command-line interfaces such as "rush build --to example". If "example" is not a project name, then it also looks for a scoped name like @something/example. If exactly one project matches this heuristic, it is returned. Otherwise, undefined is returned.
findProjectByTempName(tempProjectName)Looks up a project by its RushConfigurationProject.tempProjectName field.
getCommittedShrinkwrapFilename(variant)Gets the committed shrinkwrap file name for a specific variant.
getCommonVersions(variant)Gets the settings from the common-versions.json config file for a specific variant.
getCommonVersionsFilePath(variant)Gets the path to the common-versions.json config file for a specific variant.
getImplicitlyPreferredVersions(variant)Returns a map of all direct dependencies that only have a single semantic version specifier.
getPnpmfilePath(variant)Gets the absolute path for "pnpmfile.js" for a specific variant.
getProjectByName(projectName)Looks up a project in the projectsByName map. If the project is not found, then undefined is returned.
getProjectLookupForRoot(rootPath)(BETA)
getRepoState(variant)Gets the contents from the repo-state.json file for a specific variant.
getRepoStateFilePath(variant)Gets the path to the repo-state.json file for a specific variant.
loadFromConfigurationFile(rushJsonFilename)staticLoads the configuration data from an Rush.json configuration file and returns an RushConfiguration object.
loadFromDefaultLocation(options)static
tryFindRushJsonLocation(options)staticFind the rush.json location and return the path, or undefined if a rush.json can't be found.
tryGetProjectForPath(currentFolderPath)Returns the project for which the specified path is underneath that project's folder. If the path is not under any project's folder, returns undefined.