{"id":15002,"library":"typescript-workspace-plugin","title":"TypeScript Workspace Plugin","description":"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.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/spion/typescript-workspace-plugin","tags":["javascript"],"install":[{"cmd":"npm install typescript-workspace-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-workspace-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-workspace-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a TypeScript language service plugin and requires a compatible TypeScript installation to function.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"import 'typescript-workspace-plugin'; // Not a code import","symbol":"Plugin Activation","correct":"{\n  \"plugins\": [{\"name\": \"typescript-workspace-plugin\"}]\n}"},{"note":"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`.","wrong":"// Incorrectly trying to use 'paths' in tsconfig.json for workspace sources\n{\n  \"compilerOptions\": {\n    \"paths\": { \"*\": [\"packages/*/src\"] }\n  }\n}","symbol":"Workspace Sources Configuration","correct":"{\n  \"workspaces\": [\"packages/*\"],\n  \"workspace-sources\": {\n    \"*\": [\"packages/*/src\"]\n  }\n}"},{"note":"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.","wrong":"const plugin = require('typescript-workspace-plugin'); // Not a CommonJS module","symbol":"Plugin Name Reference","correct":"\"name\": \"typescript-workspace-plugin\""}],"quickstart":{"code":"/* tsconfig.json for an individual package */\n{\n  \"extends\": \"../../tsconfig.base.json\", // Example extend\n  \"compilerOptions\": {\n    \"outDir\": \"./lib\",\n    \"rootDir\": \"./src\"\n  },\n  \"plugins\": [\n    {\"name\": \"typescript-workspace-plugin\"}\n  ],\n  \"include\": [\"src\"]\n}\n\n/* Top-level package.json for the monorepo root */\n{\n  \"name\": \"my-monorepo\",\n  \"version\": \"1.0.0\",\n  \"private\": true,\n  \"workspaces\": [\n    \"packages/*\",\n    \"apps/*\"\n  ],\n  \"workspace-sources\": {\n    \"*\": [\"packages/*/src\", \"apps/*/src\"]\n  },\n  \"devDependencies\": {\n    \"typescript\": \"^4.9.5\", // Ensure compatible TS version\n    \"typescript-workspace-plugin\": \"^2.0.0\"\n  }\n}","lang":"json","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The editor's TypeScript language service is not using the TypeScript version installed within your project's `node_modules` (the workspace version).","error":"The TypeScript plugin 'typescript-workspace-plugin' could not be loaded."},{"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.","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.","error":"Cannot find module 'my-local-package' or its corresponding type declarations."}],"ecosystem":"npm"}