Core Lib Fix

Documentation for Developers

Core Library Import Fix

Problem

When building the core-angular library, TypeScript cannot resolve imports from @libs-foundational/core-models module, resulting in errors like:

error TS2307: Cannot find module '@libs-foundational/core-models' or its corresponding type declarations.

This happens because ng-packagr (used by Angular libraries) doesn't properly resolve TypeScript path mappings from tsconfig.base.json during the build process.

Root Cause

The issue occurs because:

  1. Path Mapping Limitation: While tsconfig.base.json defines @libs-foundational/core-models path mapping, ng-packagr doesn't always respect these mappings during Angular library compilation
  2. Module Resolution: Angular's build system expects modules to be available in node_modules or as proper package references
  3. Build Order: The core library needs to be built first, but the Angular compiler can't find the types during compilation

Solution: Symlink Setup

We use a symlink script to create a node_modules/@libs-foundational/core-models symlink that points to the actual source code:

node scripts/setup-core-symlink.js

What the Script Does

  1. Creates Symlink: Links node_modules/@libs-foundational/core-models → libs/core-models/src
  2. Removes Existing: Cleans up any existing symlink to avoid conflicts
  3. Enables Resolution: Allows ng-packagr to find the @libs-foundational/core-models module during compilation

Complete Fix Process

Step 1: Ensure Core Library Exports

Make sure libs/core-models/src/index.ts exports all required types:

// Export everything from the lib
export * from './lib';

// Responsive Types
export * from './lib/types/responsive';

// Editor UI Types
export * from './lib/types/editor-ui';

// Space Map Types
export * from './lib/types/space-map';

// All types
export * from './lib/types';

// Widget utilities and functions
export * from './lib/utils/widget-utils';

// Page utilities and functions
export * from './lib/types/page.types';

// Widget types and enums
export * from './lib/types/widget.types';

// Page template types
export * from './lib/types/page-template.types';

Step 2: Run Symlink Script

node scripts/setup-core-symlink.js

Step 3: Build Core Library

yarn nx build core --skip-nx-cache

Step 4: Build Core-Angular Library

yarn nx build core-angular --skip-nx-cache

When to Run This Script

Run the symlink script in these scenarios:

  1. Fresh Clone: After cloning the repository
  2. Clean Install: After running yarn install or rm -rf node_modules
  3. Build Issues: When getting @libs-foundational/core-models import errors
  4. CI/CD: Include in your build pipeline
  5. New Developer Setup: Part of onboarding process

Verification

After running the script, verify it worked:

# Check if symlink exists
ls -la node_modules/@libs-foundational/core-models

# Should show something like:
# @libs-foundational/core-models -> ../../libs/core-models/src

Troubleshooting

Symlink Already Exists

# Remove and recreate
rm node_modules/@libs-foundational/core-models
node scripts/setup-core-symlink.js

Permission Issues

# On macOS/Linux, you might need to run with sudo
sudo node scripts/setup-core-symlink.js

Windows Issues

On Windows, you might need to run as Administrator or enable Developer Mode for symlinks.

Alternative Solutions

If symlinks don't work in your environment:

  1. Copy Instead of Symlink: Modify the script to copy files instead
  2. Build Dependencies: Ensure core library is built before core-angular
  3. Path Mapping: Use relative imports instead of @libs-foundational/core-models alias

Prevention

To prevent this issue in the future:

  1. Documentation: Always document this step in README
  2. Package.json Scripts: Add to package.json scripts
  3. CI/CD: Include in automated build process
  4. Developer Onboarding: Include in setup instructions

Related Files