npm package: @rushstack/rig-package
Description: A system for sharing tool configurations between projects without duplicating config files.
Latest version: 0.7.2

# @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](https://api-extractor.com/) 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**

```js
{
  "$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**

```js
{
  "$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**

```js
{
  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",

  /**
   * (Required) The name of the rig package to inherit from.
   * It should be an NPM package name with the "-rig" suffix.
   */
  "rigPackageName": "example-rig",

  /**
   * (Optional) Selects a config profile from the rig package.  The name must consist of
   * lowercase alphanumeric words separated by hyphens, for example "sample-profile".
   * If omitted, then the "default" profile will be used."
   */
  "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:

1. First check for `config/<targetFile>.json` in the project folder; if found, use that file. OTHERWISE...
2. Check for `config/rig.json`; if found, then this project is using a rig package. Read the `<rigPackageName>`
   and `<rigProfile>` settings from that file.
3. Use Node.js module resolution to find the `<rigPackageName>` package folder (let's call that `<rigPackageFolder>`)
4. Check for `<rigPackageFolder>/profile/<rigProfile>/<targetFile>.json`; if found, use that file. OTHERWISE...
5. 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**

```js
{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "extends": "example-rig/profile/node-library/config/api-extractor.json",

  // Local override:
  "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:

```ts
import { RigConfig } from '@rushstack/rig-package';

// Probe for the rig.json file and load it if found
const rigConfig: RigConfig = RigConfig.loadForProjectFolder({
  // Specify a  project folder (i.e. where its package.json file is located)
  projectFolderPath: testProjectFolder
});

if (rigConfig.rigFound) {
  // We found a config/rig.json file
  //
  // Prints "/path/to/project3/config/rig.json"
  console.log('Found rig.json: ' + rigConfig.filePath);

  // Prints "example-rig"
  console.log('The rig package is: ' + rigConfig.rigPackageName);

  // Resolve the rig package
  //
  // Prints "/path/to/project3/node_modules/example-rig/profile/web-library"
  console.log('Profile folder: ' + rigConfig.getResolvedProfileFolder());

  // Look up a config file.  These file paths will be tested:
  //
  //   /path/to/project3/folder/file.json
  //   /path/to/project3/node_modules/example-rig/profile/web-library/folder/file.json
  //
  // The result will be the first path that exists, or undefined if the config file was not found.
  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

- [CHANGELOG.md](
  https://github.com/microsoft/rushstack/blob/main/libraries/rig-package/CHANGELOG.md) - Find
  out what's new in the latest version
- [API Reference](https://api.rushstack.io/pages/rig-package/)

`@rushstack/rig-package` is part of the [Rush Stack](https://rushstack.io/) family of projects.