What is @rushstack/rig-package?
The @rushstack/rig-package is part of the Rush Stack family of projects and is designed to help manage and share configurations across multiple projects in a monorepo. It allows developers to define a 'rig' package that contains shared configurations (like ESLint rules, TypeScript configs, etc.) and then easily consume those configurations in other projects within the monorepo. This approach helps in maintaining consistency and reducing duplication of configuration across projects.
What are @rushstack/rig-package's main functionalities?
Sharing ESLint configurations
This feature allows a project to extend ESLint configurations defined in a rig package. By specifying the path to the ESLint configuration in the rig package, the project can inherit and use those rules without having to duplicate the configuration.
{
"extends": "./node_modules/@example/my-rig-package/profiles/default/eslint"
}
Sharing TypeScript configurations
This feature enables projects to extend TypeScript configurations from a rig package. It allows for a base tsconfig.json to be defined in the rig, which projects can then extend and override as necessary, promoting consistency across the codebase.
{
"extends": "./node_modules/@example/my-rig-package/profiles/default/tsconfig.json",
"compilerOptions": {
/* Override specific compiler options here */
}
}
Using shared scripts
Projects can utilize shared scripts defined in a rig package for common tasks like building or testing. This reduces the need for each project to maintain its own versions of these scripts, streamlining development workflows.
"scripts": {
"build": "node ./node_modules/@example/my-rig-package/scripts/build.js"
}
Other packages similar to @rushstack/rig-package
eslint-config-airbnb
Similar to how @rushstack/rig-package can share ESLint configurations, eslint-config-airbnb is a widely used npm package that provides a set of ESLint rules following Airbnb's JavaScript style guide. While eslint-config-airbnb focuses specifically on ESLint rules, @rushstack/rig-package offers a broader range of configuration sharing capabilities.
tsconfig-paths
tsconfig-paths is a package that helps with the management of TypeScript paths and base configurations. It's similar to @rushstack/rig-package in that it aims to simplify TypeScript configuration management, but @rushstack/rig-package provides a more holistic approach to sharing configurations across various tools and not just TypeScript.
lerna
Lerna is a tool for managing JavaScript projects with multiple packages, making it easier to handle versioning and dependencies across a monorepo. While Lerna focuses on package management and publishing, @rushstack/rig-package focuses on sharing configurations across projects. Both tools are often used in monorepo setups but serve different purposes.
@rushstack/rig-package
The config/rig.json file is a system that Node.js build tools can adopt, in order to eliminate
duplication of config files when many projects share a common configuration. This is particularly valuable
in a setup where hundreds of projects may be built using a small set of reusable recipes.
Motivation
For a concrete example, consider the API Extractor tool which reads its
configuration from <projectFolder>/config/api-extractor.json. Suppose that we have three separate projects
that all share the exact same configuration:
project1/package.json
project1/config/api-extractor.json
project1/config/other-tool2.json
project1/config/other-tool3.json
project1/src/index.ts
project2/package.json
project2/config/api-extractor.json
project2/config/other-tool2.json
project2/config/other-tool3.json
project2/src/index.ts
project3/package.json
project3/config/api-extractor.json
project3/config/other-tool2.json
project3/config/other-tool3.json
project3/src/index.ts
It seems wasteful to copy and paste the api-extractor.json file with all those settings. If we later need
to tune the configuration, we'd have to find and update each file. For a large organization, there could be
hundreds of such projects.
The "extends"
setting provides a basic way to centralize the configuration in a "rig package". For this example,
we'll call our NPM package example-rig:
example-rig/package.json
example-rig/profile/node-library/config/api-extractor.json
example-rig/profile/web-library/config/api-extractor.json
project1/package.json
project1/config/api-extractor.json
project1/config/other-tool2.json
project1/config/other-tool3.json
project1/src/index.ts
project2/package.json
project2/config/api-extractor.json
project2/config/other-tool2.json
project2/config/other-tool3.json
project2/src/index.ts
project3/package.json
project3/config/api-extractor.json
project3/config/other-tool2.json
project3/config/other-tool3.json
project3/src/index.ts
To make things interesting, above we've introduced two "profiles":
node-library
is for libraries that target the Node.js runtime
web-library
is for libraries that target a web browser
NOTE: The node-library
and web-library
names are hypothetical examples. The names and purposes of
rig profiles are user-defined. If you only need one profile, then call it default
.
If project1 and project2 are Node.js libraries, then their api-extractor.json now reduces to this:
project1/config/api-extractor.json
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
"extends": "example-rig/profile/node-library/config/api-extractor.json"
}
Whereas if project3 is a web browser library, then it might look like this:
project3/config/api-extractor.json
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
"extends": "example-rig/profile/web-library/config/api-extractor.json"
}
Using "extends"
definitely made the config file shorter! But imagine that we have a large monorepo with 100 projects.
And each project has 5 config files like api-extactor.json. We still have to copy+paste 100 x 5 = 500 config files
across all our project folders.
Can we do better?
rig.json eliminates files entirely
The idea is to replace config/api-extractor.json
and config/other-tool2.json
(and any other such files)
with a single file config/rig.json
that delegates everything to the rig package:
project3/config/rig.json
{
"$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
"rigPackageName": "example-rig",
"rigProfile": "web-library"
}
Using rig.json eliminates the "extends"
stub files entirely. A tool that implements the rig.json system
would probe for its config file (<targetFile>.json
) using the following procedure:
- First check for
config/<targetFile>.json
in the project folder; if found, use that file. OTHERWISE...
- Check for
config/rig.json
; if found, then this project is using a rig package. Read the <rigPackageName>
and <rigProfile>
settings from that file.
- Use Node.js module resolution to find the
<rigPackageName>
package folder (let's call that <rigPackageFolder>
)
- Check for
<rigPackageFolder>/profile/<rigProfile>/<targetFile>.json
; if found, use that file. OTHERWISE...
- If the
<targetFile>.json
cannot be found in either of these places, the behavior is left to the tool.
For example, it could report an error, or proceed using defaults.
In cases where we need a project-specific customization, the "extends"
field is still supported. For example,
project1 can still add a local override like this:
project1/config/api-extractor.json
{
"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
"extends": "example-rig/profile/node-library/config/api-extractor.json",
"mainEntryPointFilePath": "<projectFolder>/lib/custom.d.ts",
}
The result is a much shorter inventory of files:
example-rig/package.json
example-rig/profile/node-library/config/api-extractor.json
example-rig/profile/node-library/config/other-tool2.json
example-rig/profile/node-library/config/other-tool3.json
example-rig/profile/web-library/config/api-extractor.json
example-rig/profile/web-library/config/other-tool2.json
example-rig/profile/web-library/config/other-tool3.json
project1/package.json
project1/config/rig.json
project1/config/api-extractor.json <-- local override shown above
project1/src/index.ts
project2/package.json
project2/config/rig.json
project2/src/index.ts
project3/package.json
project3/config/rig.json
project3/src/index.ts
The @rushstack/rig-package
API
The @rushstack/rig-package
library provides an API for loading the rig.json file and performing lookups.
It is a lightweight NPM package, intended to be easy for tool projects to accept as a dependency. The package
also includes the JSON schema file rig.schema.json.
Example usage of the API:
import { RigConfig } from '@rushstack/rig-package';
const rigConfig: RigConfig = RigConfig.loadForProjectFolder({
projectFolderPath: testProjectFolder
});
if (rigConfig.rigFound) {
console.log('Found rig.json: ' + rigConfig.filePath);
console.log('The rig package is: ' + rigConfig.rigPackageName);
console.log('Profile folder: ' + rigConfig.getResolvedProfileFolder());
console.log('Resolved config file: ' + rigConfig.tryResolveConfigFilePath('folder/file.json'));
}
Note that there are also async variants of the functions that access the filesystem.
Links
@rushstack/rig-package
is part of the Rush Stack family of projects.