🔍 Angular Template Error Detection Guide

⚠️ Prerequisites

Before following this guide, ensure your TypeScript configuration is correct:

• ✅ No "File not found" errors in Problems panel
• ✅ typescript.tsserver.experimental.enableProjectDiagnostics: false in .vscode/settings.json
• ✅ No duplicate path aliases in tsconfig.base.json

If you have TypeScript config errors, see: TypeScript Configuration Final Solution

The Problem

In large NX monorepos, Angular Language Service provides inline template errors but significantly slows down VS Code and conflicts with NX tooling.

✅ Our Solution: Three-Layer Detection

We use a layered approach for catching template errors:

1. ESLint (Fast, IDE) - Catches common template issues in Problems panel
2. Build-Time (Complete) - Catches all TypeScript template errors during compilation
3. Angular Language Service (Optional) - Deep debugging when needed

🎯 How It Works

1. ESLint Template Linting (Always On, IDE) ✅

ESLint catches common template issues and shows them in the Problems panel:

What ESLint Catches:

• ✅ Basic template syntax errors
• ✅ Accessibility issues
• ✅ Best practice violations
• ✅ Some binding errors
• ⚠️ Cannot catch: Complex TypeScript type errors (like missing methods)

Where You See Errors:

• 📋 Problems panel (Cmd+Shift+M)
• 🔴 Red squiggles in HTML files
• ⚡ Fast, no performance impact

Configuration:

• Root: .eslintrc.json → HTML rules
• Library: libs/editor-ui/.eslintrc.json → Angular-specific rules

2. Build-Time Template Checking (Always On, Terminal) ✅

Complete TypeScript checking catches ALL template errors during builds:

# Terminal errors will show ALL Angular template issues
yarn nx serve gograb-space
yarn nx build editor-ui

Configuration Location:

• tsconfig.base.json → angularCompilerOptions.strictTemplates: true
• libs/editor-ui/tsconfig.lib.json → Full strict Angular options

What You Get:

• ✅ 100% of template errors (including complex TypeScript types)
• ✅ Same errors that CI/CD will catch
• ✅ Catches missing methods, wrong types, etc.
• ✅ Most reliable error source

Example Error Output:

✘ [ERROR] TS2339: Property 'onWidgetAlignment' does not exist on type 'EditorUiComponent'.
    
    libs/editor-ui/src/lib/components/editor-ui/editor-ui.component.html:26:25:
      26 │ (widgetAlignment)="onWidgetAlignment($event)"

⚠️ Limitation: Only shows during build, not in Problems panel

3. Angular Language Service (Optional, Deep Debugging) 🔧

For intensive template debugging or real-time type checking, you can temporarily enable Angular Language Service:

Step 1: Install Extension

1. Open Extensions (Cmd+Shift+X)
2. Search: Angular Language Service
3. Install the official one by Angular

Step 2: Enable in Settings

Edit .vscode/settings.json and uncomment these lines:

"angular.log": "verbose",
"angular.enable-strict-mode-prompt": false,
"angular.experimental-ivy": true,
"angular.forceStrictTemplates": true,

Step 3: Reload VS Code

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

Step 4: When Done - Disable It Again!

1. Comment out those lines again
2. Reload VS Code
3. Enjoy fast performance again

🚀 Best Practices

For Daily Development:

• ❌ Don't install Angular Language Service
• ✅ Watch the terminal for template errors during nx serve
• ✅ Fix errors immediately when they appear

For Template Debugging Sessions:

• ✅ Enable temporarily when working on complex templates
• ✅ Disable after 1-2 hours of debugging
• ⚠️ Warning: Leaving it on will slow your IDE significantly

For Code Reviews:

• ✅ Run full build: yarn nx build <project>
• ✅ Check terminal output for template errors
• ✅ Never merge if build has template errors

🔧 Why This Approach?

Performance Comparison:

Why Not Both All The Time?

In a large NX monorepo with 30+ libraries:

• Angular Language Service analyzes ALL templates continuously
• Competes with NX Console, TypeScript, and ESLint
• Can cause 3-5 second delays on every keystroke
• Uses 2-4GB extra memory

📊 Error Coverage by Layer

ESLint Catches (~60%):

• ✅ Accessibility issues
• ✅ Best practice violations
• ✅ Basic syntax errors
• ✅ *ngFor without trackBy
• ✅ Click without keyboard events
• ❌ Cannot catch: TypeScript type errors, missing methods

Build-Time Catches (100%):

• ✅ Unknown properties/directives
• ✅ Type errors in templates
• ✅ Unknown components/pipes
• ✅ Missing required inputs
• ✅ Wrong event bindings
• ✅ Structural directive errors
• ✅ Template reference errors
• ✅ Everything ESLint catches + TypeScript errors

🎓 Your New Workflow

Step-by-Step:

1. Write code in your component/template
2. Check Problems panel (Cmd+Shift+M) for ESLint warnings
   • Fix accessibility and best practice issues immediately
3. Save and watch terminal for build errors
   • Fix any TypeScript errors (missing methods, wrong types, etc.)
4. Commit when both are clean

Example Flow:

1. Type: <div (click)="doSomething()">Click me</div>
   └─> ESLint: ⚠️ "Click events should have keyboard events"
   └─> Fix: Add (keyup.enter)

2. Type: (widgetAlignment)="handleAlignment($event)"
   └─> ESLint: ✅ No warnings
   └─> Terminal: ❌ "Property 'handleAlignment' does not exist"
   └─> Fix: Add method to component

3. Both clean ✅
   └─> Commit!

Benefits:

• ⚡ ESLint catches 60% instantly in IDE
• 🎯 Build catches the remaining 40% in ~1 second
• 🚀 IDE stays fast and responsive

🆘 Troubleshooting

"I don't see any errors in my terminal"

Your dev server might not be running:

yarn nx serve gograb-space

"I need inline errors for a complex refactor"

Enable Angular Language Service temporarily (see above), but disable it after.

"Can I use ESLint instead?"

ESLint can catch some template issues with @angular-eslint/template, but not all. We use it for style/best practices, not type checking.

📝 Summary

Our three-layer approach gives you the best of all worlds:

1. 🟢 ESLint - Quick feedback in Problems panel (60% of errors)
2. 🟢 Build-Time - Complete coverage in terminal (100% of errors)
3. 🟡 Language Service - Optional for deep debugging

Workflow:

1. Check Problems panel → Fix ESLint warnings
2. Watch terminal → Fix TypeScript errors
3. Both clean? → Commit!

Benefits:

• ⚡ Fast IDE - No performance hit
• 📋 IDE feedback - ESLint in Problems panel
• 🎯 Complete coverage - Build catches everything
• 🔧 Flexible - Language Service when needed

Remember: You'll see ~60% of errors instantly in the IDE, and 100% within 1 second in the terminal!