[FEATURE] LSP findReferences should work across TypeScript monorepo project references
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
In TypeScript monorepos using project references, the LSP findReferences operation only finds references within the queried file's package, not across the entire monorepo. This severely limits the usefulness of LSP for code navigation in multi-package repositories.
Example scenario:
Given a monorepo structure:
/root
├── tsconfig.json # has references: [backend, client, common, ...]
├── packages/
│ ├── common/
│ │ ├── tsconfig.json # composite: true
│ │ └── src/types.ts # exports type UserId
│ ├── backend/
│ │ ├── tsconfig.json # references: [common]
│ │ └── src/... # imports UserId from common
│ └── client/
│ ├── tsconfig.json # references: [common]
│ └── src/... # imports UserId from common
When running findReferences on UserId from packages/common/src/types.ts:
| Query Location | References Found |
|----------------|------------------|
| From common (where type is defined) | ~40 refs (common only) |
| From backend (a consumer) | ~80 refs (common + backend) |
| Actual usage (via grep) | 50+ files across all packages |
Root cause: The TypeScript language server is initialized with the nearest tsconfig.json from the queried file, not the root tsconfig.json. TypeScript's findReferences can traverse into dependencies but not out to dependent packages.
Proposed Solution
Allow Claude Code to initialize the TypeScript language server with the root tsconfig.json that contains all project references, so findReferences has visibility into the entire monorepo.
Possible implementations:
- Auto-detect monorepo root: When a
tsconfig.jsonwith"references"is found at the workspace root, use it as the project entry point for the TS server.
- Configuration option: Add an LSP setting like:
``json``
{
"lsp": {
"typescript": {
"projectRoot": "./tsconfig.json"
}
}
}
- Project-level
.lsp.json(builds on #39472): Allow specifying tsserver initialization options per-project.
Alternative Solutions
Current workarounds:
- Query
findReferencesfrom a file in a consuming package rather than the definition package (gets partial coverage) - Use grep for cross-package discovery, LSP for within-package precision
- Run multiple LSP queries from different packages and merge results
These are clunky and require the LLM to know about the monorepo structure ahead of time.
Priority
High - Needed for critical functionality
Feature Category
IDE integration and language intelligence
Use Case Example
- User asks Claude: "Find all usages of the
UserIdtype" - Claude uses LSP
findReferenceson the type definition inpackages/common - Current: Only finds ~40 references within
commonpackage - Expected: Finds all 80+ references across
common,backend,client,web, etc.
This is especially important for:
- Refactoring types/interfaces used across packages
- Understanding the impact of API changes
- Navigating large monorepo codebases
Additional Context
Evidence from testing:
# LSP findReferences from packages/common (definition location)
Found ~40 references across 12 files (all within packages/common)
# LSP findReferences from packages/backend (same symbol, queried from consumer)
Found ~80 references across 28 files (common + backend)
# Grep for the symbol across *.ts
Found 50+ files across: backend, common, client, web, cli
The root tsconfig.json already has proper project references configured - the issue is that the TS language server isn't using it as its entry point.
Related: #39472 (Project-scoped LSP configuration) - could be extended to support this use case.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗