Common Development Errors & Fixes

This document summarizes common TypeScript, Angular, and NX monorepo errors encountered during development and their solutions to prevent repetition.

⚠️ CRITICAL: Never use relative imports (e.g., libs/my-lib/src/...) as a workaround for import errors. Always fix the root cause by properly configuring tsconfig.base.json, ng-package.json, project.json, and tsconfig.lib.json. See Library Configuration Guide for proper setup.

1. TypeScript Import Errors

Error: Cannot find module '@core' or its corresponding type declarations

Root Cause: Missing or incorrect path mappings in tsconfig.json Fix: Replace with local type definitions or correct import paths

// ❌ Problematic
import type { SafeAny } from '@libs-foundational/core-models'; 

// ✅ Fixed
type SafeAny = any;

Error: Cannot find module '@editor-ui' or 'editor-ui/src/lib'

Root Cause: Missing or incorrect library configuration Fix: Ensure proper NX library alias is configured in tsconfig.base.json, and library has correct package.json, ng-package.json, and tsconfig.lib.json

// ❌ Wrong - Never use relative paths
import { EditorUiComponent } from 'libs/editor-ui/src/lib';
import { EditorUiComponent } from 'editor-ui/src/lib';

// ✅ Correct - Always use NX aliases
import { EditorUiComponent } from '@editor-ui';

Configuration Required:

// tsconfig.base.json
{
  "paths": {
    "@editor-ui": ["libs/editor-ui/src/index"]
  }
}

// libs/editor-ui/ng-package.json
{
  "lib": {
    "entryFile": "src/index.ts"
  }
}

2. Angular Template Errors

Error: 'ux-toast' is not a known element

Root Cause: Component not imported or selector mismatch Fix: Ensure component is in imports array and selector matches

// ✅ Component imports
imports: [CommonModule, UxToastComponent]

Error: Can't bind to 'highlight' since it isn't a known property of 'code'

Root Cause: Using non-existent directive Fix: Replace with standard Angular binding

<!-- ❌ Problematic -->
<code [highlight]="code"></code>

<!-- ✅ Fixed -->
<pre><code>{{ code }}</code></pre>

Error: Property 'value' does not exist on type 'EventTarget'

Root Cause: TypeScript strict typing on event targets Fix: Use Angular's $any() function or proper type casting

<!-- ❌ Problematic -->
(input)="updateSearchQuery($event.target.value)"

<!-- ✅ Fixed -->
(input)="updateSearchQuery($any($event.target).value)"

3. NX Monorepo Import Issues

⚠️ NEVER USE RELATIVE IMPORTS AS WORKAROUNDS
If you encounter import errors, the solution is ALWAYS to fix the library configuration, not to use relative paths like libs/my-lib/src/...

How to Properly Fix Library Import Errors

When you encounter Cannot find module '@my-lib' or similar errors, follow these steps:

Step 1: Verify tsconfig.base.json has the path alias

{
  "compilerOptions": {
    "paths": {
      "@my-lib": ["libs/my-lib/src/index"]
    }
  }
}

Step 2: Ensure library has ng-package.json

{
  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
  "lib": {
    "entryFile": "src/index.ts",
    "cssUrl": "inline"
  }
}

Step 3: Verify src/index.ts exists and exports public API

// libs/my-lib/src/index.ts
export * from './lib/my-component';
export * from './lib/my-service';

Step 4: Check project.json build configuration

{
  "targets": {
    "build": {
      "executor": "@nx/angular:ng-packagr-lite",
      "options": {
        "project": "libs/my-lib/ng-package.json"
      }
    }
  }
}

Step 5: Verify tsconfig.lib.json is properly configured

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "../../dist/out-tsc",
    "declaration": true,
    "declarationMap": true,
    "inlineSources": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["**/*.spec.ts", "src/test-setup.ts"]
}

Error: Static imports of lazy-loaded libraries are forbidden

Root Cause: Library alias is incorrectly configured as lazy-loaded in NX configuration Fix: Update library configuration to allow static imports - ensure package.json, project.json, and tsconfig.lib.json are properly configured

// ❌ Wrong - Never use relative paths as a workaround
import { ThemeManagerService } from 'libs/theme-system/theme-runtime/src';

// ✅ Correct - Use NX alias after fixing configuration
import { ThemeManagerService } from '@theme-runtime';

Configuration Fix:

1. Ensure the library has proper ng-package.json:

{
  "lib": {
    "entryFile": "src/index.ts"
  }
}

2. Verify tsconfig.base.json path alias:

{
  "paths": {
    "@theme-runtime": ["libs/theme-system/theme-runtime/src/index"]
  }
}

3. Check project.json doesn't mark library as lazy-loaded incorrectly

Error: Projects cannot be imported by a relative or absolute path

Root Cause: Using direct file paths instead of NX aliases Fix: Use proper NX library aliases

// ❌ Problematic
import { Component } from 'libs/ux-ui-core/src/lib';

// ✅ Fixed
import { Component } from '@ux-ui-core';

4. TypeScript Type Errors

Error: Property 'closed' does not exist on type 'unknown'

Root Cause: Missing type assertions for dynamic components Fix: Cast to proper component type

// ❌ Problematic
menuRef.instance.closed.subscribe(() => {});

// ✅ Fixed
(menuRef.instance as ContextMenuComponent).closed.subscribe(() => {});

Error: Type '"container"' is not comparable to type '"widget" | "text"'

Root Cause: Missing union type cases in switch statements Fix: Add all possible cases to type definitions

// ❌ Problematic
type: 'widget' | 'text'

// ✅ Fixed
type: 'widget' | 'text' | 'container' | 'image'

Error: Not all code paths return a value

Root Cause: Missing return statements in conditional branches Fix: Ensure all code paths return a value

// ❌ Problematic
private recoveryTimeoutEffect = effect(() => {
  if (!this.enableRecoveryOptions) return; // Missing return value
});

// ✅ Fixed
private recoveryTimeoutEffect = effect(() => {
  if (!this.enableRecoveryOptions) return undefined;
  // ... rest of logic
});

5. RxJS Deprecation Warnings

Error: '(): Promise<void>' is deprecated

Root Cause: Using deprecated toPromise() method Fix: Replace with firstValueFrom()

// ❌ Problematic
await this.store.dispatch(new CreatePage(createRequest)).toPromise();

// ✅ Fixed
await firstValueFrom(this.store.dispatch(new CreatePage(createRequest)));

6. CSS/SCSS Syntax Errors

Error: Comments in CSS use "/* ... */" instead of "//"

Root Cause: Using JavaScript-style comments in CSS Fix: Use proper CSS comment syntax

/* ❌ Problematic */
// Enhanced Navigation Controls

/* ✅ Fixed */
/* Enhanced Navigation Controls */

Error: Expected ":" [css-syntax-error]

Root Cause: Extra characters in CSS properties Fix: Remove invalid characters

/* ❌ Problematic */
padding-top: 1rem;z

/* ✅ Fixed */
padding-top: 1rem;

7. Package.json Issues

Error: Duplicate key in object literal

Root Cause: Duplicate keys in package.json scripts Fix: Rename duplicate keys

{
  "//2.1": "=== DASHBOARD AUTO-RELOAD COMMANDS ===",
  "//2.2": "=== DASHBOARD AUTO-RELOAD COMMANDS ==="
}

9. Interface and Type Definition Issues

Error: Property 'isExternal' does not exist on type union

Root Cause: Missing properties in union type definitions Fix: Use type assertion or add missing properties

// ❌ Problematic
@if (item.isExternal) {

// ✅ Fixed
@if ($any(item).isExternal) {

10. Angular Signal and Effect Issues

Error: Property 'rippleEffect' comes from an index signature

Root Cause: Using dot notation on Record types Fix: Use bracket notation for Record types

// ❌ Problematic
behaviors.rippleEffect = true;

// ✅ Fixed
behaviors['rippleEffect'] = true;

Prevention Guidelines

🚨 Most Important Rules

1. NEVER use relative imports (libs/...) as workarounds - Always fix configuration instead
2. ALWAYS use NX library aliases (@my-lib) for all library imports
3. Fix import errors properly by configuring:
   • tsconfig.base.json - Add/verify path aliases
   • ng-package.json - Set "entryFile": "src/index.ts"
   • project.json - Ensure proper build configuration
   • tsconfig.lib.json - Verify compiler options

📋 Additional Best Practices

4. Check component selectors match template usage
5. Use Angular's $any() function for complex type assertions in templates
6. Ensure all code paths return values in functions
7. Use proper CSS comment syntax (/* */ not //)
8. Replace deprecated RxJS methods with modern alternatives
9. Verify export names match class names exactly
10. Add all possible cases to union types and switch statements
11. Use bracket notation for Record<string, any> types
12. Test imports after library changes to ensure they still work

Quick Reference

• Import errors: Fix configuration files (tsconfig.base.json, ng-package.json, project.json) - NEVER use relative imports
• Template errors: Verify component imports and selectors
• Type errors: Use proper type assertions and complete type definitions
• NX errors: Always use library aliases (@my-lib), never relative paths (libs/my-lib/...)
• RxJS errors: Replace deprecated methods with modern alternatives
• CSS errors: Use proper CSS syntax and comment style

📚 Related Documentation

• Library Configuration Guide - Comprehensive guide to proper library setup
• public-api.ts → index.ts Migration - Standard entry point pattern
• Import/Export Patterns - Best practices for barrel exports
• NX Library Setup - Complete NX library configuration