# Component Design Standards for Angular

This document outlines coding standards specifically for **Component Design** in Angular applications. Following these guidelines will contribute to creating reusable, maintainable, and performant Angular components. These standards are based on the latest version of Angular and incorporate modern best practices.

## 1. Component Structure and Organization

### 1.1. Component Directory Structure

**Do This:** Organize components into feature-specific directories. Each component directory should contain the component's TypeScript file, HTML template, CSS/SCSS stylesheet, and any related test files.

**Why:** Clear directory structure improves code discoverability and maintainability, especially in large projects.

"""

src/app/

├── feature-module/

│ ├── component-a/

│ │ ├── component-a.component.ts

│ │ ├── component-a.component.html

│ │ ├── component-a.component.scss

│ │ └── component-a.component.spec.ts

│ ├── component-b/

│ │ ├── component-b.component.ts

│ │ ├── component-b.component.html

│ │ ├── component-b.component.scss

│ │ └── component-b.component.spec.ts

│ └── feature-module.module.ts

"""

**Don't Do This:** Place all components in a single, flat directory. This makes it difficult to find and manage components as the application grows.

### 1.2. Component Selector Naming

**Do This:** Use a consistent naming convention for component selectors, preferably prefixed with a short application or module identifier. Use kebab-case.

**Why:** Consistent naming prevents naming conflicts and makes it easy to identify which component belongs to which part of the application.

"""typescript

// Good: application-name-component-name

@Component({

selector: 'app-product-list',

templateUrl: './product-list.component.html',

styleUrls: ['./product-list.component.scss']

})

export class ProductListComponent { }

"""

**Don't Do This:** Use generic or inconsistent names, or names that are too long and verbose.

### 1.3. Component Logic Separation

**Do This:** Separate component logic into distinct concerns. Use services for data access, business logic, and shared functionality. Components should primarily handle view-related tasks.

**Why:** Separation of concerns makes components more testable, reusable, and easier to understand. Single Responsibility Principle.

"""typescript

// Good: Component delegates data loading to a service

import { Component, OnInit } from '@angular/core';

import { ProductService } from '../product.service';

import { Product } from '../product.model';

@Component({

selector: 'app-product-list',

templateUrl: './product-list.component.html',

styleUrls: ['./product-list.component.scss']

})

export class ProductListComponent implements OnInit {

products: Product[] = [];

constructor(private productService: ProductService) { }

ngOnInit(): void {

this.productService.getProducts().subscribe(products => this.products = products);

}

"""

**Don't Do This:** Place data access logic or complex business rules directly within the component.

### 1.4. Smart vs. Dumb Components (Presentational vs. Container Components)

**Do This:** Differentiate between "smart" (container) components and "dumb" (presentational) components. Smart components handle data fetching and state management, while dumb components focus on rendering data and emitting events.

**Why:** This pattern promotes reusability and testability. Presentational components become reusable building blocks.

"""typescript

// Dumb/Presentational Component - receives data via @Input, emits events @Output

import { Component, Input, Output, EventEmitter } from '@angular/core';

import { Product } from '../product.model';

@Component({

selector: 'app-product-card',

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

styleUrls: ['./product-card.component.scss']

})

export class ProductCardComponent {

@Input() product!: Product;

@Output() addToCart = new EventEmitter();

onAddToCart() {

this.addToCart.emit(this.product);

}

// Smart/Container Component - Fetches data, manages the product list, and uses the ProductCardComponent

import { Component, OnInit } from '@angular/core';

import { ProductService } from '../product.service';

import { Product } from '../product.model';

@Component({

selector: 'app-product-list',

templateUrl: './product-list.component.html',

styleUrls: ['./product-list.component.scss']

})

export class ProductListComponent implements OnInit {

products: Product[] = [];

constructor(private productService: ProductService) { }

ngOnInit(): void {

this.productService.getProducts().subscribe(products => this.products = products);

}

onAddToCart(product: Product) {

// Logic to add product to cart (e.g., using a cart service)

console.log("Adding ${product.name} to cart");

}

"""

**Don't Do This:** Create components that are responsible for both data fetching and rendering, making them tightly coupled and difficult to reuse.

## 2. Component Inputs and Outputs

### 2.1. Use of "@Input()" and "@Output()" Decorators

**Do This:** Clearly define component inputs using the "@Input()" decorator and outputs using the "@Output()" decorator. Use strong typing for input and output properties.

**Why:** Explicitly defining inputs and outputs improves code clarity, prevents unexpected behavior, and enables better tooling support.

"""typescript

// Good

import { Component, Input, Output, EventEmitter } from '@angular/core';

@Component({

selector: 'app-my-component',

{{ myInput }}

Click me

})

export class MyComponent {

@Input() myInput!: string; // Non-null assertion operator. Ensure you are providing a value.

@Output() myOutput = new EventEmitter();

}

"""

**Don't Do This:** Rely on implicit input properties or use string-based event names.

### 2.2. Input Property Transformations

**Do This:** If input properties require transformation, perform the transformation within the component using a setter or the "ngOnChanges" lifecycle hook.

**Why:** Keeping transformation logic within the component ensures data consistency and prevents unexpected behavior.

"""typescript

// Good: Using a setter to transform input

import { Component, Input } from '@angular/core';

@Component({

selector: 'app-display-name',

})

export class DisplayNameComponent {

private _name: string = '';

formattedName: string = '';

@Input()

set name(name: string) {

this._name = name;

this.formattedName = this._formatName(name);

}

get name(): string { return this._name; }

private _formatName(name: string): string {

return name.toUpperCase(); // Example formatting

}

"""

**Don't Do This:** Modify input properties directly without considering potential side effects or data binding issues.

### 2.3. Output Event Payload Typing

**Do This:** Always type the payload of output events. This adds type safety, making it easier to handle the event data in the parent component.

**Why:** Provides compile-time error checking and clarifies the structure of the emitted data.

"""typescript

import { Component, Output, EventEmitter } from '@angular/core';

interface Task {

id: number;

description: string;

completed: boolean;

}

@Component({

selector: 'app-task-item',

})

export class TaskItemComponent {

task: Task = { id: 1, description: 'Example Task', completed: false}; // Dummy task for demonstration

@Output() completeTask = new EventEmitter();

}

"""

**Don't Do This:** Emit events without a specified payload type, potentially leading to type errors and runtime issues.

## 3. Component Templates (HTML)

### 3.1. Template Readability

**Do This:** Format HTML templates consistently for readability. Use proper indentation, line breaks, and comments to explain complex logic. Keep templates concise and focused on presentation. Delegate heavy logic to the component class.

**Why:** Readable templates are easier to understand and maintain.

"""html

{{ product.description }}

Add to Cart

"""

**Don't Do This:** Write excessively long or complex templates with minimal formatting.

### 3.2. Avoiding Logic in Templates

**Do This:** Minimize complex logic within templates. Use template variables, pipe transformations, and method calls in the component class rather than complex expressions in the template.

**Why:** Simplifies templates, improving readability and testability.

"""typescript

// Good: Moving formatting logic to the component

import { Component } from '@angular/core';

@Component({

selector: 'app-date-display',

})

export class DateDisplayComponent {

today = new Date();

formattedDate = this.formatDate(this.today);

formatDate(date: Date): string {

return date.toLocaleDateString(); //Formatting is handled in the component

}

//Bad: overly complex logic inside of a template.

//{{ today.toLocaleDateString() }} // Date formatting directly in template

"""

**Don't Do This:** Perform heavy calculations, data manipulations, or complex conditional logic directly within the template.

### 3.3. Security: Preventing Cross-Site Scripting (XSS)

**Do This:** Sanitize any dynamically generated content before rendering it in the template. Use Angular's built-in "DomSanitizer" to prevent XSS attacks.

**Why:** Essential for preventing malicious code injection into your application through user-provided data.

"""typescript

import { Component, SecurityContext } from '@angular/core';

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

@Component({

selector: 'app-safe-content',

})

export class SafeContentComponent {

unsafeHtml = '';

safeHtml: SafeHtml;

constructor(private sanitizer: DomSanitizer) {

//Sanitize on initialization.

this.safeHtml = this.sanitizer.sanitize(SecurityContext.HTML, this.unsafeHtml) || '';

}

"""

**Don't Do This:** Directly render user-provided content without sanitization. This presents a severe security risk. Avoid bypassing sanitization unless absolutely necessary and with extreme caution and justification.

### 3.4. Using "trackBy" with "*ngFor"

**Do This:** Use the "trackBy" function with "*ngFor" to improve rendering performance for dynamic lists, especially when dealing with large datasets. "trackBy" allows Angular to only re-render items that have changed, rather than the entire list.

**Why:** Reduces DOM manipulations and significantly improves rendering performance in dynamic lists.

"""typescript

// Good

import { Component } from '@angular/core';

interface Item {

id: number;

}

@Component({

selector: 'app-list-display',

})

export class ListDisplayComponent {

items: Item[] = [{ id: 1, name: 'Item 1' }, { id: 2, name: 'Item 2' }];

trackById(index: number, item: Item): number {

return item.id;

}

"""

**Don't Do This:** Skip "trackBy" when rendering large or frequently updated lists.

## 4. Component Styles (CSS/SCSS)

### 4.1. Component-Specific Styles

**Do This:** Scope styles to components using component-specific CSS/SCSS files. Use the "encapsulation: ViewEncapsulation.Emulated" (default) or "encapsulation: ViewEncapsulation.ShadowDom" view encapsulation strategies to prevent style bleed.

**Why:** Prevents styling conflicts and ensures that component styles are isolated.

"""typescript

// Good

import { Component, ViewEncapsulation } from '@angular/core';

@Component({

selector: 'app-styled-component',

templateUrl: './styled-component.component.html',

styleUrls: ['./styled-component.component.scss'],

encapsulation: ViewEncapsulation.Emulated // Or ShadowDom

})

export class StyledComponent { }

"""

**Don't Do This:** Rely on global styles for component-specific styling unless absolutely necessary. Avoid "ViewEncapsulation.None" unless you have a very specific reason and understand the implications.

### 4.2. CSS/SCSS Naming Conventions

**Do This:** Use a consistent naming convention for CSS classes and selectors. BEM (Block Element Modifier) is a popular and effective choice.

**Why:** Consistent naming improves code readability and prevents CSS conflicts.

"""scss

/* Good: Using BEM */

.product-card { /* Block */

&__image { /* Element */

width: 100%;

}

&__title { /* Element */

font-size: 1.2em;

}

&--featured { /* Modifier */

border: 2px solid blue;

}

"""

**Don't Do This:** Use unclear, generic, or inconsistent class names.

### 4.3. Stylelint

**Do This:** Integrate Stylelint into your build process to enforce CSS/SCSS coding standards.

**Why:** Stylelint automates the process of enforcing coding standards, ensuring consistent styling across the application.

"""json

// Example Stylelint configuration (.stylelintrc.json)

{

"extends": "stylelint-config-standard",

"rules": {

"indentation": 2, // Enforce 2-space indentation

"selector-class-pattern": "^[a-z][a-zA-Z0-9]+$", // Example: enforce lowerCamelCase

"no-duplicate-selectors": true

}

"""

**Don't Do This:** Ignore CSS/SCSS coding standards or rely solely on manual code reviews.

## 5. Component Lifecycle Hooks

### 5.1. Understanding Lifecycle Hooks

**Do This:** Understand the purpose and execution order of Angular lifecycle hooks. Use them appropriately for tasks like initialization, data binding, and cleanup.

**Why:** Correct use of lifecycle hooks ensures proper component behavior and prevents memory leaks.

"""typescript

import { Component, OnInit, OnDestroy, OnChanges , Input, SimpleChanges} from '@angular/core';

import { Subscription } from 'rxjs';

@Component({

selector: 'app-lifecycle-example',

})

export class LifecycleExampleComponent implements OnInit, OnDestroy, OnChanges {

@Input() inputValue!: string; //Non-null assertion operator

value: string = '';

private subscription!: Subscription; //Non-null assertion operator

constructor() {

console.log('Constructor called');

}

ngOnChanges(changes: SimpleChanges): void {

console.log('ngOnChanges called', changes);

if (changes['inputValue']) {

this.value = changes['inputValue'].currentValue;

}

ngOnInit(): void {

console.log('ngOnInit called');

// Example: Subscribing to an observable

// this.subscription = this.myService.getData().subscribe(data => {

// this.value = data;

// });

}

ngOnDestroy(): void {

console.log('ngOnDestroy called');

//Unsubscribe to prevent memory leaks

if (this.subscription) {

this.subscription.unsubscribe();

}

"""

**Don't Do This:** Perform heavy operations in every lifecycle hook. Avoid using "ngOnDestroy" to unsubscribe from subscriptions or clean up resources.

### 5.2. Unsubscribing from Observables

**Do This:** Always unsubscribe from observables in the "ngOnDestroy" lifecycle hook to prevent memory leaks, especially when dealing with long-lived subscriptions. Use the "takeUntil" operator to automatically unsubscribe when the component is destroyed.

**Why:** Failure to unsubscribe can lead to memory leaks and performance degradation.

"""typescript

import { interval, Subject } from 'rxjs';

import { takeUntil } from 'rxjs/operators';

import { Component, OnInit, OnDestroy } from '@angular/core';

@Component({

selector: 'app-unsubscribe-example',

})

export class UnsubscribeExampleComponent implements OnInit, OnDestroy {

value: number = 0;

private destroy$ = new Subject();

ngOnInit() {

interval(1000)

.pipe(takeUntil(this.destroy$))

.subscribe(val => this.value = val);

}

ngOnDestroy() {

this.destroy$.next();

this.destroy$.complete();

}

"""

**Don't Do This:** Forget to unsubscribe from observables, particularly inside services or components that persist for a long time.

## 6. Component Testing

### 6.1. Unit Testing

**Do This:** Write unit tests for each component to verify its behavior in isolation. Test input/output bindings, template rendering, and event handling.

**Why:** Unit tests ensure that components function correctly and prevent regressions.

"""typescript

// Good: Example Jasmine/Karma test

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

import { MyComponent } from './my.component';

describe('MyComponent', () => {

let component: MyComponent;

let fixture: ComponentFixture;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [ MyComponent ]

})

.compileComponents();

});

beforeEach(() => {

fixture = TestBed.createComponent(MyComponent);

component = fixture.componentInstance;

fixture.detectChanges();

});

it('should create', () => {

expect(component).toBeTruthy();

});

it('should display the input value', () => {

component.myInput = 'Test Input';

fixture.detectChanges();

const compiled = fixture.nativeElement;

expect(compiled.querySelector('p').textContent).toContain('Test Input');

});

"""

**Don't Do This:** Skip unit testing for components, especially those with complex logic or user interactions.

### 6.2 Mocking Dependencies

**Do This:** Mock dependencies (e.g., services) when testing components to isolate the component under test.

**Why:** Mocking ensures that tests are fast, deterministic, and focused on the component's behavior, not the behavior of its dependencies.

"""typescript

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

import { ProductListComponent } from './product-list.component';

import { ProductService } from '../product.service';

import { of } from 'rxjs';

describe('ProductListComponent', () => {

let component: ProductListComponent;

let fixture: ComponentFixture;

let productServiceSpy: jasmine.SpyObj;

beforeEach(async () => {

const spy = jasmine.createSpyObj('ProductService', ['getProducts']);

await TestBed.configureTestingModule({

declarations: [ProductListComponent],

providers: [{ provide: ProductService, useValue: spy }]

}).compileComponents();

productServiceSpy = TestBed.inject(ProductService) as jasmine.SpyObj;

});

beforeEach(() => {

fixture = TestBed.createComponent(ProductListComponent);

component = fixture.componentInstance;

// Mock the getProducts method

productServiceSpy.getProducts.and.returnValue(of([{ id: 1, name: 'Test Product', description: 'Test'}]));

fixture.detectChanges();

});

it('should display products', () => {

expect(component.products.length).toBe(1);

});

"""

**Don't Do This:** Rely on real backend services or databases in unit tests.

## 7. Component Versioning and Deprecation

### 7.1. Semantic Versioning

**Do This:** Use Semantic Versioning (SemVer) for your component library. Follow SemVer guidelines for major, minor, and patch releases.

**Why:** Provides clarity for consumers of your component library about the impact of updates.

### 7.2. Deprecation

**Do This:** When deprecating a component or feature, clearly communicate the deprecation and provide a migration path. Use "@deprecated" JSDoc tag.

**Why:** Helps users to transition smoothly to new versions of your component library.

"""typescript

/**

* @deprecated Use NewComponent instead.

@Component({

selector: 'app-deprecated-component',

})

export class DeprecatedComponent { }

"""

**Don't Do This:** Remove or change features without providing deprecation warnings or migration instructions which can lead to breaking changes.

This document provides a comprehensive guide to Angular component design best practices. Consistently applying these standards will result in more robust, maintainable, and performant Angular applications. These standards should be updated and refined as the Angular ecosystem evolves.

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'

Component Design 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)