TypeScript Workspace Plugin

2.0.1 · active · verified Sun Apr 19

typescript-workspace-plugin is a language service plugin for TypeScript that adds robust support for monorepo setups, specifically those using Yarn-like workspaces. It allows individual packages within a workspace to maintain independent `tsconfig.json` files while enabling the TypeScript language service to correctly resolve local package sources, rather than relying solely on `node_modules` typings. This restores critical IDE features such as 'go to definition,' 'find references,' and accurate type checking across locally linked dependencies. The current stable version is 2.0.1. Its release cadence is irregular, driven by community needs and TypeScript updates. A key differentiator is its ability to maintain independent package configuration while ensuring full language service functionality within a monorepo, addressing a common pain point for developers working with interwoven local packages.

Common errors

```
The TypeScript plugin 'typescript-workspace-plugin' could not be loaded.
```
cause The editor's TypeScript language service is not using the TypeScript version installed within your project's `node_modules` (the workspace version).

fix Open the command palette (Ctrl+Shift+P or Cmd+Shift+P), search for 'TypeScript: Select TypeScript Version...', and select 'Use Workspace Version'. Restart the editor if necessary.
```
Cannot find module 'my-local-package' or its corresponding type declarations.
```
cause The `workspace-sources` in `package.json` might be misconfigured, or the plugin itself might not be loaded/active, preventing the language service from mapping local package sources correctly.

fix Verify that `typescript-workspace-plugin` is correctly listed in `tsconfig.json`'s `plugins` array. Check the `workspace-sources` glob patterns in your top-level `package.json` to ensure they point to the correct source directories of your workspace packages. Also, confirm you are using the workspace TypeScript version in your editor.

Warnings

breaking The plugin explicitly requires that the TypeScript version used by your editor's language service must be the one installed in your workspace's `node_modules` (the 'workspace version'), not a globally installed or editor-bundled version. If the workspace TypeScript is not used, the plugin will not load or function.
Fix: In VS Code, open the command palette (Cmd+Shift+P or Ctrl+Shift+P), type 'TypeScript: Select TypeScript Version...', and choose 'Use Workspace Version'. A reload of the editor might also be necessary.
gotcha Ensure that the `workspace-sources` configuration in your top-level `package.json` accurately reflects the source directories of all packages within your monorepo. Incorrect paths will lead to unresolved imports and broken language service features.
Fix: Carefully review the glob patterns in `workspace-sources`. For example, if packages are in `libs/` and sources are in `src/`, use `"libs/*/src"`. Verify `package.json` structure.

Install

npm install typescript-workspace-plugin npm
yarn add typescript-workspace-plugin yarn
pnpm add typescript-workspace-plugin pnpm

Imports

Plugin Activation
wrong:
```
import 'typescript-workspace-plugin'; // Not a code import
```
correct:
```
{
  "plugins": [{"name": "typescript-workspace-plugin"}]
}
```
The plugin is activated by adding its name to the `plugins` array within your package's `tsconfig.json` file. It is not imported directly into JavaScript/TypeScript code.
Workspace Sources Configuration
wrong:
```
// Incorrectly trying to use 'paths' in tsconfig.json for workspace sources
{
  "compilerOptions": {
    "paths": { "*": ["packages/*/src"] }
  }
}
```
correct:
```
{
  "workspaces": ["packages/*"],
  "workspace-sources": {
    "*": ["packages/*/src"]
  }
}
```
The core source mapping for the plugin is configured via the `workspace-sources` field in your top-level `package.json`, alongside the `workspaces` entry. This is distinct from `tsconfig.json`'s `paths`.
Plugin Name Reference
wrong:
```
const plugin = require('typescript-workspace-plugin'); // Not a CommonJS module
```
correct:
```
"name": "typescript-workspace-plugin"
```
The plugin is referenced by its exact package name string within `tsconfig.json` configuration. It does not expose any runtime JavaScript/TypeScript modules for direct `import` or `require` statements.

Quickstart

This quickstart demonstrates the essential configuration for integrating the typescript-workspace-plugin into a monorepo. It shows how to add the plugin entry to individual package `tsconfig.json` files and define the `workspace-sources` mapping in the top-level `package.json` to enable correct language service resolution across workspace packages.

/* tsconfig.json for an individual package */
{
  "extends": "../../tsconfig.base.json", // Example extend
  "compilerOptions": {
    "outDir": "./lib",
    "rootDir": "./src"
  },
  "plugins": [
    {"name": "typescript-workspace-plugin"}
  ],
  "include": ["src"]
}

/* Top-level package.json for the monorepo root */
{
  "name": "my-monorepo",
  "version": "1.0.0",
  "private": true,
  "workspaces": [
    "packages/*",
    "apps/*"
  ],
  "workspace-sources": {
    "*": ["packages/*/src", "apps/*/src"]
  },
  "devDependencies": {
    "typescript": "^4.9.5", // Ensure compatible TS version
    "typescript-workspace-plugin": "^2.0.0"
  }
}

view raw JSON →