@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

- [x] Lerna(lerna.json)
- [x] Yarn's workspaces
- [x] Workspace ranges (workspace:) #29
- [x] npm's workspaces
- [ ] pnpm workspaces
- Refer to
- [x] 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 / 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 /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 /.

For example. You can update /tsconfig.json to following.

``json5
{
"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:
`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

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

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

`json
"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

`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.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature`
5. Submit a pull request :D

Author

- github/azu
- twitter/azu_re

License

MIT © azu