Frontend Dev Guidelines

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