update-ts-references

If your repository is a multi package repository (via lerna.js, yarn workspaces, pnpm workspaces or since v7 npm workspaces) in combination with project references from TypeScript, this tool will be very helpful by reading dependencies out of the package.json and applying them to the tsconfig.json as references.

There's a blog post that's a good introduction to it Optimizing multi-package apps with TypeScript Project References.

Usage

You can just use it via npx

npx update-ts-references --help

  Usage: update-ts-references [options]

  Options:
    --configName    The name of the config files which needs to be updated. Default: tsconfig.json 
    --rootConfigName    The name of the root config file which needs to be updated. Default: tsconfig.json
    --withoutRootConfig  If you will not have a tsconfig in the root directory or don't want to update it. Default: false
    --check         Checks if updates would be necessary (without applying them)
    --help          Show help
    --createTsConfig  Create default TS configs for packages where the main entry in the package.json have a ts|tsx extension (Note: respects the --configName parameter)
    --createPathMappings Create paths mappings under compilerOptions for a better IDE support. It respects the rootDir if no rootDir available it falls back to "src"
    --cwd           Set working directory. Default: /Users/john-doe/projects/my-project
    --verbose       Show verbose output. Default: false
    --usecase       Use a specific usecase configuration. Default: update-ts-references.yaml
    --strict    Expects always a tsconfig.json in the package directory. Default: false

or you add it as dev dependency and include it in the postinstall script in the package.json

yarn add update-ts-references --dev -W

 "scripts": {
   "postinstall": "update-ts-references"
 },
 "husky": {
    "hooks": {
      "pre-push": "update-ts-references --check"
    }
  },

enable pre-push via husky

npx husky add .husky/pre-push "npx update-ts-references --check"
git add .husky/pre-push

using --createTsConfig

Creates a basic tsconfig file for each package where the main entry in the package.json have a .ts or .tsx extension. It will respect the --configName parameter.

The output for the created file looks like the following

{
  "extends": "../tsconfig.base.json", // add's extends in case you have a base config in the root directory 
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "references": [ // will be added after running update-ts-references 
    {
      "path": "../some-other-package"
    }
  ]
}

using --createPathMappings

will create path mappings under compilerOptions for a better IDE support. The generated mappings respect the rootDir defined in the referenced tsconfig.json or jsconfig.json and only fall back to src when no rootDir is provided.

{
  "extends": "../tsconfig.base.json", // add's extends in case you have a base config in the root directory 
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "paths": { // will be added after running update-ts-references with --createPathMappings
      "@my-project/some-other-package": ["../some-other-package/src"]
    }
  },
  "references": [ // will be added after running update-ts-references 
    {
      "path": "../some-other-package"
    }
  ]
}

using update-ts-references.yaml for configurations

You can configure workspace paths via the update-ts-references.yaml file. This is useful if your repo is having no package.json or pnp-workspace.yaml in the root folder. Additional to that it can also being used to extend the paths config next to the normal workspace setup via npm, pnpm, yarn and lerna so you can include or exclude some packages.

Additional to that you can configure also the following options:

• configName (default: tsconfig.json)
• rootConfigName (default: tsconfig.json)
• createPathMappings (default: false)
• withoutRootConfig (default: false)
• ignorePathMappings (default: [])

Example configuration see here

using multiple configurations for different usecases

Executing update-ts-references with different configurations via the parameter --usecase.

about jsconfig.json support

When a dependency does not ship a tsconfig.json but provides a jsconfig.json, the reference automatically targets that file and the path mappings pick up its rootDir as well, if --createPathMappings is enabled. jsconfig.json files participate in package-level references, but they stay out of the root tsconfig.json.

in combination with the --configName argument

Currently the name of the config file derives from the the configName which is tsconfig.json and would look for jsconfig.json.

Example: --configName tsconfig.test.json would look for jsconfig.test.json

FAQ

Why is my pnpm workspace alias not working?

update-ts-references is currently not supporting Referencing workspace packages through aliases yet. See issue #13

License

Copyright 2023 mobile.de Developer: Mirko Kruschke

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.