Anti-Pattern Fix: Relative Imports Documentation Update

October 21, 2025

Status: ✅ COMPLETE

🎯 Problem Identified

The common-errors/index.md documentation was incorrectly suggesting using relative imports as a "fix" for library import errors. This was promoting an anti-pattern that causes:

• ❌ Build system bypassing
• ❌ Type checking issues
• ❌ Broken IDE features
• ❌ Maintenance nightmares
• ❌ Inconsistent codebase

🔧 What Was Fixed

1. Removed Bad Advice About Relative Imports

Before (WRONG):

// ✅ Fixed (THIS WAS WRONG!)
import { EditorUiComponent } from 'libs/editor-ui/src/lib';

After (CORRECT):

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

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

2. Added Prominent Warnings

Added critical warning at the top of the document:

⚠️ 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.

3. Added Comprehensive Configuration Guide

Added new section: "How to Properly Fix Library Import Errors" with 5 steps:

1. ✅ Verify tsconfig.base.json path aliases
2. ✅ Ensure ng-package.json exists and is configured
3. ✅ Verify src/index.ts exports public API
4. ✅ Check project.json build configuration
5. ✅ Verify tsconfig.lib.json compiler options

4. Updated Prevention Guidelines

Before:

• Generic advice about using NX aliases

After:

• 🚨 Most Important Rules section with explicit warnings
• Clear hierarchy: Configuration fixes come FIRST
• Specific files to check and configure

5. Enhanced Quick Reference

Before:

- Import errors: Check tsconfig.json path mappings

After:

- Import errors: Fix configuration files (tsconfig.base.json, ng-package.json, project.json) - NEVER use relative imports

📝 Sections Updated

Updated Sections

1. Error: Cannot find module '@editor-ui'

   • Changed from suggesting relative imports to configuration fixes
   • Added configuration examples

2. Error: Static imports of lazy-loaded libraries are forbidden

   • Changed from suggesting relative imports to configuration fixes
   • Added proper configuration steps

3. Prevention Guidelines

   • Restructured with priority hierarchy
   • Added configuration checklist

4. Quick Reference

   • Made configuration-first approach explicit
   • Added "NEVER use relative imports" warnings

New Sections Added

5. How to Properly Fix Library Import Errors

   • Complete 5-step configuration guide
   • Code examples for each configuration file
   • Proper import patterns

6. Related Documentation

   • Links to library configuration guides
   • Links to import/export patterns
   • Links to NX library setup

✅ Key Messages Now Clear

DO ✅

• Always use NX library aliases (@my-lib)
• Fix configuration files when imports fail
• Follow the 5-step configuration guide
• Export through src/index.ts
• Configure tsconfig.base.json path aliases

DON'T ❌

• Never use relative imports (libs/my-lib/src/...)
• Don't bypass the build system
• Don't use workarounds instead of proper fixes
• Don't skip configuration files

📊 Impact

🎓 Why This Matters

The Problem with Relative Imports

When developers use relative imports like libs/my-lib/src/...:

1. Bypasses Build System: The library's build process is skipped
2. Type Issues: TypeScript declarations may not be generated correctly
3. IDE Problems: Autocomplete and go-to-definition break
4. Inconsistent: Different import styles across codebase
5. Maintenance: Harder to refactor and reorganize code

The Correct Approach

When using NX aliases like @my-lib:

1. ✅ Build System Works: Library is properly built and packaged
2. ✅ Types Correct: TypeScript declarations are generated and used
3. ✅ IDE Happy: Full IDE support with autocomplete
4. ✅ Consistent: Same import style everywhere
5. ✅ Maintainable: Easy to refactor and reorganize

📚 Related Documentation

This fix complements:

• public-api.ts → index.ts Migration
• Library Configuration Guide
• Import/Export Patterns
• NX Library Setup

✅ Verification

# No relative import suggestions in documentation
grep -n "libs/.*src" docs/english/public/development/common-errors/index.md

# Result: Only in "Wrong" examples marked with ❌

🎉 Summary

The documentation has been completely rewritten to:

1. ❌ Remove bad advice about using relative imports
2. ✅ Add proper guidance on configuration files
3. ⚠️ Add prominent warnings against anti-patterns
4. 📚 Add comprehensive guide with 5 configuration steps
5. 🔗 Link to related docs for complete context

Developers will now be guided to the CORRECT solution (fix configuration) instead of the WRONG workaround (use relative imports).

Updated By: AI Assistant
Review Date: October 21, 2025
Status: ✅ Complete and verified