@monorepo-utils/workspaces-to-typescript-project-references

@monorepo-utils/workspaces-to-typescript-project-references

This tool convert lerna/npm/yarn workspaces to TypeScript's Project References.

You can keep package dependencies synchronized between lerna/npm/yarn workspaces and TypeScript.

This monorepo use this tool as self-integration.

Features

• Sync between monorepo workspaces and TypeScript's Project References
• Preserve tsconfig.json's comments
• Custom Plugin support

Supports

• Lerna(lerna.json)
• Yarn's workspaces
  • Workspace ranges (workspace:) #29
• npm's workspaces
• pnpm workspaces
  • Refer to https://github.com/Bessonov/set-project-references
• Custom workspaces
  • Plugin support

Install

Install with npm:

npm install @monorepo-utils/workspaces-to-typescript-project-references

Usage

This tool provides updating feature and testing feature.

Usage
  $ workspaces-to-typescript-project-references


Options
  --root             [Path:string] Root directory of the monorepo. 
                     Default: current working directory

  --check            If set the flag, check only differences of tsconfig.json and does not update tsconfig.json.
                     If the check is failed, exit status 1. It is useful for testing.       
  --plugin           [Path:string] Path to plugin script.
                     Load the plugin script as module and use it. 
                       
  --tsconfigPath     [Path:string] Use alternative config path inside the package. e.g.: tsconfig.test.json
                     Default: tsconfig.json

  --includesRoot     If set the flag, update <root>/<tsconfigPath> with all project references.
                     It is useful to check all packages at once.

  --includesLocal    If set the flag, includes ./tsconfig.*.json

Examples
  # Update project references in tsconfig.json
  $ workspaces-to-typescript-project-references
  # Test on CI
  $ workspaces-to-typescript-project-references --check

  # Update <root>/tsconfig.json that includes all references to packages
  $ workspaces-to-typescript-project-references --includesRoot
  $ workspaces-to-typescript-project-references --includesRoot --check

:memo: Tips --includesRoot

If --includesRoot is passed, this tool also update references in <root>/<tsconfigPath>.

For example. You can update <root>/tsconfig.json to following.

{
  "compilerOptions": {
    // ...
  },
  "files": [],
  "include": [],
  "exclude": [],
  "references": [
    {
      "path": "packages/@monorepo-utils/collect-changelog"
    },
    {
      "path": "packages/@monorepo-utils/package-utils"
    },
    {
      "path": "packages/@monorepo-utils/workspaces-to-typescript-project-references"
    }
  ]
}

You can build all packages at once by tsc --build . in root dir.

• Example: package.json and tsconfig.json
• Optimizing multi-package apps with TypeScript Project References | by Mirko Kruschke | eBay Tech Berlin
• Migrating Large TypeScript Codebases To Project References — Developer Tooling (2021)

Plugin

@monorepo-utils/workspaces-to-typescript-project-references support to plugin for custom resolution.

You can write a plugin for own monorepo tools.

For example, Bolt has a workspaces, but a bit different with lerna/yarn style. Bolt require bolt.workspaces in package.json.

get-monorepo-packages support bolt's workspaces. So, you can write bolt-plugin.js as following.

bolt-plugin.js:

const getPackages = require("get-monorepo-packages");
const plugin = (options) => {
    const monorepoPackages = getPackages(options.rootDir);
    return {
        supports() {
            return monorepoPackages.length > 0;
        },
        getAllPackages() {
            return monorepoPackages;
        },
        getDependencies(packageJSON) {
            const dependencies = Object.entries(packageJSON.dependencies ?? {});
            const devDependencies = Object.entries(packageJSON.devDependencies ?? {});
            return [...dependencies, ...devDependencies].map((dep) => {
                return {
                    name: dep[0]
                };
            });
        },
        resolve({ name }) {
            const matchPkg = monorepoPackages.find((info) => {
                return info.package.name === name;
            });
            if (!matchPkg) {
                return null;
            }
            return matchPkg.location;
        }
    };
};
module.exports.plugin = plugin;

You can use this plugin via --plugin flag.

$ npm install @monorepo-utils/workspaces-to-typescript-project-references -g
$ workspaces-to-typescript-project-references --plugin ./bolt-plugin.js

For more details, See Plugin interface

Examples

For example, monorepo-utils it-self use this tool. monorepo-utils use lerna and yarn workspaces.

• workspaces definition on root's package.json

{
  "workspaces": {
    "packages": [
      "packages/*",
      "packages/@monorepo-utils/*"
    ]
  }
}

• @monorepo-utils/workspaces-to-typescript-project-references has dependencies to @monorepo-utils/package-utils

  "dependencies": {
    "@monorepo-utils/package-utils": "^2.2.0",
    "comment-json": "^3.0.3",
    "meow": "^7.1.1"
  }

To run workspaces-to-typescript-project-references and update tsconfig.json

  "references": [
    {
      "path": "../package-utils"
    }
  ]

As another examples, Following project use this tools.

• textlint

Related

• Infer project references from common monorepo patterns / tools · Issue #25376 · microsoft/TypeScript

Changelog

See Releases page.

Running tests

Install devDependencies and Run npm test:

npm test

Contributing

Pull requests and stars are always welcome.

For bugs and feature requests, please create an issue.

• Fork it!
• Create your feature branch: git checkout -b my-new-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request :D

Author

• github/azu
• twitter/azu_re

License

MIT © azu