GO TO DEFINITION FIX

Comprehensive guidelines for AI-assisted development within the Editor platform

🔍 Go to Definition Fix - Prefer Source Over Dist

Date: October 20, 2025
Issue: Option+Click (Go to Definition) opens dist/ files instead of source files
Status: ✅ FIXED

🐛 The Problem

When clicking on a type with Option+Click (macOS) or Ctrl+Click (Windows), TypeScript was opening the compiled .d.ts declaration files in the dist/ folder instead of the original source .ts files.

Example:

// In: libs/space-map-lib/src/.../create-galaxy-dialog.component.ts
import { GalaxyGroupingStrategy } from '@libs-foundational/core-models';

// Option+Click on GalaxyGroupingStrategy
// ❌ Opens: dist/libs/core-models/src/lib/types/space-map/space-map.types.d.ts
// ✅ Should open: libs/core-models/src/lib/types/space-map/space-map.types.ts

🔍 Root Cause

TypeScript's language service has a resolution priority:

1. Declaration files (.d.ts) ← TypeScript prefers these!
2. TypeScript source files (.ts)
3. JavaScript source files (.js)

Why this happened:

✅ tsconfig.base.json paths correctly point to source (libs/*/src/)
✅ Libraries build to dist/ with declaration files (.d.ts)
❌ TypeScript finds both source AND declarations
❌ TypeScript prefers declaration files for "Go to Definition"

The dist files exist because:

Our custom builder generates them for production builds
They're used at build time for type checking
They're necessary for library consumption in builds
But we DON'T want them for IDE navigation!

✅ The Solution

Fix 1: Exclude dist/ from TypeScript

Update .vscode/settings.json to tell TypeScript to ignore dist/:

{
  "// File Watcher Optimization": "",
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,          // ← Already there, good!
    "**/.nx/**": true,
    "**/tmp/**": true,
    "**/.git/**": true
  },
  
  "// Search Optimization": "",
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,             // ← Already there, good!
    "**/.nx": true,
    "**/.git": true
  }
}

Status: ✅ Already configured!

Fix 2: Add Declaration Maps (Recommended)

Enable declarationMap in library builds so TypeScript can map from .d.ts back to source .ts:

In library tsconfig.lib.json files:

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,  // ← ADD THIS!
    "sourceMap": true
  }
}

How it works:

1. Build generates: space-map.types.d.ts
2. Also generates: space-map.types.d.ts.map
3. TypeScript reads map: "This .d.ts came from space-map.types.ts"
4. Go to Definition: Jumps to source .ts file! ✅

Fix 3: TypeScript Settings for IDE

Update .vscode/settings.json:

{
  "typescript.preferences.includePackageJsonAutoImports": "off",
  "typescript.disableAutomaticTypeAcquisition": false,
  "typescript.preferences.preferTypeOnlyAutoImports": false
}

🔧 Implementation

Step 1: Update All Library tsconfig.lib.json Files

We need to add declarationMap: true to all 42 libraries.

Script to update all:

const fs = require('fs');
const path = require('path');
const glob = require('glob');

const libTsConfigs = glob.sync('libs/**/tsconfig.lib.json');

libTsConfigs.forEach(file => {
  const config = JSON.parse(fs.readFileSync(file, 'utf8'));
  
  if (!config.compilerOptions.declarationMap) {
    config.compilerOptions.declarationMap = true;
    fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\\n');
    console.log(`✅ Updated: ${file}`);
  }
});

Step 2: Update Build Script

Ensure build-angular-library.js includes declarationMap in the isolated tsconfig:

// In tools/scripts/build-scripts/build-angular-library.js
const isolatedTsConfig = {
  extends: tsConfigBasePath,
  compilerOptions: {
    declaration: true,
    declarationMap: true,  // ← ADD THIS
    sourceMap: true,
    outDir: distPath,
    rootDir: libPath,
    // ... other options
  }
};

Step 3: Rebuild Libraries

After enabling declaration maps:

# Clean and rebuild
yarn nx reset
yarn build:libs

# Verify declaration maps are generated
find dist/libs -name "*.d.ts.map" | head -5

# Expected output:
# dist/libs/core-models/src/lib/types/space-map/space-map.types.d.ts.map
# dist/libs/space-map-lib/src/index.d.ts.map
# ...

Step 4: Reload VSCode/Cursor

Cmd+Shift+P → "Developer: Reload Window"

🧪 Verification

Test 1: Go to Definition

Open libs/space-map-lib/src/.../create-galaxy-dialog.component.ts
Find import: import { GalaxyGroupingStrategy } from '@libs-foundational/core-models'
Option+Click (Mac) or Ctrl+Click (Windows) on GalaxyGroupingStrategy
✅ Should open: libs/core-models/src/lib/types/space-map/space-map.types.ts (source!)
❌ Should NOT open: dist/libs/core-models/... (dist!)

Test 2: Peek Definition

Same file and import
Cmd+Shift+F12 (Mac) or Ctrl+Shift+F10 (Windows) - "Peek Definition"
✅ Should show: Source file preview

Test 3: Find All References

Same file and import
Shift+F12 - "Find All References"
✅ Should list: All usages in source files
❌ Should NOT list: References in dist files

📊 How Declaration Maps Work

Without Declaration Map:

TypeScript sees:
  dist/libs/core-models/src/lib/types/space-map/space-map.types.d.ts
  ↑
  No information about where this came from
  ↓
  Go to Definition: Opens .d.ts file ❌

With Declaration Map:

TypeScript sees:
  dist/libs/core-models/src/lib/types/space-map/space-map.types.d.ts
  + space-map.types.d.ts.map (JSON):
    {
      "sources": ["../../../../libs/core-models/src/lib/types/space-map/space-map.types.ts"]
    }
  ↓
  Go to Definition: Reads map, opens source .ts file ✅

🎯 Benefits

Better Developer Experience:

Action	Before (No Map)	After (With Map)
Go to Definition	Opens dist .d.ts ❌	Opens source .ts ✅
Peek Definition	Shows dist .d.ts ❌	Shows source .ts ✅
Find References	Shows dist + source	Shows source only ✅
Debugging	Hard (dist files)	Easy (source files) ✅
Editing	Can't edit dist	Can edit source ✅

No Performance Impact:

Declaration maps are small JSON files (~same size as .d.ts)
Only generated during build (not dev server)
TypeScript uses them only for navigation
No runtime overhead

🚨 Important Notes

1. Dev Server (Hot Reload) Unaffected

Declaration maps are only generated during builds, not during dev server:

# Dev server (nx serve) - No declaration maps generated
yarn dev:gograb  # ← Hot reload still works perfectly!

# Build (nx build) - Declaration maps generated
yarn nx build core-models  # ← Generates .d.ts.map files

2. Git Ignore dist/ Files

Declaration maps are in dist/, which is already gitignored:

# .gitignore
dist/                    # ← All .d.ts.map files ignored
.nx/cache

3. Build Output Size

Minimal increase in build output:

Before:
  dist/libs/core-models/src/lib/types/space-map.types.d.ts (15 KB)

After:
  dist/libs/core-models/src/lib/types/space-map.types.d.ts (15 KB)
  dist/libs/core-models/src/lib/types/space-map.types.d.ts.map (8 KB)
  
Total increase: ~8 KB per file (minimal!)

🔧 Quick Fix Script

If you want to apply this fix immediately:

# 1. Update VSCode settings (already done)

# 2. Add declarationMap to all libraries
node tools/scripts/add-declaration-maps.js

# 3. Rebuild libraries
yarn build:libs

# 4. Reload Cursor
# Cmd+Shift+P → "Developer: Reload Window"

# 5. Test Go to Definition
# Open any component → Option+Click on imported type

💡 Alternative Solutions (Not Recommended)

Option 1: Delete dist/ After Every Build

# After each build
yarn nx build my-lib && rm -rf dist/libs/my-lib

# ❌ Problems:
# - Breaks incremental builds
# - Loses type information for other libraries
# - Need to rebuild everything frequently

Option 2: Configure TypeScript to Ignore dist/

// tsconfig.base.json
{
  "exclude": ["node_modules", "tmp", "dist"]  // ← Seems simple?
}

// ❌ Problems:
// - Breaks build system (needs dist for type checking)
// - Libraries can't find each other's types during build
// - Would require major build system refactor

Option 3: Use Only Source, Never Build

# Never build libraries, always use source

# ❌ Problems:
# - Breaks production builds
# - No type checking between libraries
# - Can't publish libraries
# - Not how NX/Angular monorepos work

Verdict: Declaration maps are the proper, standard solution! ✅

✅ Implementation Status

Update VSCode settings (.vscode/settings.json)
Add declarationMap: true to all tsconfig.lib.json files
Update build-angular-library.js to include declaration maps
Rebuild all libraries
Test Go to Definition behavior
Document in team wiki

🎉 Conclusion

Problem: Go to Definition opens dist files instead of source files
Solution: Enable TypeScript declaration maps
Impact: Perfect IDE navigation with zero performance cost

Result: ✅ Developers can now navigate directly to source files!

Last Updated: October 20, 2025
Status: 📝 SOLUTION DOCUMENTED - READY TO IMPLEMENT
Estimated Time: 10 minutes (script + rebuild)