# Code Style and Conventions Standards for Angular

This document outlines the coding style and conventions standards for Angular projects. Adhering to these guidelines ensures code consistency, readability, maintainability, and performance in Angular applications. These standards are designed to complement the official Angular Style Guide and incorporate modern best practices for the latest versions of Angular.

## 1. Code Formatting

Consistent code formatting is crucial for readability and maintainability. We use Prettier for automated formatting, configured to match these standards.

### 1.1. Whitespace and Indentation

* **Do This:** Use two spaces for indentation. Configure your IDE and Prettier to enforce this automatically.

* **Don't Do This:** Use tabs or mixed spaces and tabs.

* **Why:** Two-space indentation improves readability without excessive horizontal scrolling.

"""typescript

// Do This

function calculateArea(width: number, height: number): number {

return width * height;

}

// Don't Do This

function calculateArea(width: number, height: number): number {

return width * height;

}

"""

### 1.2. Line Length

* **Do This:** Keep lines of code within a maximum of 120 characters.

* **Don't Do This:** Allow lines to exceed this limit without breaking them appropriately.

* **Why:** Shorter lines improve readability, especially on smaller screens and when comparing files side-by-side.

"""typescript

// Do This

const formattedAddress = "${addressLine1}, ${addressLine2}, ${city}, ${state} ${zipCode}, ${country}";

// Don't Do This

const formattedAddress = "${addressLine1}, ${addressLine2}, ${city}, ${state} ${zipCode}, ${country, anotherProperty}";

"""

### 1.3. Blank Lines

* **Do This:** Use blank lines to separate logical blocks of code, such as between functions, classes, and sections within a function.

* **Don't Do This:** Use excessive or inconsistent blank lines.

* **Why:** Blank lines enhance readability by visually separating different parts of the code.

"""typescript

// Do This

function calculateSum(a: number, b: number): number {

return a + b;

}

function calculateProduct(a: number, b: number): number {

return a * b;

}

// Don't Do This

function calculateSum(a: number, b: number): number {return a + b;}function calculateProduct(a: number, b: number): number {return a * b;}

"""

### 1.4. Operators

* **Do This:** Use spaces around operators for readability.

* **Don't Do This:** Omit spaces around operators.

* **Why:** Consistent spacing improves code clarity and reduces the chance of misreading expressions

"""typescript

// Do This

const total = price * quantity + tax;

// Don't Do This

const total=price*quantity+tax;

"""

## 2. Naming Conventions

Consistent naming conventions make your code easier to understand.

### 2.1. General Naming

* **Do This:** Use descriptive and meaningful names.

* **Don't Do This:** Use abbreviations or single-letter names unless in simple loop counters.

* **Why:** Clear names make the code self-documenting.

"""typescript

// Do This

const userFirstName = 'John';

// Don't Do This

const fn = 'John';

"""

### 2.2. TypeScript Specific Naming

* **Do This:**

* Classes: Use PascalCase (e.g., "UserService").

* Interfaces: Use PascalCase prefixed with "I" (e.g., "IUser").

* Variables/Properties: Use camelCase (e.g., "userAge").

* Constants: Use UPPER_SNAKE_CASE (e.g., "MAX_RETRIES").

* Functions/Methods: Use camelCase (e.g., "getUser()").

* **Don't Do This:** Deviate from the established naming conventions.

* **Why:** Consistent naming provides type and purpose context, improving code readability.

"""typescript

// Do This

interface IUser {

id: number;

firstName: string;

}

class UserService {

readonly MAX_USERS = 100;

getUser(id: number): IUser {

// ...

}

// Don't Do This

interface user { // Incorrect. Using 'I' prefix is important in Angular.

userID: number;

userName: string;

}

class user_service { // Incorrect.

readonly maxUsers = 100;

get_user(id: number): user {

// ...

}

"""

### 2.3. Angular Specific Naming

* **Do This:**

* Components: Use dash-case for selectors (e.g., "app-user-profile") and PascalCase for the class name (e.g., "UserProfileComponent"). Suffix component class names with "Component".

* Services: Use PascalCase and suffix with "Service" (e.g., "AuthService").

* Modules: Use PascalCase and suffix with "Module" (e.g., "SharedModule").

* Pipes: Use camelCase for the name and PascalCase and suffix with "Pipe" for the class name (e.g., "dateFormat" and "DateFormatPipe").

* Directives: Use camelCase for the name and PascalCase and suffix with "Directive" for the class name (e.g., "highlightText" and "HighlightTextDirective").

* **Don't Do This:** Inconsistent suffixes or naming styles for Angular artifacts.

* **Why:** Angular's architectural structure becomes more identifiable with consistent naming.

"""typescript

// Components

@Component({

selector: 'app-user-profile',

templateUrl: './user-profile.component.html',

styleUrls: ['./user-profile.component.css']

})

export class UserProfileComponent implements OnInit {

// ...

}

// Services

@Injectable({

providedIn: 'root'

})

export class AuthService {

// ...

}

// Modules

@NgModule({

declarations: [],

imports: [

CommonModule

]

})

export class SharedModule { }

// Pipes

@Pipe({

name: 'dateFormat'

})

export class DateFormatPipe implements PipeTransform {

// ...

}

// Directives

@Directive({

selector: '[appHighlightText]'

})

export class HighlightTextDirective {

// ...

}

"""

## 3. Stylistic Consistency

Consistent style enhances code readability, ease of review, and collaboration.

### 3.1. Code Comments

* **Do This:**

* Include JSDoc-style comments for all classes, interfaces, methods, and properties.

* Properly document parameters and return types.

* Use comments to explain complex logic.

* Keep comments up-to-date with the code.

* **Don't Do This:**

* Write obvious comments like "// Set name" before "this.name = name;".

* Leave commented-out code in the codebase.

* **Why:** Good comments provide context and explain the 'why' behind the code.

"""typescript

/**

* User service for managing user data.

@Injectable({

providedIn: 'root'

})

export class UserService {

/**

* Retrieves a user by ID.

* @param id User ID.

* @returns Observable with user data.

getUser(id: number): Observable {

// Fetches user data from API

return this.http.get("/api/users/${id}");

}

"""

### 3.2. Template Syntax

* **Do This:**

* Use consistent spacing within templates (e.g., "{{ user.name }}").

* Group related attributes together.

* Break long lines for readability.

* **Don't Do This:** Inconsistent spacing and organization in templates.

* **Why:** Readable templates are essential for front-end maintainability.

"""html

{{ user.name }}

{{user.name}}

"""

### 3.3. RxJS Best Practices

* **Do This:**

* Unsubscribe from observables in components to prevent memory leaks using "takeUntil" or the "async" pipe.

* Use pure functions for operators like "map", "filter", and "reduce".

* Handle errors gracefully using RxJS error handling operators ("catchError", "retry").

* **Don't Do This:** Forgetting to unsubscribe from observables, using side effects in RxJS operators, or ignoring errors.

* **Why:** RxJS is fundamental in Angular; proper usage avoids common pitfalls.

"""typescript

// Do This

import { Subject, takeUntil } from 'rxjs';

@Component({ ... })

export class UserListComponent implements OnInit, OnDestroy {

users$: Observable;

private destroy$ = new Subject();

constructor(private userService: UserService) { }

ngOnInit(): void {

this.users$ = this.userService.getUsers().pipe(

takeUntil(this.destroy$)

);

}

ngOnDestroy(): void {

this.destroy$.next();

this.destroy$.complete();

}

//In the template:

// Don't Do This

@Component({ ... })

export class UserListComponent implements OnInit {

users: IUser[] | undefined;

constructor(private userService: UserService) { }

ngOnInit(): void {

this.userService.getUsers().subscribe(users => {

this.users = users; //Not unsubscribing

});

}

"""

### 3.4. Dependency Injection

* **Do This:** Prefer constructor injection for dependencies. Leverage the "providedIn: 'root'" option for injectable services, using "providedIn: NgModule" only when service scope needs to limited to specified module.

* **Don't Do This:** Use "@Optional" and "@Host" injectors without appropriate justification. Avoid property injection.

* **Why:** Constructor injection improves testability and makes dependencies explicit. Using "providedIn: 'root'" leads to better tree-shaking and reduces bundle size.

"""typescript

// Do This

@Injectable({

providedIn: 'root'

})

export class AuthService {

constructor(private http: HttpClient) { }

}

@Component({...})

export class LoginComponent {

constructor(private authService: AuthService) {}

}

// Don't Do This

@Injectable()

export class AuthService { // No providedIn. Unless specifically overriding AuthService at the module level, use "providedIn: 'root'"

constructor(private http: HttpClient) { }

}

@Component({...})

export class LoginComponent {

@Inject(AuthService) authService: AuthService; // Property Injection: Avoid

}

"""

## 4. Angular Specific Guidelines

These guidelines are specific to Angular and address components, modules, services, and other areas.

### 4.1. Components

* **Do This:**

* Keep components small and focused on a single responsibility.

* Use "@Input()" and "@Output()" for component communication.

* Use lifecycle hooks appropriately. Prioritize "OnPush" change detection when possible for performance. Use trackBy functions with "ngFor".

* **Don't Do This:** Create large, monolithic components or directly manipulate the DOM.

* **Why:** Small, focused components are easier to test, understand, and reuse.

"""typescript

// Do This

@Component({

selector: 'app-user-card',

templateUrl: './user-card.component.html',

styleUrls: ['./user-card.component.css'],

changeDetection: ChangeDetectionStrategy.OnPush

})

export class UserCardComponent implements OnInit {

@Input() user: IUser | undefined;

@Output() userSelected = new EventEmitter();

ngOnInit(): void {

// Initialization logic

}

selectUser(): void {

if (this.user) {

this.userSelected.emit(this.user);

}

export class UserListComponent {

users: IUser[] = [...];

trackByUserId(index: number, user: IUser): number {

return user.id;

}

// Don't Do This

@Component({

selector: 'app-user-profile',

templateUrl: './user-profile.component.html',

styleUrls: ['./user-profile.component.css']

})

export class UserProfileComponent implements OnInit {

// Excessive logic related to multiple modules, services, etc.

}

"""

### 4.2. Modules

* **Do This:**

* Use feature modules to organize related components, services, and directives.

* Use a shared module for commonly used components, directives, and pipes.

* Use the "forRoot()" pattern for modules that provide services to the entire application.

* **Don't Do This:** Declare components in multiple modules or import modules unnecessarily.

* **Why:** Modular architecture improves maintainability, testability, and reusability.

"""typescript

// Feature Module: user.module.ts

@NgModule({

declarations: [UserListComponent, UserCardComponent],

imports: [CommonModule, SharedModule], // Import SharedModule.

exports: [UserListComponent]

})

export class UserModule { }

// Shared Module: shared.module.ts

@NgModule({

declarations: [DateFormatPipe],

imports: [CommonModule],

exports: [DateFormatPipe, CommonModule] // Export CommonModule for components.

})

export class SharedModule {

static forRoot(): ModuleWithProviders {

return {

ngModule: SharedModule,

providers: [/* Services intended to be singletons */]

};

}

//App Module: app.module.ts to import the module.

@NgModule({

imports: [

BrowserModule,

SharedModule.forRoot(), // Import SharedModule using forRoot()

...

})

export class AppModule { }

"""

### 4.3. Services

* **Do This:**

* Use services for business logic, data access, and shared state.

* Keep services focused on a single responsibility.

* Use dependency injection to provide services to components.

* **Don't Do This:** Directly instantiate services in components.

* **Why:** Services promote separation of concerns and testability.

"""typescript

// Do This

@Injectable({

providedIn: 'root'

})

export class DataService {

constructor(private http: HttpClient) { }

getData(): Observable {

return this.http.get('/api/data');

}

// Don't Do This

@Component({ ... })

export class DataComponent implements OnInit {

dataService: DataService; // Manual instantiation

constructor() {

this.dataService = new DataService(); // Avoid this.

}

"""

### 4.4. Routing

* **Do This:**

* Use lazy loading for feature modules.

* Configure routes in a separate module ("app-routing.module.ts").

* Protect routes with route guards.

* **Don't Do This:** Define all routes in the "AppModule" or neglect route protection.

* **Why:** Lazy loading improves initial load time, and route guards enhance security.

"""typescript

// app-routing.module.ts

const routes: Routes = [

{

path: 'users',

loadChildren: () => import('./user/user.module').then(m => m.UserModule),

canActivate: [AuthGuard]

{

path: 'login',

component: LoginComponent

{

path: '**',

redirectTo: 'users'

}

];

@NgModule({

imports: [RouterModule.forRoot(routes)],

exports: [RouterModule]

})

export class AppRoutingModule { }

"""

## 5. Performance Optimization

Performance is crucial, especially for large Angular applications.

### 5.1. Change Detection

* **Do This:**

* Use "ChangeDetectionStrategy.OnPush" whenever possible.

* Use immutable data structures to trigger change detection efficiently.

* Detach change detectors when necessary.

* **Don't Do This:** Rely on default change detection everywhere without considering performance impacts.

* **Why:** OnPush change detection improves rendering performance significantly.

"""typescript

// OnPush Change Detection

@Component({

selector: 'app-data-display',

templateUrl: './data-display.component.html',

changeDetection: ChangeDetectionStrategy.OnPush

})

export class DataDisplayComponent implements OnChanges{

@Input() data: any;

ngOnChanges(changes: SimpleChanges) {

// Use changes to explicitly manage data updates

}

// Immutable Data Structures

this.data = { ...this.data, newValue: 'new' }; // Create new object instead of directly mutating

"""

### 5.2. Lazy Loading

* **Do This:** Lazy load feature modules to reduce initial bundle size and load time.

* **Don't Do This:** Load all modules eagerly, resulting in a large initial bundle.

* **Why:** Lazy loading improves application startup time.

(See Routing example in section 4.4 for example)

### 5.3. Ahead-of-Time (AOT) Compilation

* **Do This:** Use AOT compilation for production builds.

* **Don't Do This:** Rely on Just-in-Time (JIT) compilation in production.

* **Why:** AOT compilation reduces application size, improves rendering speed, and detects template errors at compile time.

Make sure your "angular.json" has the following to enable default AOT.

"""json

"build": {

"configurations": {

"production": {

"aot": true, //Enabled by default

}

"""

### 5.4. Image Optimization

* **Do This:** Optimize images by compressing them, using appropriate formats (WebP), and lazy loading them

* **Don't Do This:** Use large, unoptimized images that negatively impact page load times.

* **Why:** Image optimization decreases the load on the client and reduces bandwidth costs.

"""html

"""

## 6. Security Best Practices

Security is a critical aspect of Angular development.

### 6.1. Cross-Site Scripting (XSS)

* **Do This:**

* Sanitize user-provided content using the "DomSanitizer" to prevent XSS attacks.

* Avoid using "innerHTML" to inject content directly.

* **Don't Do This:** Trust user-provided content without sanitization.

* **Why:** Prevents malicious scripts from being injected into your application.

"""typescript

import { DomSanitizer, SafeHtml } from '@angular/platform-browser';

@Component({ ... })

export class DisplayComponent {

safeHtml: SafeHtml;

constructor(private sanitizer: DomSanitizer) {

this.safeHtml = this.sanitizer.bypassSecurityTrustHtml('User Input');

}

"""

In the template:

"""html

"""

### 6.2. Cross-Site Request Forgery (CSRF)

* **Do This:**

* Implement CSRF protection by using tokens in your backend and Angular's "HttpClient" to include them in requests (using "HttpInterceptor").

* Set proper CORS policies.

* **Don't Do This:** Neglect CSRF protection, leaving your application vulnerable to unauthorized requests.

* **Why:** Protects users from malicious websites making unauthorized requests on their behalf.

"""typescript

// Interceptor to Add CSRF Token

@Injectable()

export class CSRFInterceptor implements HttpInterceptor {

intercept(req: HttpRequest, next: HttpHandler): Observable> {

const csrfToken = localStorage.getItem('csrfToken');

if (csrfToken) {

const cloned = req.clone({

headers: req.headers.set('X-CSRF-TOKEN', csrfToken)

});

return next.handle(cloned);

}

return next.handle(req);

}

"""

### 6.3. Data Security

* **Do This:**

* Avoid storing sensitive information (e.g., passwords, API keys) in the front-end code.

* Use HTTPS for all API requests.

* **Don't Do This:** Expose sensitive data or use unencrypted communication channels.

* **Why:** Protects sensitive data from unauthorized access.

### 6.4. Dependencies

* **Do This:**

* Regularly audit and update your dependencies to patch known vulnerabilities.

* Use tools like "npm audit" or "yarn audit" to identify and address security issues.

* **Don't Do This:** Use outdated dependencies with known security vulnerabilities.

* **Why:** Reduces risks associated with vulnerable third-party code.

## 7. Error Handling

Appropriate error handling provides a better user experience and makes applications more stable.

### 7.1. Centralized Error Handling

* **Do This:** Implement global error handling using "ErrorHandler".

* **Don't Do This:** Handle errors inconsistently or ignore them.

* **Why:** Provides a consistent way to handle errors across the application.

"""typescript

import { ErrorHandler, Injectable } from '@angular/core';

@Injectable()

export class GlobalErrorHandler implements ErrorHandler {

handleError(error: any) {

console.error('An error occurred:', error.message);

// Report the error to a logging service

}

// Include in app.module.ts providers

@NgModule({

providers: [

{ provide: ErrorHandler, useClass: GlobalErrorHandler }

]

})

export class AppModule {}

"""

### 7.2. Observable Error Handling

* **Do This:** Use RxJS "catchError" operator to handle errors in observables gracefully.

* **Don't Do This:** Let errors propagate without handling, which can crash the application.

* **Why:** RxJS error handling provides a controlled way to handle errors in asynchronous operations.

"""typescript

getData(): Observable {

return this.http.get('/api/data').pipe(

catchError(error => {

console.error('Error fetching data', error);

return throwError('Something went wrong');

})

);

}

"""

## 8. Testing

Comprehensive testing is essential for delivering robust and reliable Angular applications.

### 8.1. Unit Testing

* **Do This:**

* Write unit tests for all components, services, and pipes.

* Use mocks and spies to isolate units under test.

* Aim for high code coverage.

* **Don't Do This:** Skip unit testing or write superficial tests.

* **Why:** Unit tests ensure individual components work as expected.

"""typescript

// Example Unit Test with Jasmine and Karma

import { ComponentFixture, TestBed } from '@angular/core/testing';

import { UserService } from './user.service';

import { of } from 'rxjs';

describe('UserService', () => {

let service: UserService;

let httpClientSpy: { get: jasmine.Spy };

beforeEach(() => {

httpClientSpy = jasmine.createSpyObj('HttpClient', ['get']);

service = new UserService(httpClientSpy as any);

});

it('should return expected users (HttpClient called once)', (done: DoneFn) => {

const expectedUsers: IUser[] = [{ id: 1, name: 'A' }, { id: 2, name: 'B' }];

httpClientSpy.get.and.returnValue(of(expectedUsers));

service.getUsers().subscribe(

users => {

expect(users).toEqual(expectedUsers);

done();

done.fail

);

expect(httpClientSpy.get.calls.count()).toBe(1, 'one call');

});

"""

### 8.2. End-to-End (E2E) Testing

* **Do This:** Use E2E tests to verify the application works correctly from the user's perspective.

* **Don't Do This:** Rely solely on unit tests and neglect E2E testing.

* **Why:** E2E tests ensure the entire application works correctly together.

### 8.3. Integration Testing

* **Do This:** Perform integration tests to verify interactions between modules and services.

* **Don't Do This:** Only focus on individual units without verifying how they integrate.

* **Why:** Integration tests ensure that different parts of the application work together correctly.

By adhering to these coding style and conventions standards, development teams can build Angular applications that are consistent, maintainable, performant, and secure, while leveraging the latest features and best practices of the Angular ecosystem.

Cline

This guide explains how to effectively use .clinerules with Cline, the AI-powered coding assistant.

Overview

The .clinerules file is a powerful configuration file that helps Cline understand your project's requirements, coding standards, and constraints. When placed in your project's root directory, it automatically guides Cline's behavior and ensures consistency across your codebase.

Key Concepts

Purpose of .clinerules

Defines project-specific guidelines and requirements
Enforces consistent coding standards
Establishes documentation practices
Sets testing and quality requirements
Configures error handling preferences

File Location

Place the .clinerules file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.

Rule Structure

1. Project Overview

# Project Overview
project:
  name: 'Your Project Name'
  description: 'Brief project description'
  stack:
    - technology: 'Framework/Language'
      version: 'X.Y.Z'
    - technology: 'Database'
      version: 'X.Y.Z'

2. Code Standards

# Code Standards
standards:
  style:
    - 'Use consistent indentation (2 spaces)'
    - 'Follow language-specific naming conventions'
  documentation:
    - 'Include JSDoc comments for all functions'
    - 'Maintain up-to-date README files'
  testing:
    - 'Write unit tests for all new features'
    - 'Maintain minimum 80% code coverage'

3. Security Rules

# Security Guidelines
security:
  authentication:
    - 'Implement proper token validation'
    - 'Use environment variables for secrets'
  dataProtection:
    - 'Sanitize all user inputs'
    - 'Implement proper error handling'

Best Practices

Writing Effective Rules

Be Specific
- Use clear, actionable language
- Provide examples where helpful
- Define measurable criteria
Maintain Organization
- Group related rules together
- Use consistent formatting
- Keep critical rules at the top
Regular Updates
- Review rules periodically
- Update based on team feedback
- Document changes in version control

Common Patterns

# Common Patterns Example
patterns:
  components:
    - pattern: 'Use functional components by default'
    - pattern: 'Implement error boundaries for component trees'
  stateManagement:
    - pattern: 'Use React Query for server state'
    - pattern: 'Implement proper loading states'

Integration with Development Workflow

Using with Version Control

Commit the Rules
- Include .clinerules in version control
- Document rule changes in commit messages
- Review rule changes as part of PR process
Team Collaboration
- Discuss rule changes with team
- Maintain changelog for rule updates
- Ensure all team members understand rules

Troubleshooting

Common Issues

Rules Not Being Applied
- Verify file location (must be in root directory)
- Check file formatting
- Ensure Cline has access to the file
Conflicting Rules
- Review rule hierarchy
- Resolve conflicts explicitly
- Document rule precedence
Performance Considerations
- Keep rules concise and focused
- Avoid overly complex rule structures
- Regular cleanup of obsolete rules

Examples

Basic Project Setup

# Basic .clinerules Example
project:
  name: 'Web Application'
  type: 'Next.js Frontend'
  standards:
    - 'Use TypeScript for all new code'
    - 'Follow React best practices'
    - 'Implement proper error handling'

testing:
  unit:
    - 'Jest for unit tests'
    - 'React Testing Library for components'
  e2e:
    - 'Cypress for end-to-end testing'

documentation:
  required:
    - 'README.md in each major directory'
    - 'JSDoc comments for public APIs'
    - 'Changelog updates for all changes'

Advanced Configuration

# Advanced .clinerules Example
project:
  name: 'Enterprise Application'
  compliance:
    - 'GDPR requirements'
    - 'WCAG 2.1 AA accessibility'

architecture:
  patterns:
    - 'Clean Architecture principles'
    - 'Domain-Driven Design concepts'

security:
  requirements:
    - 'OAuth 2.0 authentication'
    - 'Rate limiting on all APIs'
    - 'Input validation with Zod'

Code Style and Conventions Standards for Angular

Cline

Overview

Key Concepts

Purpose of .clinerules

File Location

Rule Structure

1. Project Overview

2. Code Standards

3. Security Rules

Best Practices

Writing Effective Rules

Common Patterns

Integration with Development Workflow

Using with Version Control

Troubleshooting

Common Issues

Examples

Basic Project Setup

Advanced Configuration

Related Rules

Angular v19+ Development Standards and Best Practices: A Comprehensive Guide

NgRx Signal Store Best Practices

NgRx Signals Testing Guidelines

Angular Material Theming Guidelines (v3)

Angular Testing Guidelines (Jasmine + ng-mocks)