# Storybook Guidelines for Angular (v9.0.18+)
Use these guidelines when working with Storybook in Angular projects. This document covers modern patterns, best practices, and the latest features in Storybook 9.x.
## 1. Core Architecture & Setup
### Framework Configuration
- **Angular Framework**: Always use `@storybook/angular` as the framework in your `.storybook/main.ts`
- **TypeScript First**: All configuration files should use TypeScript (`.ts` extension)
- **Standalone Components**: Leverage Angular standalone components in stories - they work seamlessly with Storybook
- **Modern Angular Patterns**: Support for Angular 17+ features including signals, control flow, and standalone APIs
### Basic Configuration Structure
```typescript
// .storybook/main.ts
import type { StorybookConfig } from '@storybook/angular';
const config: StorybookConfig = {
framework: {
name: '@storybook/angular',
options: {
// Framework-specific options
},
},
stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
addons: [
'@storybook/addon-essentials',
'@storybook/addon-interactions',
'@storybook/addon-a11y',
'@storybook/addon-docs',
'@storybook/addon-vitest', // For Storybook 9.x testing
],
};
export default config;
```
## 2. Story Structure & CSF 3 Patterns
### Modern Story Format (CSF 3)
- **Component Story Format 3**: Use the latest CSF 3 syntax for all new stories
- **TypeScript Types**: Always use `Meta` and `StoryObj` for type safety
- **Minimal Boilerplate**: Leverage CSF 3's simplified syntax
```typescript
import type { Meta, StoryObj } from '@storybook/angular';
import { Button } from './button.component';
const meta: Meta = {
component: Button,
};
export default meta;
type Story = StoryObj;
export const Primary: Story = {
args: {
primary: true,
label: 'Button',
},
};
export const Secondary: Story = {
args: {
primary: false,
label: 'Button',
},
};
```
### Story Naming & Organization
- **Descriptive Names**: Use clear, descriptive names for story exports
- **Hierarchical Titles**: Organize stories with meaningful hierarchies using forward slashes
- **Auto-Generated Titles**: Leverage automatic title generation when possible
- **Component-Centric**: Group stories by component, not by state
```typescript
const meta: Meta = {
title: 'Design System/Components/Button', // Hierarchical organization
component: Button,
};
```
## 3. Angular-Specific Patterns
### Standalone Components (Recommended)
- **Default Approach**: Prefer standalone components for new development
- **No Module Imports**: Avoid importing CommonModule or other NgModules
- **Direct Dependencies**: Import only required standalone components, directives, or pipes
```typescript
// ✅ Good - Standalone component story
import type { Meta, StoryObj } from '@storybook/angular';
import { MyStandaloneComponent } from './my-standalone.component';
const meta: Meta = {
component: MyStandaloneComponent,
};
```
### Legacy Module-Based Components
- **Module Metadata**: Use `moduleMetadata` decorator for components requiring NgModules
- **Minimal Imports**: Import only necessary modules and declarations
```typescript
// For legacy components requiring modules
import { moduleMetadata } from '@storybook/angular';
import { CommonModule } from '@angular/common';
const meta: Meta = {
component: LegacyComponent,
decorators: [
moduleMetadata({
imports: [CommonModule],
declarations: [LegacyComponent, ChildComponent],
}),
],
};
```
### Application Configuration
- **Provider Setup**: Use `applicationConfig` decorator for dependency injection
- **Service Mocking**: Configure providers for testing scenarios
```typescript
import { applicationConfig } from '@storybook/angular';
import { importProvidersFrom } from '@angular/core';
import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
const meta: Meta = {
component: MyComponent,
decorators: [
applicationConfig({
providers: [
importProvidersFrom(BrowserAnimationsModule),
// Add other providers as needed
],
}),
],
};
```
## 4. Story Configuration & Best Practices
### Args and Controls
- **Typed Args**: Leverage TypeScript for type-safe arguments
- **Meaningful Defaults**: Provide sensible default values
- **Control Types**: Explicitly define control types when needed
```typescript
const meta: Meta = {
component: Button,
argTypes: {
size: {
control: { type: 'select' },
options: ['small', 'medium', 'large'],
},
disabled: {
control: { type: 'boolean' },
},
},
args: {
// Default args for all stories
size: 'medium',
disabled: false,
label: 'Button',
},
};
```
### Parameters Configuration
- **Global Parameters**: Set common parameters at the meta level
- **Story-Specific Overrides**: Override parameters for specific stories when needed
- **Documentation**: Use parameters for docs configuration
```typescript
const meta: Meta = {
component: Button,
parameters: {
docs: {
description: {
component: 'A versatile button component for user interactions.',
},
},
backgrounds: {
default: 'light',
},
},
};
export const OnDark: Story = {
parameters: {
backgrounds: { default: 'dark' },
},
};
```
## 5. Advanced Patterns
### Custom Render Functions
- **Complex Templates**: Use render functions for complex component templates
- **Template Customization**: Provide custom templates when component alone isn't sufficient
```typescript
export const WithCustomTemplate: Story = {
render: args => ({
props: args,
template: `
<p>Additional content around the button</p>
`,
}),
};
```
### Component Composition
- **Multi-Component Stories**: Show components working together
- **Real-World Scenarios**: Create stories that demonstrate actual usage patterns
```typescript
const meta: Meta = {
component: List,
decorators: [
moduleMetadata({
declarations: [List, ListItem],
}),
],
};
export const WithItems: Story = {
render: args => ({
props: args,
template: `
Item 1
Item 2
Item 3
`,
}),
};
```
## 6. Testing Integration (Storybook 9.x)
### Vitest Addon Integration
- **Modern Testing**: Use `@storybook/addon-vitest` for component testing
- **Story-Based Tests**: Transform stories into tests automatically
- **Browser Mode**: Leverage Vitest's browser mode for realistic testing
```bash
# Install and configure Vitest addon
npx storybook@latest add @storybook/addon-vitest
```
### Interaction Testing
- **Play Functions**: Use play functions for interaction testing
- **User Events**: Simulate real user interactions
- **Assertions**: Include meaningful assertions in play functions
```typescript
import { userEvent, within, expect } from '@storybook/test';
export const InteractiveTest: Story = {
args: {
label: 'Click me',
},
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
const button = canvas.getByRole('button');
await userEvent.click(button);
await expect(button).toHaveClass('clicked');
},
};
```
### Accessibility Testing
- **A11y Addon**: Include `@storybook/addon-a11y` for accessibility checks
- **ARIA Labels**: Ensure proper ARIA labeling in stories
- **Keyboard Navigation**: Test keyboard accessibility
```typescript
const meta: Meta = {
component: Button,
parameters: {
a11y: {
config: {
rules: [
{
id: 'color-contrast',
enabled: true,
},
],
},
},
},
};
```
## 7. Documentation & Docs Integration
### Compodoc Integration
- **API Documentation**: Integrate Compodoc for automatic API docs generation
- **Angular.json Configuration**: Configure builders for Compodoc integration
```json
// angular.json
{
"projects": {
"your-project": {
"architect": {
"storybook": {
"builder": "@storybook/angular:start-storybook",
"options": {
"compodoc": true,
"compodocArgs": ["-e", "json", "-d", "."]
}
}
}
}
}
}
```
```typescript
// .storybook/preview.ts
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';
setCompodocJson(docJson);
```
### Story Documentation
- **JSDoc Comments**: Use JSDoc comments for automatic documentation
- **Description Parameters**: Override descriptions when needed
- **Code Examples**: Include relevant code examples
```typescript
/**
* Primary button component for user actions.
* Supports various sizes and states.
*/
const meta: Meta = {
component: Button,
parameters: {
docs: {
description: {
component: 'The primary button component with full accessibility support.',
},
},
},
};
/**
* The primary button state - used for main actions
*/
export const Primary: Story = {
parameters: {
docs: {
description: {
story: 'Use this variant for primary actions like "Save" or "Submit".',
},
},
},
};
```
## 8. Performance & Optimization
### Lazy Loading
- **Code Splitting**: Leverage Angular's lazy loading for large component libraries
- **Story Optimization**: Keep stories focused and lightweight
- **Asset Management**: Optimize images and other assets
### Bundle Optimization
- **Tree Shaking**: Ensure proper tree shaking of unused code
- **Minimal Dependencies**: Import only necessary dependencies
- **Build Configuration**: Optimize build configuration for production
## 9. Theming & Styling
### Angular Material Integration
- **Theme Providers**: Use decorators to provide Angular Material themes
- **Component Wrapper**: Wrap stories with theme providers when needed
```typescript
import { componentWrapperDecorator } from '@storybook/angular';
const meta: Meta = {
component: MyComponent,
decorators: [componentWrapperDecorator(story => `${story}`)],
};
```
### CSS Custom Properties
- **Design Tokens**: Use CSS custom properties for consistent theming
- **Theme Switching**: Implement theme switching in stories
- **Responsive Design**: Test components across different viewports
## 10. File Organization & Naming
### File Structure
- **Co-location**: Keep stories close to their components
- **Consistent Naming**: Use consistent naming patterns
- **Logical Grouping**: Group related stories together
```
src/
components/
button/
button.component.ts
button.component.html
button.component.scss
button.component.stories.ts
button.component.spec.ts
```
### Naming Conventions
- **Story Files**: Use `.stories.ts` extension
- **Export Names**: Use PascalCase for story exports
- **File Names**: Use kebab-case for file names
## 11. CI/CD Integration
### Build Configuration
- **Static Builds**: Configure static build for deployment
- **Environment Variables**: Handle environment-specific configuration
- **Testing Pipeline**: Integrate story testing in CI/CD
```bash
# Build Storybook for production
ng run your-project:build-storybook
# Run tests with Vitest addon
npm run test-storybook
```
### Deployment
- **Static Hosting**: Deploy to static hosting services
- **Version Management**: Tag releases with version numbers
- **Documentation Updates**: Keep documentation in sync with code
## 12. Migration & Maintenance
### Upgrading Storybook
- **Regular Updates**: Keep Storybook updated to latest versions
- **Migration Guides**: Follow official migration guides
- **Breaking Changes**: Test thoroughly after major updates
### Legacy Code Migration
- **Gradual Migration**: Migrate stories incrementally
- **CSF 2 to CSF 3**: Upgrade older story formats
- **Module to Standalone**: Migrate to standalone components when possible
## 13. Common Patterns & Examples
### Form Components
```typescript
export const FormExample: Story = {
render: args => ({
props: args,
template: `
`,
}),
};
```
### Data Loading States
```typescript
export const Loading: Story = {
args: {
loading: true,
data: null,
},
};
export const WithData: Story = {
args: {
loading: false,
data: mockData,
},
};
export const Error: Story = {
args: {
loading: false,
error: 'Failed to load data',
},
};
```
### Responsive Components
```typescript
export const Mobile: Story = {
parameters: {
viewport: {
defaultViewport: 'mobile1',
},
},
};
export const Desktop: Story = {
parameters: {
viewport: {
defaultViewport: 'desktop',
},
},
};
```
## 14. Quality Guidelines
### Code Quality
- **TypeScript Strict Mode**: Use strict TypeScript configuration
- **ESLint Rules**: Follow Storybook-specific ESLint rules
- **Consistent Formatting**: Use Prettier for code formatting
### Testing Standards
- **Coverage Goals**: Aim for high story coverage of component states
- **Interaction Tests**: Include interaction tests for complex components
- **Accessibility Tests**: Ensure all stories pass accessibility checks
### Documentation Standards
- **Complete Coverage**: Document all component props and behaviors
- **Real Examples**: Provide realistic usage examples
- **Up-to-date**: Keep documentation synchronized with code changes
## 15. Troubleshooting & Common Issues
### Angular-Specific Issues
- **Module Dependencies**: Ensure all required modules are imported
- **Provider Configuration**: Check provider setup for dependency injection
- **Change Detection**: Consider OnPush change detection strategy
### Performance Issues
- **Bundle Size**: Monitor and optimize bundle size
- **Memory Leaks**: Watch for memory leaks in complex stories
- **Build Time**: Optimize build configuration for faster development
This comprehensive guide ensures you're following the latest best practices for Storybook 9.x with Angular, leveraging modern features like the Vitest addon, improved testing capabilities, and optimized development workflows.
saschaleh92
Created Jul 29, 2025
This guide explains how to effectively use .clinerules
with Cline, the AI-powered coding assistant.
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.
Place the .clinerules
file in your project's root directory. Cline automatically detects and follows these rules for all files within the project.
# 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'
# 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'
# Security Guidelines security: authentication: - 'Implement proper token validation' - 'Use environment variables for secrets' dataProtection: - 'Sanitize all user inputs' - 'Implement proper error handling'
Be Specific
Maintain Organization
Regular Updates
# 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'
Commit the Rules
.clinerules
in version controlTeam Collaboration
Rules Not Being Applied
Conflicting Rules
Performance Considerations
# 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 .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'
# Angular Guidelines Use this guidelines when working with Angular related code. ## 1. Core Architecture - **Standalone Components:** Components, directives, and pipes are standalone by default. The `standalone: true` flag is no longer required and should be omitted in new code (Angular v17+ and above). - **Strong Typing:** TypeScript types, interfaces, and models provide type safety throughout the codebase - **Single Responsibility:** Each component and service has a single, well-defined responsibility - **Rule of One:** Files focus on a single concept or functionality - **Reactive State:** Signals provide reactive and efficient state management - **Dependency Injection:** Angular's DI system manages service instances - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` - **Lazy Loading:** Deferrable Views and route-level lazy loading with `loadComponent` improve performance - **Directive Composition:** The Directive Composition API enables reusable component behavior - **Standalone APIs Only:** Do not use NgModules, CommonModule, or RouterModule. Import only required standalone features/components. - **No Legacy Modules:** Do not use or generate NgModules for new features. Migrate existing modules to standalone APIs when possible. ## 2. Angular Style Guide Patterns - **Code Size:** Files are limited to 400 lines of code - **Single Purpose Files:** Each file defines one entity (component, service, etc.) - **Naming Conventions:** Symbols have consistent, descriptive names - **Folder Structure:** Code is organized by feature-based folders - **File Separation:** Templates and styles exist in their own files for components - **Property Decoration:** Input and output properties have proper decoration - **Component Selectors:** Component selectors use custom prefixes and kebab-case (e.g., `app-feature-name`) - **No CommonModule or RouterModule Imports:** Do not import CommonModule or RouterModule in standalone components. Import only the required standalone components, directives, or pipes. ## 3. Input Signal Patterns - **Signal-Based Inputs:** The `input()` function creates InputSignals: ```typescript // Current pattern readonly value = input(0); // Creates InputSignal // Legacy pattern @Input() value = 0; ``` - **Required Inputs:** The `input.required()` function marks inputs as mandatory: ```typescript readonly value = input.required<number>(); ``` - **Input Transformations:** Transformations convert input values: ```typescript readonly disabled = input(false, { transform: booleanAttribute }); readonly value = input(0, { transform: numberAttribute }); ``` - **Two-Way Binding:** Model inputs enable two-way binding: ```typescript readonly value = model(0); // Creates a model input with change propagation // Model values update with .set() or .update() increment(): void { this.value.update(v => v + 1); } ``` - **Input Aliases:** Aliases provide alternative input names: ```typescript readonly value = input(0, { alias: "sliderValue" }); ``` ## 3a. Typed Reactive Forms - **Typed Forms:** Always use strictly typed reactive forms by defining an interface for the form values and using `FormGroup<MyFormType>`, `FormBuilder.group<MyFormType>()`, and `FormControl<T>()`. - **Non-Nullable Controls:** Prefer `nonNullable: true` for controls to avoid null issues and improve type safety. - **Patch and Get Values:** Use `patchValue` and `getRawValue()` to work with typed form values. - **Reference:** See the [Angular Typed Forms documentation](https://angular.dev/guide/forms/typed-forms) for details and examples. ## 4. Component Patterns - **Naming Pattern:** Components follow consistent naming - `feature.type.ts` (e.g., `hero-list.component.ts`) - **Template Extraction:** Non-trivial templates exist in separate `.html` files - **Style Extraction:** Styles exist in separate `.css/.scss` files - **Signal-Based Inputs:** Components use the `input()` function for inputs - **Two-Way Binding:** Components use the `model()` function for two-way binding - **Lifecycle Hooks:** Components implement appropriate lifecycle hook interfaces (OnInit, OnDestroy, etc.) - **Element Selectors:** Components use element selectors (`selector: 'app-hero-detail'`) - **Logic Delegation:** Services contain complex logic - **Input Initialization:** Inputs have default values or are marked as required - **Lazy Loading:** The `@defer` directive loads heavy components or features - **Error Handling:** Try-catch blocks handle errors - **Modern Control Flow:** Templates use `@if`, `@for`, `@switch` instead of structural directives - **State Representation:** Components implement loading and error states - **Derived State:** The `computed()` function calculates derived state - **No NgModules:** Do not use or reference NgModules in new code. ## 5. Styling Patterns - **Component Encapsulation:** Components use scoped styles with proper encapsulation - **CSS Methodology:** BEM methodology guides CSS class naming when not using Angular Material - **Component Libraries:** Angular Material or other component libraries provide consistent UI elements - **Theming:** Color systems and theming enable consistent visual design - **Accessibility:** Components follow a11y standards - **Dark Mode:** Components support dark mode where appropriate ## 5a. Angular Material and Angular CDK Usage - **Standard UI Library:** Use Angular Material v3 for all standard UI components (buttons, forms, navigation, dialogs, etc.) to ensure consistency, accessibility, and alignment with Angular best practices. - **Component Development:** Build new UI components and features using Angular Material components as the foundation. Only create custom components when Material does not provide a suitable solution. - **Behavioral Primitives:** Use Angular CDK for advanced behaviors (drag-and-drop, overlays, accessibility, virtual scrolling, etc.) and for building custom components that require low-level primitives. - **Theming:** Leverage Angular Material's theming system for consistent color schemes, dark mode support, and branding. Define and use custom themes in `styles.scss` or feature-level styles as needed. - **Accessibility:** All UI components must meet accessibility (a11y) standards. Prefer Material components for built-in a11y support. When using CDK or custom components, follow WCAG and ARIA guidelines. - **Best Practices:** - Prefer Material's layout and typography utilities for spacing and text. - Use Material icons and fonts for visual consistency. - Avoid mixing multiple UI libraries in the same project. - Reference the [Angular Material documentation](https://material.angular.io) for usage patterns and updates. - **CDK Utilities:** Use Angular CDK utilities for custom behaviors, overlays, accessibility, and testing harnesses. - **Migration:** For legacy or custom components, migrate to Angular Material/CDK where feasible. ## 5b. Template Patterns - **Modern Control Flow:** Use the new Angular control flow syntax: `@if`, `@for`, `@switch` in templates. Do not use legacy structural directives such as `*ngIf`, `*ngFor`, or `*ngSwitch`. - **No Legacy Structural Directives:** Remove or migrate any usage of `*ngIf`, `*ngFor`, or `*ngSwitch` to the new control flow syntax in all new code. Legacy code should be migrated when touched. - **Referencing Conditional Results:** When using `@if`, reference the result using the `as` keyword, e.g. `@if (user(); as u) { ... }`. This is the recommended pattern for accessing the value inside the block. See the [Angular documentation](https://angular.dev/guide/templates/control-flow#referencing-the-conditional-expressions-result) for details. ## 6. Service and DI Patterns - **Service Declaration:** Services use the `@Injectable()` decorator with `providedIn: 'root'` for singletons - **Data Services:** Data services handle API calls and data operations - **Error Handling:** Services include error handling - **DI Hierarchy:** Services follow the Angular DI hierarchy - **Service Contracts:** Interfaces define service contracts - **Focused Responsibilities:** Services focus on specific tasks - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` ## 7. Directive and Pipe Patterns - **Attribute Directives:** Directives handle presentation logic without templates - **Host Property:** The `host` property manages bindings and listeners: ```typescript @Directive({ selector: '[appHighlight]', host: { // Host bindings '[class.highlighted]': 'isHighlighted', '[style.color]': 'highlightColor', // Host listeners '(click)': 'onClick($event)', '(mouseenter)': 'onMouseEnter()', '(mouseleave)': 'onMouseLeave()', // Static properties 'role': 'button', '[attr.aria-label]': 'ariaLabel' } }) ``` - **Selector Prefixes:** Directive selectors use custom prefixes - **Pure Pipes:** Pipes are pure when possible for better performance - **Pipe Naming:** Pipes follow camelCase naming conventions ## 8. State Management Patterns - **Signals:** Signals serve as the primary state management solution - **Component Inputs:** Signal inputs with `input()` handle component inputs - **Two-Way Binding:** Model inputs with `model()` enable two-way binding - **Local State:** Writable signals with `signal()` manage local component state - **Derived State:** Computed signals with `computed()` calculate derived state - **Side Effects:** The `effect()` function handles side effects - **Error Handling:** Signal computations include error handling - **Signal Conversion:** The `toSignal()` and `toObservable()` functions enable interoperability with RxJS ## 9. Testing Patterns - **Test Coverage:** Tests cover components and services - **Unit Tests:** Focused unit tests verify services, pipes, and components - **Component Testing:** TestBed and component harnesses test components - **Mocking:** Tests use mocking techniques for dependencies - **Test Organization:** Tests follow the AAA pattern (Arrange, Act, Assert) - **Test Naming:** Tests have descriptive names that explain the expected behavior - **Playwright Usage:** Playwright handles E2E testing with fixtures and test isolation - **Test Environment:** Test environments match production as closely as possible ## 10. Performance Patterns - **Change Detection:** Components use OnPush change detection strategy - **Lazy Loading:** Routes and components load lazily - **Virtual Scrolling:** Virtual scrolling renders long lists efficiently - **Memoization:** Memoization optimizes expensive computations - **Bundle Size:** Bundle size monitoring and optimization reduce load times - **Server-Side Rendering:** SSR improves initial load performance - **Web Workers:** Web workers handle intensive operations ## 11. Security Patterns - **XSS Prevention:** User input undergoes sanitization - **CSRF Protection:** CSRF tokens secure forms - **Content Security Policy:** CSP headers restrict content sources - **Authentication:** Secure authentication protects user accounts - **Authorization:** Authorization checks control access - **Sensitive Data:** Client-side code excludes sensitive data ## 12. Accessibility Patterns - **ARIA Attributes:** ARIA attributes enhance accessibility - **Keyboard Navigation:** Interactive elements support keyboard access - **Color Contrast:** UI elements maintain proper color contrast ratios - **Screen Readers:** Components work with screen readers - **Focus Management:** Focus management guides user interaction - **Alternative Text:** Images include alt text
# TypeScript Performance Optimization Standards: Best Practices for Efficient Applications This document outlines coding standards and best practices specifically for performance optimization in TypeScript projects. Adhering to these guidelines will improve the speed, responsiveness, efficient use of resources, and overall user experience of your applications. ## Table of Contents - [1. Architectural Considerations for Performance](#1-architectural-considerations-for-performance) - [1.1. Code Splitting](#11-code-splitting) - [1.2. Lazy Loading Modules](#12-lazy-loading-modules) - [1.3. Server-Side Rendering (SSR) or Static Site Generation (SSG)](#13-server-side-rendering-ssr-or-static-site-generation-ssg) - [1.4. Data Structure Selection](#14-data-structure-selection) ## 1. Architectural Considerations for Performance ### 1.1. Code Splitting **Standard:** Implement code splitting to reduce the initial load time of your application. **Why:** Loading only the necessary code on initial page load significantly improves the user experience. **Do This:** * Utilize dynamic imports (`import()`) to load modules on demand. * Configure your bundler (Webpack, Parcel, Rollup) to create separate chunks for different parts of your application. **Don't Do This:** * Load the entire application code in a single bundle. * Use `require()` statements (CommonJS) in modern TypeScript projects where ES Modules are supported. **Example:** ```typescript // Before: Loading everything upfront import { featureA } from './featureA'; import { featureB } from './featureB'; // After: Code splitting with dynamic imports async function loadFeatureA() { const { featureA } = await import('./featureA'); featureA.init(); } async function loadFeatureB() { const { featureB } = await import('./featureB'); featureB.init(); } // Use loadFeatureA or loadFeatureB based on user interaction or route ``` **Bundler Configuration (Webpack example):** ```javascript // webpack.config.js module.exports = { entry: './src/index.ts', output: { filename: '[name].bundle.js', path: path.resolve(__dirname, 'dist'), }, module: { rules: [ { test: /\.tsx?$/, use: 'ts-loader', exclude: /node_modules/, }, ], }, resolve: { extensions: ['.tsx', '.ts', '.js'], }, optimization: { splitChunks: { chunks: 'all', // Split all chunks of code }, }, }; ``` ### 1.2. Lazy Loading Modules **Standard:** Employ lazy loading for non-critical modules or components. **Why:** Reduce the amount of code that needs to be parsed and compiled on initial load. **Do This:** * Load components or modules only when they are needed. * Utilize Intersection Observer API to load components when they become visible in the viewport. **Don't Do This:** * Load modules that are not immediately required for the current user interaction. **Example (Intersection Observer Lazy Loading):** ```typescript function lazyLoadComponent(element: HTMLElement, importPath: string) { const observer = new IntersectionObserver((entries) => { entries.forEach(async (entry) => { if (entry.isIntersecting) { const { default: Component } = await import(importPath); const componentInstance = new Component(); // Instantiate the component. element.appendChild(componentInstance.render()); // Append to the DOM (adjust according to your framework). observer.unobserve(element); } }); }); observer.observe(element); } // Usage: const lazyComponentElement = document.getElementById('lazy-component'); if (lazyComponentElement) { lazyLoadComponent(lazyComponentElement, './MyHeavyComponent'); } ``` ### 1.3. Server-Side Rendering (SSR) or Static Site Generation (SSG) **Standard:** Consider using SSR or SSG for content-heavy, SEO-sensitive, or performance-critical applications. **Why:** Reduces the time to first paint (TTFP) and improves SEO by providing crawlers with pre-rendered content. **Do This:** * Evaluate the trade-offs between SSR, SSG, and client-side rendering (CSR) based on your application's needs. * Use frameworks like Next.js (React), Nuxt.js (Vue), or Angular Universal. * Implement appropriate caching strategies for SSR. **Don't Do This:** * Default to CSR when SSR or SSG could provide significant performance benefits. **Example (Next.js):** ```typescript // pages/index.tsx (Next.js example) import React from 'react'; interface Props { data: { title: string; description: string; }; } const HomePage: React.FC<Props> = ({ data }) => { return ( <div> <h1>{data.title}</h1> <p>{data.description}</p> </div> ); }; export async function getServerSideProps() { // Fetch data from an API, database, or file system. const data = { title: 'My Awesome Website', description: 'Welcome to my extremely performant website!', }; return { props: { data, }, }; } export default HomePage; ``` ### 1.4. Data Structure Selection **Standard:** Select the most appropriate data structure for each specific use case. **Why:** Using appropriate data structures will reduce the complexity and improve the execution speed of algorithms. **Do This:** * Use `Map` when you need to associate keys with values, especially when the keys are not strings or numbers. * Use `Set` when you need to store a collection of unique values. * Use `Record<K, V>` type for type-safe object mapping. * Consider specialized data structures for specific performance needs (e.g., priority queues, linked lists). **Don't Do This:** * Use generic arrays or objects when more specialized data structures would be more efficient. * Perform frequent lookups in arrays when using a Map or Set would be more performant. **Example:** ```typescript // Before: Using an array for lookups const users = [ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' } ]; // O(n) lookup operation const findUser = (id: number) => users.find(user => user.id === id); // After: Using Map for efficient lookups const userMap = new Map<number, {id: number, name: string}>(); userMap.set(1, { id: 1, name: 'Alice' }); userMap.set(2, { id: 2, name: 'Bob' }); userMap.set(3, { id: 3, name: 'Charlie' }); // O(1) lookup operation const getUser = (id: number) => userMap.get(id); ```
# NgRx Signals Patterns This document outlines the state management patterns used in our Angular applications with NgRx Signals Store. ## 1. NgRx Signals Architecture - **Component-Centric Design:** Stores are designed around component requirements - **Hierarchical State:** State is organized in hierarchical structures - **Computed State:** Derived state uses computed values - **Declarative Updates:** State updates use patchState for immutability - **Store Composition:** Stores compose using features and providers - **Reactivity:** UIs build on automatic change detection - **Signal Interoperability:** Signals integrate with existing RxJS-based systems - **SignalMethod & RxMethod:** Use `signalMethod` for lightweight, signal-driven side effects; use `rxMethod` for Observable-based side effects and RxJS integration. When a service returns an Observable, always use `rxMethod` for side effects instead of converting to Promise or using async/await. ## 2. Signal Store Structure - **Store Creation:** The `signalStore` function creates stores - **Protected State:** Signal Store state is protected by default (`{ protectedState: true }`) - **State Definition:** Initial state shape is defined with `withState<StateType>({...})` - Root level state is always an object: `withState({ users: [], count: 0 })` - Arrays are contained within objects: `withState({ items: [] })` - **Dependency Injection:** Stores are injectable with `{ providedIn: 'root' }` or feature/component providers - **Store Features:** Built-in features (`withEntities`, `withHooks`, `signalStoreFeature`) handle cross-cutting concerns and enable store composition - **State Interface:** State interfaces provide strong typing - **Private Members:** Prefix all internal state, computed signals, and methods with an underscore (`_`). Ensure unique member names across state, computed, and methods. ```typescript withState({ count: 0, _internalCount: 0 }); withComputed(({ count, _internalCount }) => ({ doubleCount: computed(() => count() * 2), _doubleInternal: computed(() => _internalCount() * 2), })); ``` - **Member Integrity:** Store members have unique names across state, computed, and methods - **Initialization:** State initializes with meaningful defaults - **Collection Management:** The `withEntities` feature manages collections. Prefer atomic entity operations (`addEntity`, `updateEntity`, `removeEntity`, `setAllEntities`) over bulk state updates. Use `entityConfig` and `selectId` for entity identification. - **Entity Adapter Configuration:** Use `entityConfig` to configure the entity adapter for each store. Always specify the `entity` type, `collection` name, and a `selectId` function for unique entity identification. Pass the config to `withEntities<T>(entityConfig)` for strong typing and consistent entity management. ```typescript const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( { providedIn: "root" }, withState(initialState), withEntities(userEntityConfig), // ... ); ``` - **Custom Store Properties:** Use `withProps` to add static properties, observables, and dependencies. Expose observables with `toObservable`. ```typescript // Signal store structure example import { signalStore, withState, withComputed, withMethods, patchState, type, } from "@ngrx/signals"; import { withEntities, entityConfig } from "@ngrx/signals/entities"; import { computed, inject } from "@angular/core"; import { UserService } from "./user.service"; import { User } from "./user.model"; import { setAllEntities } from "@ngrx/signals/entities"; export interface UserState { selectedUserId: string | null; loading: boolean; error: string | null; } const initialState: UserState = { selectedUserId: null, loading: false, error: null, }; const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( { providedIn: "root" }, withState(initialState), withEntities(userEntityConfig), withComputed(({ usersEntities, usersEntityMap, selectedUserId }) => ({ selectedUser: computed(() => { const id = selectedUserId(); return id ? usersEntityMap()[id] : undefined; }), totalUserCount: computed(() => usersEntities().length), })), withMethods((store, userService = inject(UserService)) => ({ loadUsers: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true, error: null }); return userService.getUsers().pipe( tapResponse({ next: (users) => patchState(store, setAllEntities(users, userEntityConfig), { loading: false, }), error: () => patchState(store, { loading: false, error: "Failed to load users", }), }), ); }), ), ), selectUser(userId: string | null): void { patchState(store, { selectedUserId: userId }); }, })), ); ``` ## 3. Signal Store Methods - **Method Definition:** Methods are defined within `withMethods` - **Dependency Injection:** The `inject()` function accesses services within `withMethods` - **Method Organization:** Methods are grouped by domain functionality - **Method Naming:** Methods have clear, action-oriented names - **State Updates:** `patchState(store, newStateSlice)` or `patchState(store, (currentState) => newStateSlice)` updates state immutably - **Async Operations:** Methods handle async operations and update loading/error states - **Computed Properties:** `withComputed` defines derived state - **RxJS Integration:** `rxMethod` integrates RxJS streams. Use `rxMethod` for all store methods that interact with Observable-based APIs or services. Avoid using async/await with Observables in store methods. ```typescript // Signal store method patterns import { signalStore, withState, withMethods, patchState } from "@ngrx/signals"; import { inject } from "@angular/core"; import { TodoService } from "./todo.service"; import { Todo } from "./todo.model"; export interface TodoState { todos: Todo[]; loading: boolean; } export const TodoStore = signalStore( { providedIn: "root" }, withState<TodoState>({ todos: [], loading: false }), withMethods((store, todoService = inject(TodoService)) => ({ addTodo(todo: Todo): void { patchState(store, (state) => ({ todos: [...state.todos, todo], })); }, loadTodosSimple: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true }); return todoService.getTodos().pipe( tapResponse({ next: (todos) => patchState(store, { todos, loading: false }), error: () => patchState(store, { loading: false }), }), ); }), ), ), })), ); ``` ## 4. Entity Management - **Entity Configuration:** Entity configurations include ID selectors - **Collection Operations:** Entity operations handle CRUD operations - **Entity Relationships:** Computed properties manage entity relationships - **Entity Updates:** Prefer atomic entity operations (`addEntity`, `updateEntity`, `removeEntity`, `setAllEntities`) over bulk state updates. Use `entityConfig` and `selectId` for entity identification. ```typescript // Entity management patterns const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( withEntities(userEntityConfig), withMethods((store) => ({ addUser: signalMethod<User>((user) => { patchState(store, addEntity(user, userEntityConfig)); }), updateUser: signalMethod<{ id: string; changes: Partial<User> }>( ({ id, changes }) => { patchState(store, updateEntity({ id, changes }, userEntityConfig)); }, ), removeUser: signalMethod<string>((id) => { patchState(store, removeEntity(id, userEntityConfig)); }), setUsers: signalMethod<User[]>((users) => { patchState(store, setAllEntities(users, userEntityConfig)); }), })), ); ``` ## 5. Component Integration ### Component State Access - **Signal Properties:** Components access signals directly in templates - **OnPush Strategy:** Signal-based components use OnPush change detection - **Store Injection:** Components inject store services with the `inject` function - **Default Values:** Signals have default values - **Computed Values:** Components derive computed values from signals - **Signal Effects:** Component effects handle side effects ```typescript // Component integration patterns @Component({ standalone: true, imports: [UserListComponent], template: ` @if (userStore.users().length > 0) { <app-user-list [users]="userStore.users()"></app-user-list> } @else { <p>No users loaded yet.</p> } <div>Selected user: {{ selectedUserName() }}</div> `, changeDetection: ChangeDetectionStrategy.OnPush, }) export class UsersContainerComponent implements OnInit { readonly userStore = inject(UserStore); selectedUserName = computed(() => { const user = this.userStore.selectedUser(); return user ? user.name : "None"; }); constructor() { effect(() => { const userId = this.userStore.selectedUserId(); if (userId) { console.log(`User selected: ${userId}`); } }); } ngOnInit() { this.userStore.loadUsers(); } } ``` ### Signal Store Hooks - **Lifecycle Hooks:** The `withHooks` feature adds lifecycle hooks to stores - **Initialization:** The `onInit` hook initializes stores - **Cleanup:** The `onDestroy` hook cleans up resources - **State Synchronization:** Hooks synchronize state between stores ```typescript // Signal store hooks patterns export const UserStore = signalStore( withState<UserState>({ /* initial state */ }), withMethods(/* store methods */), withHooks({ onInit: (store) => { // Initialize the store store.loadUsers(); // Return cleanup function if needed return () => { // Cleanup code }; }, }), ); ``` ## 6. Advanced Signal Patterns ### Signal Store Features - **Feature Creation:** The `signalStoreFeature` function creates reusable features - **Generic Feature Types:** Generic type parameters enhance feature reusability ```typescript function withMyFeature<T>(config: Config<T>) { return signalStoreFeature(/*...*/); } ``` - **Feature Composition:** Multiple features compose together - **Cross-Cutting Concerns:** Features handle logging, undo/redo, and other concerns - **State Slices:** Features define and manage specific state slices ```typescript // Signal store feature patterns export function withUserFeature() { return signalStoreFeature( withState<UserFeatureState>({ /* feature state */ }), withComputed((state) => ({ /* computed properties */ })), withMethods((store) => ({ /* methods */ })), ); } // Using the feature export const AppStore = signalStore( withUserFeature(), withOtherFeature(), withMethods((store) => ({ /* app-level methods */ })), ); ``` ### Signals and RxJS Integration - **Signal Conversion:** `toSignal()` and `toObservable()` convert between Signals and Observables - **Effects:** Angular's `effect()` function reacts to signal changes - **RxJS Method:** `rxMethod<T>(pipeline)` handles Observable-based side effects. Always prefer `rxMethod` for Observable-based service calls in stores. Do not convert Observables to Promises for store logic. - Accepts input values, Observables, or Signals - Manages subscription lifecycle automatically - **Reactive Patterns:** Signals combine with RxJS for complex asynchronous operations ```typescript // Signal and RxJS integration patterns import { signalStore, withState, withMethods, patchState } from "@ngrx/signals"; import { rxMethod } from "@ngrx/signals/rxjs-interop"; import { tapResponse } from "@ngrx/operators"; import { pipe, switchMap } from "rxjs"; import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; import { User } from "./user.model"; export interface UserState { users: User[]; loading: boolean; error: string | null; } export const UserStore = signalStore( { providedIn: "root" }, withState({ users: [], loading: false, error: null }), withMethods((store, http = inject(HttpClient)) => ({ loadUsers: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true, error: null }); return http.get<User[]>("/api/users").pipe( tapResponse({ next: (users) => patchState(store, { users, loading: false }), error: () => patchState(store, { loading: false, error: "Failed to load users", }), }), ); }), ), ), })), ); ``` ### Signal Method for Side Effects The `signalMethod` function manages side effects driven by Angular Signals within Signal Store: - **Input Flexibility:** The processor function accepts static values or Signals - **Automatic Cleanup:** The underlying effect cleans up when the store is destroyed - **Explicit Tracking:** Only the input signal passed to the processor function is tracked - **Lightweight:** Smaller bundle size compared to `rxMethod` ```typescript // Signal method patterns import { signalStore, withState, withMethods, patchState } from '@ngrx/signals'; import { signalMethod } from '@ngrx/signals'; import { inject } from '@angular/core'; import { Logger } from './logger'; interface UserPreferencesState { theme: 'light' | 'dark'; sendNotifications: boolean; const initialState: UserPreferencesState = { theme: 'light', sendNotifications: true, }; export const PreferencesStore = signalStore( { providedIn: 'root' }, withState(initialState), withProps(() => ({ logger: inject(Logger), })); withMethods((store) => ({ setSendNotifications(enabled: boolean): void { patchState(store, { sendNotifications: enabled }); }, // Signal method reacts to theme changes logThemeChange: signalMethod<'light' | 'dark'>((theme) => { store.logger.log(`Theme changed to: ${theme}`); }), setTheme(newTheme: 'light' | 'dark'): void { patchState(store, { theme: newTheme }); }, })), ); ``` ## 7. Custom Store Properties - **Custom Properties:** The `withProps` feature adds static properties, observables, and dependencies - **Observable Exposure:** `toObservable` within `withProps` exposes state as observables ```typescript withProps(({ isLoading }) => ({ isLoading$: toObservable(isLoading), })); ``` - **Dependency Grouping:** `withProps` groups dependencies for use across store features ```typescript withProps(() => ({ booksService: inject(BooksService), logger: inject(Logger), })); ``` ## 8. Project Organization ### Store Organization - **File Location:** Store definitions (`*.store.ts`) exist in dedicated files - **Naming Convention:** Stores follow the naming pattern `FeatureNameStore` - **Model Co-location:** State interfaces and models exist near store definitions - **Provider Functions:** Provider functions (`provideFeatureNameStore()`) encapsulate store providers ```typescript // Provider function pattern import { Provider } from "@angular/core"; import { UserStore } from "./user.store"; export function provideUserSignalStore(): Provider { return UserStore; } ``` ### Store Hierarchy - **Parent-Child Relationships:** Stores have clear relationships - **State Sharing:** Related components share state - **State Ownership:** Each state slice has a clear owner - **Store Composition:** Complex UIs compose multiple stores
Debe preferir usar el gestor de versiones "pnpm" por sobre "npm" para la ejecución de los comandos.
# NgRx Signals Testing Guidelines These guidelines outline best practices for testing NgRx Signals Stores in Angular applications. ## 1. General Testing Patterns - **Public API Testing:** Tests interact with stores through their public API - **TestBed Usage:** Angular's `TestBed` instantiates and injects Signal Stores - **Dependency Mocking:** Tests mock store dependencies - **Store Mocking:** Component tests mock stores - **State and Computed Testing:** Tests assert on signal and computed property values - **Method Testing:** Tests trigger methods and assert on resulting state - **Protected State Access:** The `unprotected` utility from `@ngrx/signals/testing` accesses protected state - **Integration Testing:** Tests cover stores and components together - **Custom Extension Testing:** Tests verify custom store features ## 2. Example: Store Testing ```typescript import { TestBed } from "@angular/core/testing"; import { unprotected } from "@ngrx/signals/testing"; describe("CounterStore", () => { it("recomputes doubleCount on count changes", () => { const counterStore = TestBed.inject(CounterStore); patchState(unprotected(counterStore), { count: 10 }); expect(counterStore.doubleCount()).toBe(20); }); }); ``` --- Follow these patterns for all NgRx Signals Store tests. Use Jasmine, Angular’s latest APIs, and strong typing. For more, see the official NgRx Signals documentation.