[![npm version](https://badge.fury.io/js/%40goldstack%2Futils-typescript-references.svg)](https://badge.fury.io/js/%40goldstack%2Futils-typescript-references)

# TypeScript References Yarn Workspaces Sync Utility

This library ensures that [project references](https://www.typescriptlang.org/docs/handbook/project-references.html) in TypeScript `tsconfig.js` files are automatically kept up to date in a project using **Yarn 2 workspaces**.

Running this script will:

1. Add a list of all packages in the workspaces to the root `tsconfig.json` for the `"references"` attribute:

```json
{
  "references": [
    {
      "path": "workspaces/apps"
    },
    {
      "path": "workspaces/docs"
    },
    {
      "path": "workspaces/templates"
    },
    {
      "path": "workspaces/templates-lib"
    }
  ]
}
```

2. Update all the `"references"` in the `tsconfig.json` for all packages in the workspace so that it includes all the packages that it declares as a dependency in `package.json`.

This utility has been developed for the [Goldstack](https://goldstack.party) starter project builder. Check it out for starting your next project ❤️
## Installation

```bash
npm install @goldstack/utils-typescript-references
```

## Usage

Install as development dependency using

```
npm i @goldstack/utils-typescript-references --save-dev
-- or
yarn add -D @goldstack/utils-typescript-references
```

Add a script to your `package.json`

```json
{
  "scripts": {
    "fix-typescript-references": "utils-typescript-references"
  }
}
```

Run the script using

```
npm run fix-typescript-references
-- or
yarn fix-typescript-references
```

## Options

The following parameters can be passed when invoking the script:

### --help

Shows a reference of all available options:

```
$ utils-typescript-references --help
Options:
  --help                 Show help                                     [boolean]
  --version              Show version number                           [boolean]
  --skipPackages         Only update project references in the root tsConfig
                                                                       [boolean]
  --skipRoot             Skip updating project references in project root
                         tsConfig                                      [boolean]
  --excludeInReferences  Exclude specific packages from being referenced by
                         other packages                                  [array]
  --excludeInRoot        Exclude specific packages from being referenced in the
                         root tsConfig                                   [array]
  --tsConfigName         Names of tsConfig files to be updated           [array]
```

### --tsConfigName

Provide one or more name of `tsconfig.json` files in projects across the monorepo that should be updated.

```
$ utils-typescript-references --tsConfigName tsconfig.json --tsConfigName tsconfig.build.json
```

Defaults to `tsconfig.json`

This helpful for monorepos where for instance the `tsconfig.build.json` builds the modules that are exported from the package, and thus should be run when you are building using `tsc -b`. In this case the `tsconfig.json` can be set up to type check only (no emit) and have a manually inserted reference to `tsconfig.build.json` for running `tsc -b`.

Note that once any `--tsConfigName` is provided, the default `tsconfig.json` is not updated any more. In order to continue updating `tsconfig.json` along with any custom configuration files, simply provide it as an extra option:

```
$ utils-typescript-references --tsConfigName tsconfig.build.json --tsConfigName tsconfig.json
```

This option can also be used if the `tsconfig.json` file is not in the root of packages (e.g. in the `src/` folder). In that case, provide an option as follows:

```
$ utils-typescript-references --tsConfigName src/tsconfig.json --tsConfigName tsconfig.json
```

### --excludeInReferences

Will prevent certain packages from being added to the `references` of other projects in the monorepo.

```
$ utils-typescript-references --excludeInReferences @myproject/packageA --excludeInReferences @myproject/PackageB
```

The above will cause `@myproject/packageA` and `@myproject/packageB` not to be inserted as referenced in all other packages of the monorepo.

### --excludeInRoot

Will prevent certain packages from being added to the `references` section of the root `tsconfig.json` file.

```
$ utils-typescript-references --excludeInRoot @myproject/packageA --excludeInRoot @myproject/PackageB
```

### --skipPackages

Will skip updating the `references` in `tsconfig.json` files for all packages in the project.

```
$ utils-typescript-references --skipPackages
```

### --skipRoot

Will skip updating the `references` in the `tsconfig.json` file for the project root.

```
$ utils-typescript-references --skipRoot
```

## Limitations

- The root `tsconfig.json` file needs to be a vanilla JSON document (so no comments)

If these limitations or anything else are an issues, please [raise a ticket in GitHub for the Goldstack Monorepo](https://github.com/goldstack/goldstack/issues).

## See Also

- [Code with Joy - The Ultimate Guide to TypeScript Monorepos](https://maxrohde.com/2021/11/20/the-ultimate-guide-to-typescript-monorepos/)
- [The Full Stack Blog - TypeScript Monorepo with Yarn and Project References](https://maxrohde.com/2021/10/01/typescript-monorepo-with-yarn-and-project-references/)
- [@monorepo-utils/workspaces-to-typescript-project-references](https://github.com/azu/monorepo-utils/tree/master/packages/@monorepo-utils/workspaces-to-typescript-project-references#readme)
- [Optimizing multi-package apps with TypeScript Project References](https://ebaytech.berlin/optimizing-multi-package-apps-with-typescript-project-references-d5c57a3b4440)
- [TypeScript Monorepos with Yarn](https://semaphoreci.com/blog/typescript-monorepos-with-yarn)