Teaching Claude Modern Angular with Custom Instructions

### Angular Development

For detailed Angular guidelines including modern syntax, signals, and control flow, see **[angular-best-practices.md](angular-best-practices.md)**.
Use these best practices whenever you're working with Angular.

# Angular Best Practices

This document contains Angular-specific coding standards and modern syntax guidelines for the project.

## Modern Angular Syntax

### Standalone Components

Always generate standalone components:

```bash
ng generate component <name> --standalone
```

### Signals Input Syntax

**ALWAYS use the modern Angular signals input syntax instead of @Input decorators:**

```typescript
// Correct - Modern signals input syntax
export class MyComponent {
    myInput = input<MyType>(); // Optional input
    requiredInput = input.required<MyType>(); // Required input

    ngOnInit() {
        const value = this.myInput(); // Access with parentheses
        const required = this.requiredInput(); // Access with parentheses
    }
}
```

```typescript
// Avoid - Old @Input decorator syntax
export class MyComponent {
    @Input() myInput: MyType;
    @Input({ required: true }) requiredInput: MyType;
}
```

**Key points:**
-   Use `input<Type>()` for optional inputs
-   Use `input.required<Type>()` for required inputs
-   Access input values with parentheses: `this.myInput()`
-   This provides better type safety and integrates with Angular's signal-based reactivity

### Reactive UI Updates with Signals

**Use Angular signals for reactive state management that automatically updates the UI:**

```typescript
// Correct - Using signals for reactive state
export class DashboardComponent {
    private logger = inject(LogService);
    currentUser = signal<User | null>(null);
    loading = signal<boolean>(true);

    // Computed values update automatically
    isAdmin = computed(() => this.currentUser()?.role === UserRole.Admin);

    // Effect runs when signals change
    constructor() {
        effect(() => {
            if (this.isAdmin()) {
                this.logger.info('[DashboardComponent] User is admin');
            }
        });
    }
}
```

```html
<!-- Template automatically updates when signals change -->
@if (isAdmin()) {
<div>Admin content</div>
} @if (loading()) {
<div>Loading...</div>
}
```

### Control Flow Syntax

**ALWAYS use the modern Angular control flow syntax instead of structural directives:**

```html
<!-- Correct - New control flow syntax -->
@if (condition) {
<p>Content when true</p>
} @else if (otherCondition) {
<p>Alternative content</p>
} @else {
<p>Fallback content</p>
} @for (item of items(); track item.id) {
<div>{{ item.name }}</div>
} @empty {
<p>No items found</p>
} @switch (status()) { @case ('loading') {
<div>Loading...</div>
} @case ('error') {
<div>Error occurred</div>
} @default {
<div>Content loaded</div>
} }
```

```html
<!-- Avoid - Old structural directive syntax -->
<div *ngIf="condition">Content</div>
<div *ngFor="let item of items; trackBy: trackById">{{ item.name }}</div>
<div [ngSwitch]="status">
    <div *ngSwitchCase="'loading'">Loading...</div>
</div>
```

**Key Benefits:**
-   Better performance and smaller bundle sizes
-   Improved type checking and IDE support
-   More readable and maintainable templates
-   Built-in empty states with @empty

## State Management

### Services with BehaviorSubjects

Use services with BehaviorSubjects for traditional state management:

```typescript
// Common pattern in services
private dataSubject = new BehaviorSubject<Data[]>([]);
public data$ = this.dataSubject.asObservable();
```

### Prefer Signals for New Code

For new components and services, prefer using Angular signals over traditional RxJS patterns where appropriate. Signals provide better ergonomics and performance for synchronous state.

## Component Guidelines

### Loading States

Use skeleton loaders instead of spinners when loading data to provide a better user experience. Skeleton screens show the layout structure while content loads, reducing perceived wait time.

## Testing

-   **Frontend Tests**: Jasmine/Karma or Jest
-   Focus on component logic and service methods
-   Test reactive state with signals
-   Test control flow logic

## System Requirements

### Node.js Version Requirements

**Angular 20 requires specific Node.js versions:**

-   **Node.js 20.x**: Minimum version 20.19
-   **Node.js 22.x**: Minimum version 22.12 (recommended)
-   **Node.js 24.x**: Supported from version 24.0 (latest LTS)

**Important Notes:**

-   Node.js 18.x is no longer supported (reached EOL March 27, 2025)
-   Node.js 22.0 to 22.10 are not supported
-   Use `node --version` to check your current Node.js version