npm package: @spreadmonitor/shared-tooling-config
Description: Shared configs for tooling withing our Typescript projects.
Author: Spreadmonitor
Latest version: 0.8.0

# @spreadmonitor/shared-tooling-config

This package provides a shared configuration for tools used in our Typescript based projects. By bundling our
configurations and specific packages versions we can ensure that every project uses the same best practices and
simplifies the update of said dependencies.

We have two type of shares:

- config only - we share specific config files to extend in our projects but do not bundle the package itself (eg: Typescript, Jest)
- bundled dependency - we bundle the config and the specific version of the dependency to be used (Prettier, ESLint)

## Installation

```bash
npm install --save-dev @spreadmonitor/shared-tooling-config
```

> [!Tip]
> The above command installs the package from NPM. To install the package from Github Package Registry follow
> the steps below.

<details>
<summary>Guide to install from Github Package Registry</summary>

To use the Github Package Registry you need to do two things:

- authenticate with a personal access token
- configure NPM to use the custom registry for the `@spreadmonitor` scope
- optionally you can configure multiple registries if not all of your packages are installed from the Github Registry

You can do this via adding the following to your `<project-root>/.npmrc` file:

```.npmrc
//npm.pkg.github.com/:_authToken=<PERSONAL GH TOKEN>
```

You also need to configure NPM per project basis to use both the NPM and Github registry to lookup packages
in the `@spreadmonitor/*` namespace. Add a `<project-root>/.npmrc` file with the following content:

```.npmrc
; Instrument NPM to use both the NPM public and Github registry to lookup packages for the @spreadmonitor scope.
@spreadmonitor:registry=https://npm.pkg.github.com
@spreadmonitor:registry=https://registry.npmjs.org/
```

For further details, please read the related [Github documentation][ghprc].

</details>

## Usage

This package contains the configuration files for our tools which needs to be included in project local configuration.
This section details how use each included config type.

---

### Typescript

We provide three configuration files for Typescript: one for development, one for production builds, and one for testing
with Jest - this is laxer configuration to help writing tests with less boilerplate. Each of these files needs to be
extended from the project specific configurations. You may overwrite specific configuration options in the local
configuration but generally no extra change should be required for everyday development.

> [!TIP]
> Typescript is not included in this package, only the the configurations. You still need to install Typescript for
> each project separately.

Currently the following files are provided:

- `tsconfig.json` - the base configuration used for development
- `tsconfig.prod.json` - configuration extending the base for production builds
- `tsconfig.spec.json` - configuration extending the base for testing with Jest

#### Examples

> [!IMPORTANT]
> Please note that path based compiler options (eg: `compilerOptions.outDir` and `compilerOptions.rootDir`) is resolved
> relatively to the file it was defined in, so it needs to be defined manually in each project as seen below. 
> (This issue is tracked in [microsoft/TypeScript#29172][outdir-issue].)

`<project-root>/tsconfig.json` - extending the default tsconfig in the project

```jsonc
{
  // Specify the base config from this package.
  "extends": "@spreadmonitor/shared-tooling-config/tsconfig.json",
  // Any project specific configuration overwrite can be included here.
  "compilerOptions": {
    // If the project still uses CommonJS, then you need to specify it
    "module": "commonjs",
    // You must add the outDir option in the local configuration.
    "outDir": "build"
  }
}
```

`<project-root>/tsconfig.prod.json` - extending the production configuration

```jsonc
{
  "extends": "@spreadmonitor/shared-tooling-config/tsconfig.json"
}
```

`<project-root>/tsconfig.spec.json` - extending the TSConfig used for testing

```jsonc
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "rootDirs": ["./src", "./test"]
  }
}
```

---

### Prettier

To use the shared Prettier config you need to create a `.prettierrc.yml` file and specify the name of this package.

#### Example

`<project-root>/.prettierrc` - extending the default Prettier config

```yml
"@spreadmonitor/shared-tooling-config"
```

For more details read the [Prettier documentation][prettier-sharing-config] about sharing configurations.

---

### ESLint

To use the shared ESLint configuration you need to use the extend statement in the project `.eslintrc.yml` file. The
project file should not extend other ESLint files as we are extending everything we would like to use in the base config.

```yml
extends:
  - '@spreadmonitor/shared-tooling-config'
```

For more details read the [ESLint documentation][eslint-sharing-config] about sharing configurations.

## Contributing

Before contributing please read the [contribution guidelines][contrib-guide]!

[ghprc]: https://docs.github.com/en/packages/guides/configuring-npm-for-use-with-github-packages
[prettier-sharing-config]: https://prettier.io/docs/en/configuration.html#sharing-configurations
[eslint-sharing-config]: https://eslint.org/docs/developer-guide/shareable-configs
[outdir-issue]: https://github.com/microsoft/TypeScript/issues/29172
[contrib-guide]: ./CONTRIBUTING.md