NX Library Build - Quick Fix Guide

Last Updated: November 13, 2025

🚨 "Cannot find module" Error?

If you see this error when building a library:

❌ error TS2307: Cannot find module '@libs-foundational/core-models'

Root Cause: TypeScript declarations are in the wrong location.

Quick Fix:

1. Remove rootDir from the dependency's tsconfig.lib.json:

   # Example: fixing core-models
   # Edit: libs/libs-foundational/core-models/tsconfig.lib.json
   # Remove this line:
   "rootDir": "./src",
   

2. Clear caches:

   nx reset && rm -rf dist/ tmp/
   

3. Rebuild the dependency:

   nx build <dependency-name> --skip-nx-cache
   

4. Rebuild your library:

   nx build <your-library> --skip-nx-cache
   

✅ New Library Checklist

When creating a new library, follow these rules:

1. tsconfig.lib.json - DO NOT use rootDir

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "../../../dist/libs/<path-to-lib>",
    // ❌ DO NOT ADD: "rootDir": "./src"
    "declaration": true,
    "declarationMap": true
  }
}

2. project.json - Use Custom Builder

{
  "targets": {
    "build": {
      "executor": "nx:run-commands",
      "outputs": ["{workspaceRoot}/dist/libs/<path-to-lib>"],
      "options": {
        "command": "node tools/scripts/build/build-angular-library.js <lib-path>"
      },
      "defaultConfiguration": "production",
      "dependsOn": ["^build"]
    }
  }
}

3. Verify Output Structure

# Build your library
nx build my-new-lib

# Check output structure
ls -la dist/libs/<path-to-lib>/index.*

# Expected (✅ CORRECT):
# dist/libs/<path-to-lib>/
#   ├── index.d.ts      ← At ROOT level
#   ├── index.js
#   └── lib/            ← Implementation files nested

# NOT expected (❌ WRONG):
# dist/libs/<path-to-lib>/
#   └── src/            ← Extra /src/ directory
#       ├── index.d.ts
#       └── index.js

🔧 Common Issues

Issue 1: Build succeeds but consuming app fails

Symptom: Library builds fine, but apps importing it show "Cannot find module"
Cause: Declaration files are nested under /src/ in dist
Fix: Remove rootDir from tsconfig.lib.json

Issue 2: ng-packagr can't find dependencies

Symptom: error TS2307 during ng-packagr build
Cause: Dependency declarations are in wrong location
Fix: Fix the dependency library first, then rebuild

Issue 3: Changes not taking effect

Symptom: Same errors after making config changes
Cause: NX is serving cached builds
Fix: Clear caches: nx reset && rm -rf dist/ tmp/

📚 Reference

• Full Analysis: BUILD_SYSTEM_FIX_SUMMARY.md
• Detailed Technical Docs: BUILD_ANALYSIS_COMPLETE.md
• Custom Builder: tools/scripts/build/build-angular-library.js

🎯 Key Principles

1. Never use rootDir in library configs
2. Use custom builder for consistency
3. Always verify output structure
4. Clear caches after config changes

Questions? Check the full documentation in BUILD_SYSTEM_FIX_SUMMARY.md