TypeScript Monorepo Troubleshooting Guide

Quick fixes for common TypeScript configuration issues in NX monorepos.

🚨 Problem: "File not found" errors for inherited paths

Error Message:

File '/Users/.../libs/some-lib/src/index' not found.
The file is in the program because:
  Root file specified for compilation

✅ Solution Checklist (Apply in Order):

1. Check VS Code Settings (/.vscode/settings.json)

Problem: Experimental diagnostic setting breaks monorepos

{
  "typescript.tsserver.experimental.enableProjectDiagnostics": false  // ← Must be false!
}

Why: This setting was designed for small projects with 1-3 configs. In monorepos with 50+ libraries, it tries to load ALL configs simultaneously and can't handle complex inheritance chains.

2. Check Template Config (/tsconfig.templates/lib-coordinator.json)

Problem: Missing files: [] in template

{
  "extends": "../tsconfig.base.json",
  "compilerOptions": {
    "noEmit": true
  },
  "files": [],  // ← Must be present!
  "references": [
    { "path": "./tsconfig.lib.json" },
    { "path": "./tsconfig.spec.json" }
  ],
  "angularCompilerOptions": {
    "strictTemplates": true
  }
}

Why: Without files: [], all 100+ inherited paths from tsconfig.base.json are treated as "root compilation files".

3. Check for Duplicate Path Aliases (/tsconfig.base.json)

Problem: Multiple aliases pointing to same library

Diagnosis:

# Check if any library has duplicate aliases
grep '"@.*-ui"' tsconfig.base.json

Bad (causes errors):

{
  "paths": {
    "@ui-editor": ["libs/editor-ui/src/index"],      // ← Duplicate #1
    "@ui-editor/*": ["libs/editor-ui/src/*"],
    "@editor-ui": ["libs/editor-ui/src/index"],      // ← Duplicate #2
    "@editor-ui/*": ["libs/editor-ui/src/*"]
  }
}

Solutions:

Option A: Remove duplicate (recommended)

{
  "paths": {
    // Remove @ui-editor, keep only one alias
    "@editor-ui": ["libs/editor-ui/src/index"],
    "@editor-ui/*": ["libs/editor-ui/src/*"]
  }
}

Option B: Add explicit files: [] to affected library

// libs/editor-ui/tsconfig.json
{
  "extends": "../../tsconfig.templates/lib-coordinator.json",
  "compilerOptions": {
    "strict": true
  },
  "files": [],  // ← Explicit override for this specific library
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts"]
}

Why: Duplicate aliases confuse TypeScript's config inheritance, preventing files: [] from template from being respected.

🚨 Problem: Angular template errors not visible in IDE

See: Angular Template Errors Guide

Quick Check:

1. Are TypeScript errors fixed first? (see above)
2. Is build showing the error in terminal? (it should)
3. Want inline IDE errors? Enable Angular Language Service temporarily

Our Recommendation: Watch terminal during nx serve - you'll see errors within 1 second. No IDE slowdown.

🚨 Problem: Import autocomplete not working

Symptom: VS Code doesn't suggest @library imports

Solution:

# 1. Verify path exists in tsconfig.base.json
grep "@your-library" tsconfig.base.json

# 2. Restart TypeScript server
# Cmd+Shift+P → "TypeScript: Restart TS Server"

# 3. If still broken, clear caches
rm -rf .angular/cache .nx/cache dist/libs/*/tsconfig.tsbuildinfo

🚨 Problem: Slow TypeScript server / IDE lag

Causes & Solutions:

1. Too many diagnostics

// .vscode/settings.json
{
  "typescript.tsserver.experimental.enableProjectDiagnostics": false
}

2. Angular Language Service always on

• Only enable when actively debugging templates
• Disable immediately after

3. Not enough memory

// .vscode/settings.json
{
  "typescript.tsserver.maxTsServerMemory": 8192  // 8GB for large monorepos
}

📋 Verification Commands

After making config changes, run these to verify everything works:

# 1. Check VS Code setting
grep "enableProjectDiagnostics" .vscode/settings.json
# Expected: false

# 2. Check template has files:[]
grep "files" tsconfig.templates/lib-coordinator.json
# Expected: "files": []

# 3. Check for duplicate aliases
grep -E '"@[^"]*".*libs/' tsconfig.base.json | awk -F'[":]' '{print $NF}' | sort | uniq -d
# Expected: (no output = no duplicates)

# 4. Test a build
yarn nx build your-library-name
# Expected: Success, no "file not found" errors

# 5. Restart TS Server and check Problems panel
# Cmd+Shift+P → "TypeScript: Restart TS Server"
# Expected: No "file not found" errors in Problems panel

🔄 "I'm still having issues!"

Nuclear Option: Complete Reset

# 1. Clear all caches
rm -rf node_modules/.cache
rm -rf .angular/cache
rm -rf .nx/cache
rm -rf dist
rm -rf libs/*/tsconfig.tsbuildinfo

# 2. Restart VS Code completely
# Cmd+Q → Reopen

# 3. Rebuild dependencies
yarn install

# 4. Test
yarn nx build <your-library>

Still broken?

Check these files match the template pattern:

1. Template: /tsconfig.templates/lib-coordinator.json has files: []
2. VS Code: /.vscode/settings.json has enableProjectDiagnostics: false
3. Base paths: /tsconfig.base.json has no duplicate aliases
4. Individual libs: libs/*/tsconfig.json extends template and has include

Then: Full VS Code restart + clear all caches (see above)

📚 Related Documentation

• TypeScript Configuration Final Solution - Deep dive
• TypeScript Configuration Templates README - Template system
• Angular Template Errors Guide - Template error detection

💡 Key Principles (Remember These!)

1. files: [] in template prevents inherited paths from being root files
2. include in individual libs tells TypeScript what to actually compile
3. enableProjectDiagnostics: false is required for monorepos with 30+ libs
4. No duplicate aliases - each library should have ONE primary alias
5. Angular Language Service is optional - terminal shows 100% of errors