Frontend Development Guidelines

Purpose

Establish consistency and best practices for Angular 19 frontend development using NG-ZORRO, RxJS, and modern TypeScript patterns.

When to Use This Skill

• •Creating new components or pages
• •Building new features
• •Fetching data with auto-generated API client (@ai-nx-starter/api-client) and RxJS
• •Setting up routing with Angular Router
• •Styling components with NG-ZORRO and LESS themes
• •Performance optimization
• •Organizing frontend code
• •TypeScript best practices

New Component Checklist

Creating a component? Follow this checklist:

• • Use @Component decorator with standalone: true (Angular 19 default) → component-patterns-guide.md
• • Lazy load feature modules via router or use dynamic component loading for heavy components → component-patterns-guide.md
• • Handle loading states in template with *ngIf and NG-ZORRO nz-spin → loading-and-error-states-guide.md
• • Use auto-generated @ai-nx-starter/api-client services with RxJS operators → data-fetching-guide.md
• • Import from packages: @ai-nx-starter/types, @ai-nx-starter/api-client
• • Styles: Inline if <100 lines, separate .less file if >100 lines → styling-guide.md
• • Use component methods for event handlers (avoid inline arrow functions in templates) → component-patterns-guide.md
• • Export component class (named export, not default)
• • Use *ngIf="data$ | async as data" pattern for observables (no manual subscriptions) → data-fetching-guide.md
• • Use NzMessageService or NzNotificationService for user notifications → loading-and-error-states-guide.md
• • Apply OnPush change detection strategy for performance → performance-guide.md
• • Implement OnDestroy and unsubscribe from manual subscriptions (or use takeUntilDestroyed()) → performance-guide.md
• • Write tests for business logic, user interactions, and data fetching → testing-guide.md

New Feature Checklist

Creating a feature? Set up this structure:

• • Create features/{feature-name}/ directory in apps/web-ui/src/app/ → file-organization-guide.md
• • Create subdirectories: components/, services/, models/, guards/, directives/ (as needed) → file-organization-guide.md
• • Define DTOs/types in @ai-nx-starter/types package (shared with backend)
• • Use auto-generated API services from @ai-nx-starter/api-client (NO manual HTTP services) → data-fetching-guide.md
• • Create feature routing module: {feature-name}-routing.module.ts or use standalone route config → routing-guide.md
• • Configure lazy loading in parent router: loadChildren or loadComponent → routing-guide.md
• • Create feature barrel export: index.ts for public API → file-organization-guide.md
• • Apply OnPush change detection to all feature components → performance-guide.md
• • Handle loading states with *ngIf and NG-ZORRO nz-spin or nz-skeleton → loading-and-error-states-guide.md
• • Use RxJS operators (map, switchMap, catchError) for data transformation → data-fetching-guide.md
• • Implement error handling with @ai-nx-starter/backend-common exception types → loading-and-error-states-guide.md
• • Add route guards if authentication/authorization required → common-patterns-guide.md
• • Write tests for components, services, guards, and business logic → testing-guide.md

Import Aliases Quick Reference

Defined in: tsconfig.base.json lines 20-24

Key Rules:

• •✅ ALWAYS use package aliases for cross-package imports
• •✅ Import DTOs from @ai-nx-starter/types (shared with backend)
• •✅ Use API services from @ai-nx-starter/api-client (auto-generated)
• •❌ NEVER import from @ai-nx-starter/data-access-layer in frontend code
• •❌ NEVER use relative paths for package imports like ../../../packages/types

Common Imports Cheatsheet

// Angular Core & RxJS
import { Component, OnInit, OnDestroy, ChangeDetectionStrategy, inject } from '@angular/core';
import { CommonModule } from '@angular/common';
import { Observable, Subject } from 'rxjs';
import { map, switchMap, catchError, takeUntil, tap } from 'rxjs/operators';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

// NG-ZORRO Components (import as needed)
import { NzButtonModule } from 'ng-zorro-antd/button';
import { NzCardModule } from 'ng-zorro-antd/card';
import { NzGridModule } from 'ng-zorro-antd/grid';
import { NzSpinModule } from 'ng-zorro-antd/spin';
import { NzTableModule } from 'ng-zorro-antd/table';
import { NzFormModule } from 'ng-zorro-antd/form';
import { NzInputModule } from 'ng-zorro-antd/input';
import { NzMessageService } from 'ng-zorro-antd/message';
import { NzNotificationService } from 'ng-zorro-antd/notification';

// Angular Router
import { Router, ActivatedRoute } from '@angular/router';
import { RouterModule } from '@angular/router';

// Angular Forms
import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';

// Auto-generated API Client (NO manual HTTP services!)
import { UserService, PostService, AuthService } from '@ai-nx-starter/api-client';

// Shared Types from monorepo
import { PostDto, UserDto, CreatePostDto } from '@ai-nx-starter/types';

// Feature Components (local imports)
import { LoaderComponent } from '../components/loader/loader.component';
import { HeaderComponent } from '../components/header/header.component';

Component Patterns

Modern Angular components use:

• •@Component decorator with TypeScript for type safety
• •Lazy loading via router (loadComponent) for code splitting
• •*ngIf with nz-spin or nz-skeleton for loading states
• •OnPush change detection for performance

Key Concepts:

• •Lazy load heavy components (DataGrid, charts, rich editors)
• •Use *ngIf template directives for loading/error states
• •Apply OnPush change detection strategy
• •Component structure: Decorator → Inputs/Outputs → Lifecycle → Methods

📖 Complete Guide: resources/component-patterns-guide.md

Data Fetching

Modern data fetching uses:

• •Auto-generated API client from @ai-nx-starter/api-client (NO manual HTTP services)
• •RxJS Observables with operators (finalize, catchError, tap, switchMap)
• •Service layer with BehaviorSubject for state management and caching
• •Template-based loading states with *ngIf and nz-spin

Key Concepts:

• •Use auto-generated API services (ApiUserService, ApiPostService, etc.)
• •Service layer with BehaviorSubject for caching and state
• •RxJS operators for data transformation and error handling
• •Cache-first strategies to reduce API calls
• •Parallel fetching with forkJoin and combineLatest

📖 Complete Guide: resources/data-fetching-guide.md

File Organization

features/ vs components/:

• •features/: Domain-specific features (users, teams, auth)
• •components/: Truly reusable UI (loader, header, error-boundary)

Feature Subdirectories:

features/
  my-feature/
    components/       # Feature components
    services/         # State management with BehaviorSubject
    models/           # Frontend-specific types
    guards/           # Route guards
    directives/       # Custom directives

Key Concepts:

• •Feature-based organization in apps/web-ui/src/app/features/
• •Package aliases for imports: @ai-nx-starter/*
• •kebab-case naming for all files (user-list.component.ts)
• •Services with BehaviorSubject for state management
• •Lazy loading via Angular Router

📖 Complete Guide: resources/file-organization-guide.md

Styling

Inline vs Separate:

• •<100 lines: Inline in .component.less file
• •

  100 lines: Organize with section comments in .component.less

Primary Method:

• •Use LESS for component styles
• •Theme variables: @primary-color, @padding-md, @component-background
• •Component-scoped in .component.less files

NG-ZORRO Grid:

<div nz-col [nzXs]="24" [nzMd]="12">  // ✅ Responsive grid
<div nz-col [nzSpan]="12">            // ✅ Fixed width

Key Concepts:

• •LESS preprocessing with theme variables
• •2 space indentation (project standard)
• •kebab-case for class names
• •Use ::ng-deep sparingly (only for child components)

📖 Complete Guide: resources/styling-guide.md

Routing

Angular Router - Configuration-Based:

• •Define routes in app.routes.ts
• •Lazy load with loadComponent / loadChildren
• •Route guards for authentication/authorization
• •Route data for breadcrumbs/titles

Example:

export const routes: Routes = [
  {
    path: 'users',
    loadComponent: () => import('./features/users/user-list.component').then((m) => m.UserListComponent),
    canActivate: [authGuard],
    data: { breadcrumb: 'Users' },
  },
];

Key Concepts:

• •Lazy loading for code splitting
• •Route guards (canActivate, canDeactivate)
• •Resolvers for data prefetching
• •Navigation with Router service or routerLink
• •Child routes with <router-outlet>

📖 Complete Guide: resources/routing-guide.md

Loading & Error States

CRITICAL RULE: No Early Returns

<!-- ❌ NEVER - Causes layout shift -->
<div *ngIf="loading"><nz-spin></nz-spin></div>
<div *ngIf="!loading"><nz-table [nzData]="users"></nz-table></div>

<!-- ✅ ALWAYS - Consistent layout -->
<nz-spin [nzSpinning]="loading">
  <nz-table [nzData]="users"></nz-table>
</nz-spin>

Why: Prevents Cumulative Layout Shift (CLS), better UX

Loading Patterns:

• •nz-spin with [nzSpinning] - Loading overlay (preferred)
• •nz-skeleton - Skeleton loading for initial loads
• •Template with fixed container height

Error Handling:

• •Use NzMessageService for user feedback
• •NzNotificationService for rich content
• •RxJS catchError for error handling
• •HTTP interceptors for global errors

📖 Complete Guide: resources/loading-and-error-states-guide.md

Performance

Optimization Patterns:

• •OnPush change detection - Use for all components (most important!)
• •trackBy functions - For all *ngFor loops
• •Computed signals - Memoized expensive calculations
• •Debounced search - RxJS debounceTime (300-500ms)
• •Memory leak prevention - takeUntilDestroyed or takeUntil pattern

Key Optimizations:

• •OnPush only checks when @Input() changes or events fire
• •trackBy prevents DOM recreation in lists
• •Immutable data patterns (create new references)
• •Virtual scrolling for large lists (100+ items)
• •Lazy load modules and heavy libraries

📖 Complete Guide: resources/performance-guide.md

TypeScript

Standards:

• •Strict mode enabled, no any type
• •Explicit return types on functions and methods
• •Type imports: import type { ClientUserDto } from '@ai-nx-starter/types'
• •JSDoc comments on Input/Output decorators
• •Utility types (Partial, Pick, Omit, Required, Record)

Key Patterns:

• •Typed Observables and BehaviorSubjects
• •Type guards for narrowing unknown types
• •Optional chaining (?.) and nullish coalescing (??)
• •Generic services and components
• •Interface for objects, type for unions

📖 Complete Guide: resources/typescript-standards-guide.md

Common Patterns

Covered Topics:

• •AuthService for authentication and current user
• •Reactive Forms with validators (built-in and custom)
• •NG-ZORRO Modal and dialog patterns
• •NG-ZORRO Table with pagination, sorting, filtering
• •Mutation patterns with auto-generated API client
• •BehaviorSubject services for state management

Key Patterns:

• •AuthService with currentUser$, login, logout, hasRole
• •Form validation with Validators and custom validators
• •Modal service for confirm dialogs
• •Table with server-side or client-side operations
• •Cache invalidation after mutations

📖 Complete Guide: resources/common-patterns-guide.md

Complete Examples

Full Working Examples:

• •Modern component with OnPush, RxJS, auto-generated API client
• •Complete feature structure with routing, services, guards
• •BehaviorSubject service for caching and state management
• •Reactive forms with validation and API integration
• •List component with filtering, sorting, pagination

Key Examples:

• •User profile component with loading states and error handling
• •Feature module with lazy loading and route guards
• •Service layer with BehaviorSubject caching
• •Form component with reactive validation
• •Table component with NG-ZORRO and client-side filtering

📖 Complete Guide: resources/complete-examples-guide.md

Project-Specific Extensions

This project includes additional utilities, decorators, and conventions beyond standard Angular:

Configuration

• •AppConfigService: All configuration MUST go through AppConfigService (in api-client package)
• •Config file: /apps/web-ui/src/assets/config.json (generated from Docker ENV variables)
• •NO hardcoded configuration values in components/services

Component Defaults

• •Components are standalone: false by default (use standalone: true only when specified)
• •Always use separate files for HTML, LESS, and TypeScript

Styling Utilities

Helper classes from theme-general.less:

• •Margins/padding: mt-1, p-2, etc.
• •Font weights: fw-bold, fw-light, etc.
• •Form sections: Use predefined form-section class

Global styling rules:

• •HTML base element styles can ONLY be overridden in apps/web-ui/src/assets/styles/theme.less
• •NO font or background color modifications in component .less files
• •ALL colors MUST use theme variables

Available Decorators

Project-specific decorators in core/:

• •@catchError() - Error handling wrapper
• •@log() - Method logging
• •@measure() - Performance measurement
• •@debounce(300) - Input debouncing
• •@engagement() - User engagement tracking
• •@requireRole('admin') - Role-based access control
• •@minFeatureFlag('feature') - Feature flag requirements

Available Components

Utility components in core/:

• •Busy indicator component
• •Display Flow component (for async operations)
• •Standardized context menu component

Available Directives

Project-specific directives:

• •appHideInProd - Hide elements in production
• •Role directive (TODO: implement)

Available Utilities

Helper functions:

• •sleep() - Delays/testing function

Form Validation

• •Use FormGroupService for handling complex form validation
• •Reference: features/zorro-components/forms

Icons

• •Update icons module when using new icons: /shared/icons/icons.module.ts

Internationalization

• •Default language: en_US
• •Currently supporting en_US only
• •Code prepared for future multi-language support

Navigation Guide

Related Skills

• •backend-dev-guidelines: Backend API patterns that frontend consumes