diff --git a/frontend/angular/advanced-performance.md b/frontend/angular/advanced-performance.md index 70b5a2d..abf3cfb 100644 --- a/frontend/angular/advanced-performance.md +++ b/frontend/angular/advanced-performance.md @@ -5,7 +5,7 @@ level: Senior/Architect version: 20+ tags: [performance, advanced, angular, best-practices, clean-code, scalable-code] ai_role: Senior Angular Performance Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿš€ Angular Advanced Performance Best Practices & Expert Patterns diff --git a/frontend/angular/architecture.md b/frontend/angular/architecture.md index 197f8e3..5e794ec 100644 --- a/frontend/angular/architecture.md +++ b/frontend/angular/architecture.md @@ -5,7 +5,7 @@ level: Senior/Architect version: 20+ tags: [architecture, dependency-injection, angular, best-practices, clean-code, scalable-code] ai_role: Senior Angular Architecture Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ— Angular Architecture & Dependency Injection Best Practices diff --git a/frontend/angular/basics.md b/frontend/angular/basics.md new file mode 100644 index 0000000..95db775 --- /dev/null +++ b/frontend/angular/basics.md @@ -0,0 +1,308 @@ +--- +technology: Angular +domain: frontend +level: Senior/Architect +version: "20+" +tags: [angular, best-practices, clean-code, basics] +ai_role: Senior Angular Expert +last_updated: 2026-05-05 +--- + +# ๐Ÿš€ Basics & Popular + +[โฌ†๏ธ Back to Top](./readme.md) + +### ๐Ÿšจ 1. Using `@Input()` Decorator +> [!NOTE] +> **Context:** Component Inputs +### โŒ Bad Practice +```typescript +@Input() title: string; +``` +### โš ๏ธ Problem +Using the `@Input()` decorator breaks the functional reactivity of Zoneless applications. +### โœ… Best Practice +```typescript +title = input(); +``` +### ๐Ÿš€ Solution +Use Signal Inputs (`input()`). This allows Angular to precisely know *which* specific component requires an update, paving the way for Zoneless applications. +--- + +### ๐Ÿšจ 2. Using `@Output()` Decorator +> [!NOTE] +> **Context:** Component Outputs +### โŒ Bad Practice +```typescript +@Output() save = new EventEmitter(); +``` +### โš ๏ธ Problem +The classic `EventEmitter` adds an unnecessary layer of abstraction over RxJS Subject and does not integrate with the Angular functional API. +### โœ… Best Practice +```typescript +save = output(); +``` +### ๐Ÿš€ Solution +Use the `output()` function. It provides strict typing, better performance, and a unified API with Signal Inputs. +--- + +### ๐Ÿšจ 3. Two-Way Binding with `@Input()` and `@Output()` +> [!NOTE] +> **Context:** Model Synchronization +### โŒ Bad Practice +```typescript +@Input() value: string; +@Output() valueChange = new EventEmitter(); +``` +### โš ๏ธ Problem +Boilerplate code that is easy to break if you make a mistake in naming the `Change` event. +### โœ… Best Practice +```typescript +value = model(); +``` +### ๐Ÿš€ Solution +> [!IMPORTANT] +> Use `model()`. This creates a Signal that MUST be both read and written to, automatically synchronizing its state with the parent. +--- + +### ๐Ÿšจ 4. Structural Directives (`*ngIf`, `*ngFor`) +> [!NOTE] +> **Context:** Template Control Flow +### โŒ Bad Practice +```html +
+
  • {{ item }}
    • +
    +``` +### โš ๏ธ Problem +Directives require importing `CommonModule` or `NgIf/NgFor`, increasing bundle size. Micro-template syntax is complex for static analysis and type-checking. +### โœ… Best Practice +```html +@if (isLoaded()) { + @for (item of items(); track item.id) { +
  • {{ item.name }}
    • + } +} @else { + +} +``` +### ๐Ÿš€ Solution +Use the built-in Control Flow (`@if`, `@for`). It is built into the compiler, requires no imports, supports improved type-narrowing, and runs faster. +--- + +### ๐Ÿšจ 5. Subscribing in Components (Logic in `ngOnInit`) +> [!NOTE] +> **Context:** Data Fetching +### โŒ Bad Practice +```typescript +data: unknown; +ngOnInit() { + this.service.getData().subscribe(res => this.data = res); +} +``` +### โš ๏ธ Problem +Imperative subscriptions lead to memory leaks (if you forget to `unsubscribe`), "Callback Hell", and state desynchronization. Requires manual subscription management. +### โœ… Best Practice +```typescript +data = toSignal(this.service.getData()); +``` +### ๐Ÿš€ Solution +Use `toSignal()` to convert an Observable into a Signal. This automatically manages the subscription and integrates the data stream into the reactivity system. +--- + +### ๐Ÿšจ 6. `BehaviorSubject` for Local State +> [!NOTE] +> **Context:** Component State Management +### โŒ Bad Practice +```typescript +private count$ = new BehaviorSubject(0); +getCount() { return this.count$.value; } +``` +### โš ๏ธ Problem +RxJS is overkill for simple synchronous state. `BehaviorSubject` requires `.value` for access and `.next()` for writes, increasing cognitive load. +### โœ… Best Practice +```typescript +count = signal(0); +// Access: count() +// Update: count.set(1) +``` +### ๐Ÿš€ Solution +Use `signal()` for local state. It is a primitive designed specifically for synchronizing UI and data. +--- + +### ๐Ÿšจ 7. Derived State with `ngOnChanges` +> [!NOTE] +> **Context:** Reactivity +### โŒ Bad Practice +```typescript +ngOnChanges(changes: SimpleChanges) { + if (changes['firstName']) { + this.fullName = `${this.firstName} ${this.lastName}`; + } +} +``` +### โš ๏ธ Problem +`ngOnChanges` is triggered only when Inputs change, has complex typing, and runs before View initialization. +### โœ… Best Practice +```typescript +fullName = computed(() => `${this.firstName()} ${this.lastName()}`); +``` +### ๐Ÿš€ Solution +Use `computed()`. The signal is recalculated *only* when its dependencies change, and the result is memoized (cached). +--- + +### ๐Ÿšจ 8. Constructor Dependency Injection +> [!NOTE] +> **Context:** DI Pattern +### โŒ Bad Practice +```typescript +constructor(private http: HttpClient, private store: Store) {} +``` +### โš ๏ธ Problem +Constructors become cluttered with many dependencies. When inheriting classes, dependencies must be passed through `super()`. +### โœ… Best Practice +```typescript +private http = inject(HttpClient); +private store = inject(Store); +``` +### ๐Ÿš€ Solution +Use the `inject()` function. It operates in the initialization context (fields or constructor), is type-safe, and does not require `super()` during inheritance. +--- + +### ๐Ÿšจ 9. Modules (`NgModule`) +> [!NOTE] +> **Context:** App Architecture +### โŒ Bad Practice +```typescript +@NgModule({ + declarations: [AppComponent], + imports: [BrowserModule] +}) +export class AppModule {} +``` +### โš ๏ธ Problem +Modules create an unnecessary level of indirection. Components become dependent on the module context, complicating Lazy Loading and testing. +### โœ… Best Practice +```typescript +@Component({ + standalone: true, + imports: [CommonModule] +}) +``` +### ๐Ÿš€ Solution +Use Standalone Components. This is the Angular v14+ standard that makes components self-sufficient and tree-shakable. +--- + +### ๐Ÿšจ 10. String-based Route Loading +> [!NOTE] +> **Context:** Lazy Loading Routing +### โŒ Bad Practice +```typescript +loadChildren: () => import('./module').then(m => m.UserModule) +``` +### โš ๏ธ Problem +Loading modules pulls in transitive dependencies that might not be needed. +### โœ… Best Practice +```typescript +loadComponent: () => import('./user.component').then(c => c.UserComponent) +``` +### ๐Ÿš€ Solution +Use `loadComponent` for routing to Standalone components. This ensures minimal chunk size. +--- + +### ๐Ÿšจ 11. Heavy Logic in Templates +> [!NOTE] +> **Context:** Template Performance +### โŒ Bad Practice +```html +
    {{ calculateTotal(items) }}
    +``` +### โš ๏ธ Problem +The `calculateTotal` function is called during *every* Change Detection (CD) cycle, even if `items` have not changed. This kills UI performance. +### โœ… Best Practice +```typescript +total = computed(() => this.calculateTotal(this.items())); +``` +```html +
    {{ total() }}
    +``` +### ๐Ÿš€ Solution +Extract logic into `computed()` signals or Pure Pipes. They are only executed when input data changes. +--- + +### ๐Ÿšจ 12. Manual Subscription Management (`takeUntil`) +> [!NOTE] +> **Context:** RxJS Memory Leaks +### โŒ Bad Practice +```typescript +destroy$ = new Subject(); +ngOnDestroy() { this.destroy$.next(); } +stream$.pipe(takeUntil(this.destroy$)).subscribe(); +``` +### โš ๏ธ Problem +It's easy to forget `takeUntil` or `unsubscribe`. Requires a lot of boilerplate code in every component. +### โœ… Best Practice +```typescript +stream$.pipe(takeUntilDestroyed()).subscribe(); +``` +### ๐Ÿš€ Solution +Use the `takeUntilDestroyed()` operator. It automatically unsubscribes upon context destruction (component, directive, service). +--- + +### ๐Ÿšจ 13. Deeply Nested Components Passing Data +> [!NOTE] +> **Context:** Prop Drilling +### โŒ Bad Practice +```html + + + + +``` +### โš ๏ธ Problem +"Prop drilling" heavily couples intermediate components to data they don't need, just for the sake of passing it deeper. +### โœ… Best Practice +```typescript +// Service +theme = signal('dark'); +// Grandchild +theme = inject(ThemeService).theme; +``` +### ๐Ÿš€ Solution +Use Signal Stores or services for state sharing, or the new `input()` API with context inheritance (in the future). +--- + +### ๐Ÿšจ 14. Accessing DOM directly (`ElementRef.nativeElement`) +> [!NOTE] +> **Context:** Security & Abstraction +### โŒ Bad Practice +```typescript +el.nativeElement.style.backgroundColor = 'red'; +``` +### โš ๏ธ Problem +Direct DOM access breaks abstraction (doesn't work in SSR/Web Workers) and opens up XSS vulnerabilities. It bypasses Angular Sanitization mechanisms. +### โœ… Best Practice +```typescript +// Use Renderer2 or bindings +
    +``` +### ๐Ÿš€ Solution +Use style/class bindings or `Renderer2`. For direct manipulations, consider directives. +--- + +### ๐Ÿšจ 15. Zone.js overhead +> [!NOTE] +> **Context:** Change Detection +### โŒ Bad Practice +The application relies on Zone.js for any asynchronous event (setTimeout, Promise, XHR). +### โš ๏ธ Problem +Zone.js patches all browser APIs, adding overhead and increasing bundle size. CD triggers more often than necessary. +### โœ… Best Practice +```typescript +bootstrapApplication(App, { + providers: [provideExperimentalZonelessChangeDetection()] +}); +``` +### ๐Ÿš€ Solution +Migrate to Zoneless mode. Use Signals to notify Angular when a re-render is needed. +--- diff --git a/frontend/angular/components-signals.md b/frontend/angular/components-signals.md index 31adc19..a36b53f 100644 --- a/frontend/angular/components-signals.md +++ b/frontend/angular/components-signals.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "20+" tags: [angular, best-practices, clean-code, signals, components] ai_role: Senior Angular Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงฉ Components & Signals diff --git a/frontend/angular/data-forms.md b/frontend/angular/data-forms.md index 5d4a4d4..765e1a2 100644 --- a/frontend/angular/data-forms.md +++ b/frontend/angular/data-forms.md @@ -5,7 +5,7 @@ level: Senior/Architect version: 20+ tags: [forms, data, angular, best-practices, clean-code, scalable-code] ai_role: Senior Angular Data Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ“ Angular Data & Forms Best Practices diff --git a/frontend/angular/expert-niche.md b/frontend/angular/expert-niche.md index e090dad..33ed629 100644 --- a/frontend/angular/expert-niche.md +++ b/frontend/angular/expert-niche.md @@ -5,7 +5,7 @@ level: Senior/Architect version: 20+ tags: [expert, niche, angular, best-practices, clean-code, scalable-code] ai_role: Senior Angular Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿง  Angular Expert/Niche Best Practices diff --git a/frontend/angular/reactivity.md b/frontend/angular/reactivity.md index 6bd445b..f713e00 100644 --- a/frontend/angular/reactivity.md +++ b/frontend/angular/reactivity.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "20+" tags: [angular, best-practices, clean-code, reactivity, rxjs] ai_role: Senior Angular Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # โšก Reactivity & RxJS diff --git a/frontend/angular/readme.md b/frontend/angular/readme.md index 77107e5..6b563f3 100644 --- a/frontend/angular/readme.md +++ b/frontend/angular/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: 20+ tags: [best-practices, clean-code, architecture-patterns, vibe-coding, cursor-rules, typescript, software-architecture, system-design, solid-principles, production-ready, programming-standards, react-best-practices, node-js, design-patterns, scalable-code, windsurf-rules, ai-coding, fsd, ddd, enterprise-patterns] ai_role: Senior Angular Performance Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐ŸŽจ Angular Best Practices & Production-Ready Patterns @@ -27,300 +27,7 @@ Please refer to the specialized guides for detailed best practices: - [๐Ÿงฉ Components & Signals](./components-signals.md) - [โšก Reactivity & RxJS](./reactivity.md) -### ๐Ÿšจ 1. Using `@Input()` Decorator -> [!NOTE] -> **Context:** Component Inputs -### โŒ Bad Practice -```typescript -@Input() title: string; -``` -### โš ๏ธ Problem -Using the `@Input()` decorator breaks the functional reactivity of Zoneless applications. -### โœ… Best Practice -```typescript -title = input(); -``` -### ๐Ÿš€ Solution -Use Signal Inputs (`input()`). This allows Angular to precisely know *which* specific component requires an update, paving the way for Zoneless applications. ---- - -### ๐Ÿšจ 2. Using `@Output()` Decorator -> [!NOTE] -> **Context:** Component Outputs -### โŒ Bad Practice -```typescript -@Output() save = new EventEmitter(); -``` -### โš ๏ธ Problem -The classic `EventEmitter` adds an unnecessary layer of abstraction over RxJS Subject and does not integrate with the Angular functional API. -### โœ… Best Practice -```typescript -save = output(); -``` -### ๐Ÿš€ Solution -Use the `output()` function. It provides strict typing, better performance, and a unified API with Signal Inputs. ---- - -### ๐Ÿšจ 3. Two-Way Binding with `@Input()` and `@Output()` -> [!NOTE] -> **Context:** Model Synchronization -### โŒ Bad Practice -```typescript -@Input() value: string; -@Output() valueChange = new EventEmitter(); -``` -### โš ๏ธ Problem -Boilerplate code that is easy to break if you make a mistake in naming the `Change` event. -### โœ… Best Practice -```typescript -value = model(); -``` -### ๐Ÿš€ Solution -> [!IMPORTANT] -> Use `model()`. This creates a Signal that MUST be both read and written to, automatically synchronizing its state with the parent. ---- - -### ๐Ÿšจ 4. Structural Directives (`*ngIf`, `*ngFor`) -> [!NOTE] -> **Context:** Template Control Flow -### โŒ Bad Practice -```html -
    -
  • {{ item }}
    • -
    -``` -### โš ๏ธ Problem -Directives require importing `CommonModule` or `NgIf/NgFor`, increasing bundle size. Micro-template syntax is complex for static analysis and type-checking. -### โœ… Best Practice -```html -@if (isLoaded()) { - @for (item of items(); track item.id) { -
  • {{ item.name }}
    • - } -} @else { - -} -``` -### ๐Ÿš€ Solution -Use the built-in Control Flow (`@if`, `@for`). It is built into the compiler, requires no imports, supports improved type-narrowing, and runs faster. ---- - -### ๐Ÿšจ 5. Subscribing in Components (Logic in `ngOnInit`) -> [!NOTE] -> **Context:** Data Fetching -### โŒ Bad Practice -```typescript -data: unknown; -ngOnInit() { - this.service.getData().subscribe(res => this.data = res); -} -``` -### โš ๏ธ Problem -Imperative subscriptions lead to memory leaks (if you forget to `unsubscribe`), "Callback Hell", and state desynchronization. Requires manual subscription management. -### โœ… Best Practice -```typescript -data = toSignal(this.service.getData()); -``` -### ๐Ÿš€ Solution -Use `toSignal()` to convert an Observable into a Signal. This automatically manages the subscription and integrates the data stream into the reactivity system. ---- - -### ๐Ÿšจ 6. `BehaviorSubject` for Local State -> [!NOTE] -> **Context:** Component State Management -### โŒ Bad Practice -```typescript -private count$ = new BehaviorSubject(0); -getCount() { return this.count$.value; } -``` -### โš ๏ธ Problem -RxJS is overkill for simple synchronous state. `BehaviorSubject` requires `.value` for access and `.next()` for writes, increasing cognitive load. -### โœ… Best Practice -```typescript -count = signal(0); -// Access: count() -// Update: count.set(1) -``` -### ๐Ÿš€ Solution -Use `signal()` for local state. It is a primitive designed specifically for synchronizing UI and data. ---- - -### ๐Ÿšจ 7. Derived State with `ngOnChanges` -> [!NOTE] -> **Context:** Reactivity -### โŒ Bad Practice -```typescript -ngOnChanges(changes: SimpleChanges) { - if (changes['firstName']) { - this.fullName = `${this.firstName} ${this.lastName}`; - } -} -``` -### โš ๏ธ Problem -`ngOnChanges` is triggered only when Inputs change, has complex typing, and runs before View initialization. -### โœ… Best Practice -```typescript -fullName = computed(() => `${this.firstName()} ${this.lastName()}`); -``` -### ๐Ÿš€ Solution -Use `computed()`. The signal is recalculated *only* when its dependencies change, and the result is memoized (cached). ---- - -### ๐Ÿšจ 8. Constructor Dependency Injection -> [!NOTE] -> **Context:** DI Pattern -### โŒ Bad Practice -```typescript -constructor(private http: HttpClient, private store: Store) {} -``` -### โš ๏ธ Problem -Constructors become cluttered with many dependencies. When inheriting classes, dependencies must be passed through `super()`. -### โœ… Best Practice -```typescript -private http = inject(HttpClient); -private store = inject(Store); -``` -### ๐Ÿš€ Solution -Use the `inject()` function. It operates in the initialization context (fields or constructor), is type-safe, and does not require `super()` during inheritance. ---- - -### ๐Ÿšจ 9. Modules (`NgModule`) -> [!NOTE] -> **Context:** App Architecture -### โŒ Bad Practice -```typescript -@NgModule({ - declarations: [AppComponent], - imports: [BrowserModule] -}) -export class AppModule {} -``` -### โš ๏ธ Problem -Modules create an unnecessary level of indirection. Components become dependent on the module context, complicating Lazy Loading and testing. -### โœ… Best Practice -```typescript -@Component({ - standalone: true, - imports: [CommonModule] -}) -``` -### ๐Ÿš€ Solution -Use Standalone Components. This is the Angular v14+ standard that makes components self-sufficient and tree-shakable. ---- - -### ๐Ÿšจ 10. String-based Route Loading -> [!NOTE] -> **Context:** Lazy Loading Routing -### โŒ Bad Practice -```typescript -loadChildren: () => import('./module').then(m => m.UserModule) -``` -### โš ๏ธ Problem -Loading modules pulls in transitive dependencies that might not be needed. -### โœ… Best Practice -```typescript -loadComponent: () => import('./user.component').then(c => c.UserComponent) -``` -### ๐Ÿš€ Solution -Use `loadComponent` for routing to Standalone components. This ensures minimal chunk size. ---- - -### ๐Ÿšจ 11. Heavy Logic in Templates -> [!NOTE] -> **Context:** Template Performance -### โŒ Bad Practice -```html -
    {{ calculateTotal(items) }}
    -``` -### โš ๏ธ Problem -The `calculateTotal` function is called during *every* Change Detection (CD) cycle, even if `items` have not changed. This kills UI performance. -### โœ… Best Practice -```typescript -total = computed(() => this.calculateTotal(this.items())); -``` -```html -
    {{ total() }}
    -``` -### ๐Ÿš€ Solution -Extract logic into `computed()` signals or Pure Pipes. They are only executed when input data changes. ---- - -### ๐Ÿšจ 12. Manual Subscription Management (`takeUntil`) -> [!NOTE] -> **Context:** RxJS Memory Leaks -### โŒ Bad Practice -```typescript -destroy$ = new Subject(); -ngOnDestroy() { this.destroy$.next(); } -stream$.pipe(takeUntil(this.destroy$)).subscribe(); -``` -### โš ๏ธ Problem -It's easy to forget `takeUntil` or `unsubscribe`. Requires a lot of boilerplate code in every component. -### โœ… Best Practice -```typescript -stream$.pipe(takeUntilDestroyed()).subscribe(); -``` -### ๐Ÿš€ Solution -Use the `takeUntilDestroyed()` operator. It automatically unsubscribes upon context destruction (component, directive, service). ---- - -### ๐Ÿšจ 13. Deeply Nested Components Passing Data -> [!NOTE] -> **Context:** Prop Drilling -### โŒ Bad Practice -```html - - - - -``` -### โš ๏ธ Problem -"Prop drilling" heavily couples intermediate components to data they don't need, just for the sake of passing it deeper. -### โœ… Best Practice -```typescript -// Service -theme = signal('dark'); -// Grandchild -theme = inject(ThemeService).theme; -``` -### ๐Ÿš€ Solution -Use Signal Stores or services for state sharing, or the new `input()` API with context inheritance (in the future). ---- - -### ๐Ÿšจ 14. Accessing DOM directly (`ElementRef.nativeElement`) -> [!NOTE] -> **Context:** Security & Abstraction -### โŒ Bad Practice -```typescript -el.nativeElement.style.backgroundColor = 'red'; -``` -### โš ๏ธ Problem -Direct DOM access breaks abstraction (doesn't work in SSR/Web Workers) and opens up XSS vulnerabilities. It bypasses Angular Sanitization mechanisms. -### โœ… Best Practice -```typescript -// Use Renderer2 or bindings -
    -``` -### ๐Ÿš€ Solution -Use style/class bindings or `Renderer2`. For direct manipulations, consider directives. ---- - -### ๐Ÿšจ 15. Zone.js overhead -> [!NOTE] -> **Context:** Change Detection -### โŒ Bad Practice -The application relies on Zone.js for any asynchronous event (setTimeout, Promise, XHR). -### โš ๏ธ Problem -Zone.js patches all browser APIs, adding overhead and increasing bundle size. CD triggers more often than necessary. -### โœ… Best Practice -```typescript -bootstrapApplication(App, { - providers: [provideExperimentalZonelessChangeDetection()] -}); -``` -### ๐Ÿš€ Solution -Migrate to Zoneless mode. Use Signals to notify Angular when a re-render is needed. ---- +- [๐Ÿš€ Basics & Popular](./basics.md) [โฌ†๏ธ Back to Top](#) ## ๐Ÿ“š Specialized Topics diff --git a/frontend/angular/state-management.md b/frontend/angular/state-management.md index c318147..4c8330b 100644 --- a/frontend/angular/state-management.md +++ b/frontend/angular/state-management.md @@ -5,7 +5,7 @@ level: Senior/Architect version: 20+ tags: [state-management, signals, zoneless, angular, best-practices, clean-code, scalable-code] ai_role: Senior Angular State Management Expert -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- diff --git a/frontend/angular/testing.md b/frontend/angular/testing.md index 6d0a76d..43f41a7 100644 --- a/frontend/angular/testing.md +++ b/frontend/angular/testing.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "20+" tags: [angular, testing, best-practices, clean-code, signals, vibe-coding] ai_role: Senior Angular Testing Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงช Angular Testing Best Practices diff --git a/frontend/design-ui/accessibility.md b/frontend/design-ui/accessibility.md index e03f550..16f4da7 100644 --- a/frontend/design-ui/accessibility.md +++ b/frontend/design-ui/accessibility.md @@ -5,7 +5,7 @@ level: Senior/Architect version: Agnostic tags: [vibe-coding, a11y, html, w3c, wcag, best-practices] ai_role: Frontend UI/UX Enforcer -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- # โ™ฟ Accessibility (A11y) Standards diff --git a/frontend/design-ui/component-architecture.md b/frontend/design-ui/component-architecture.md index d693efc..790a151 100644 --- a/frontend/design-ui/component-architecture.md +++ b/frontend/design-ui/component-architecture.md @@ -5,7 +5,7 @@ level: Senior/Architect version: Agnostic tags: [vibe-coding, atomic-design, architecture, ui-components] ai_role: Frontend UI/UX Enforcer -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- # ๐Ÿ—๏ธ UI Component Architecture diff --git a/frontend/design-ui/readme.md b/frontend/design-ui/readme.md index df0b2ad..0ecd335 100644 --- a/frontend/design-ui/readme.md +++ b/frontend/design-ui/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: Latest tags: [vibe-coding, documentation, best-practices, architecture, design-system, accessibility] ai_role: Senior Vibe Coding Expert -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- # ๐ŸŽจ UI/UX Design Production-Ready Best Practices diff --git a/frontend/design-ui/responsive-design.md b/frontend/design-ui/responsive-design.md index e318949..b7efa21 100644 --- a/frontend/design-ui/responsive-design.md +++ b/frontend/design-ui/responsive-design.md @@ -5,7 +5,7 @@ level: Senior/Architect version: Agnostic tags: [vibe-coding, responsive, adaptive, css, best-practices] ai_role: Frontend UI/UX Enforcer -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- # ๐Ÿ“ฑ Responsive & Adaptive Design Principles diff --git a/frontend/design-ui/styling.md b/frontend/design-ui/styling.md index 7e266cc..39544d6 100644 --- a/frontend/design-ui/styling.md +++ b/frontend/design-ui/styling.md @@ -5,7 +5,7 @@ level: Senior/Architect version: Agnostic tags: [vibe-coding, design-tokens, css, styling, best-practices] ai_role: Frontend UI/UX Enforcer -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- # ๐ŸŽจ UI/UX Styling & Design Tokens Rules diff --git a/frontend/javascript/async-logic.md b/frontend/javascript/async-logic.md index 7015c73..b87aa03 100644 --- a/frontend/javascript/async-logic.md +++ b/frontend/javascript/async-logic.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "ES2024+" tags: [javascript, async, promises, best-practices, clean-code, scalable-code] ai_role: Senior JavaScript Asynchronous Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # โณ JavaScript Asynchronous & Logic Best Practices diff --git a/frontend/javascript/basic-syntax.md b/frontend/javascript/basic-syntax.md index 85395c7..866e51e 100644 --- a/frontend/javascript/basic-syntax.md +++ b/frontend/javascript/basic-syntax.md @@ -5,7 +5,7 @@ level: Senior/Architect version: ES2022+ tags: [javascript, best-practices, clean-code, syntax] ai_role: Senior JavaScript Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿ“œ Basic Syntax & Fundamentals diff --git a/frontend/javascript/clean-code.md b/frontend/javascript/clean-code.md index 9b5fcf8..6f72141 100644 --- a/frontend/javascript/clean-code.md +++ b/frontend/javascript/clean-code.md @@ -5,7 +5,7 @@ level: Senior/Architect version: ES2022+ tags: [javascript, best-practices, clean-code, logic] ai_role: Senior JavaScript Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงน Clean Code & Logic diff --git a/frontend/javascript/modern-syntax.md b/frontend/javascript/modern-syntax.md index f29e3a5..c781a6e 100644 --- a/frontend/javascript/modern-syntax.md +++ b/frontend/javascript/modern-syntax.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "ES2024+" tags: [javascript, es6, functional-programming, best-practices, clean-code, scalable-code] ai_role: Senior JavaScript Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # โœจ Modern JavaScript Syntax & Functional Programming Best Practices diff --git a/frontend/javascript/professional-niche.md b/frontend/javascript/professional-niche.md index d7296b3..cfc167d 100644 --- a/frontend/javascript/professional-niche.md +++ b/frontend/javascript/professional-niche.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "ES2024+" tags: [javascript, advanced, best-practices, clean-code, scalable-code] ai_role: Senior JavaScript Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿง  JavaScript Professional & Niche Best Practices (Senior Level) diff --git a/frontend/javascript/readme.md b/frontend/javascript/readme.md index f195912..7d8e34b 100644 --- a/frontend/javascript/readme.md +++ b/frontend/javascript/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: ES6-ES2024 tags: [javascript, clean-code, es6, performance, best-practices] ai_role: Senior JavaScript Performance Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐ŸŽจ JavaScript Best Practise diff --git a/frontend/javascript/testing.md b/frontend/javascript/testing.md index 1ba4b2b..1da9818 100644 --- a/frontend/javascript/testing.md +++ b/frontend/javascript/testing.md @@ -5,7 +5,7 @@ level: Senior/Architect version: ES6-ES2024 tags: [javascript, testing, best-practices, clean-code, tdd, vibe-coding] ai_role: Senior JavaScript Testing Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงช JavaScript Testing Best Practices diff --git a/frontend/qwik/performance.md b/frontend/qwik/performance.md index 6ded16b..bc8c773 100644 --- a/frontend/qwik/performance.md +++ b/frontend/qwik/performance.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1.x" tags: [performance, advanced, qwik, best-practices, clean-code, scalable-code] ai_role: Senior Qwik Performance Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿš€ Qwik Advanced Performance Best Practices diff --git a/frontend/qwik/readme.md b/frontend/qwik/readme.md index a482088..2c625c1 100644 --- a/frontend/qwik/readme.md +++ b/frontend/qwik/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1.x" tags: [best-practices, clean-code, architecture-patterns, vibe-coding, cursor-rules, typescript, software-architecture, system-design, solid-principles, production-ready, programming-standards, react-best-practices, node-js, design-patterns, scalable-code, windsurf-rules, ai-coding, fsd, ddd, enterprise-patterns] ai_role: Senior Qwik Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # โšก Qwik Best Practices & Production-Ready Patterns diff --git a/frontend/qwik/state-management.md b/frontend/qwik/state-management.md index 7de0fc7..329746e 100644 --- a/frontend/qwik/state-management.md +++ b/frontend/qwik/state-management.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1.x" tags: [state-management, advanced, qwik, best-practices, clean-code, scalable-code] ai_role: Senior Qwik State Management Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ”„ Qwik State Management Best Practices diff --git a/frontend/qwik/testing.md b/frontend/qwik/testing.md index 312ac1a..ecf7c55 100644 --- a/frontend/qwik/testing.md +++ b/frontend/qwik/testing.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1+" tags: [qwik, testing, best-practices, clean-code, resumability, vibe-coding] ai_role: Senior Qwik Testing Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงช Qwik Testing Best Practices diff --git a/frontend/react/performance.md b/frontend/react/performance.md index 795a65d..96e59cb 100644 --- a/frontend/react/performance.md +++ b/frontend/react/performance.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "19+" tags: [react, performance, use, react-compiler, best-practices, architecture, clean-code] ai_role: Senior React Performance Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # โšก React Performance & Best Practices diff --git a/frontend/react/readme.md b/frontend/react/readme.md index c62e2b8..316a23e 100644 --- a/frontend/react/readme.md +++ b/frontend/react/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "19+" tags: [react, best-practices, architecture, clean-code, scalable-code, modern-react, server-components] ai_role: Senior React Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # โš›๏ธ React Production-Ready Best Practices diff --git a/frontend/react/security.md b/frontend/react/security.md index edcca03..7fa469b 100644 --- a/frontend/react/security.md +++ b/frontend/react/security.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "19+" tags: [react, security, best-practices, clean-code, xss, server-components, ai-coding] ai_role: Senior React Security Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿ›ก๏ธ React Security Best Practices diff --git a/frontend/react/state-management.md b/frontend/react/state-management.md index ba5fcf9..0f8b964 100644 --- a/frontend/react/state-management.md +++ b/frontend/react/state-management.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "19+" tags: [react, state-management, server-actions, best-practices, architecture, clean-code] ai_role: Senior React State Management Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ”„ React State Management & Server Actions Best Practices diff --git a/frontend/react/testing.md b/frontend/react/testing.md index 206bb44..a234bc1 100644 --- a/frontend/react/testing.md +++ b/frontend/react/testing.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "19+" tags: [react, testing, best-practices, clean-code, tdd, architecture, vibe-coding] ai_role: Senior React Testing Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงช React Testing Best Practices diff --git a/frontend/readme.md b/frontend/readme.md index 991d0b1..2063714 100644 --- a/frontend/readme.md +++ b/frontend/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: Agnostic tags: [best-practices, clean-code, architecture-patterns, vibe-coding, cursor-rules, typescript, software-architecture, system-design, solid-principles, production-ready, programming-standards, react-best-practices, node-js, design-patterns, scalable-code, windsurf-rules, ai-coding, fsd, ddd, enterprise-patterns] ai_role: Senior Frontend Architect -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐ŸŽจ Frontend Best Practices & Production-Ready Patterns diff --git a/frontend/solidjs/performance.md b/frontend/solidjs/performance.md index 8d5f2f3..c7be3fa 100644 --- a/frontend/solidjs/performance.md +++ b/frontend/solidjs/performance.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1.8+" tags: [performance, advanced, solidjs, best-practices, clean-code, scalable-code] ai_role: Senior SolidJS Performance Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿš€ SolidJS Advanced Performance Best Practices diff --git a/frontend/solidjs/readme.md b/frontend/solidjs/readme.md index 628efdd..12bc34b 100644 --- a/frontend/solidjs/readme.md +++ b/frontend/solidjs/readme.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1.8+" tags: [best-practices, clean-code, architecture-patterns, vibe-coding, cursor-rules, typescript, software-architecture, system-design, solid-principles, production-ready, programming-standards, react-best-practices, node-js, design-patterns, scalable-code, windsurf-rules, ai-coding, fsd, ddd, enterprise-patterns] ai_role: Senior SolidJS Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # โšก SolidJS Best Practices & Production-Ready Patterns diff --git a/frontend/solidjs/state-management.md b/frontend/solidjs/state-management.md index 8ce0ffb..e500a94 100644 --- a/frontend/solidjs/state-management.md +++ b/frontend/solidjs/state-management.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1.8+" tags: [state-management, advanced, solidjs, best-practices, clean-code, scalable-code] ai_role: Senior SolidJS State Management Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ”„ SolidJS State Management Best Practices diff --git a/frontend/solidjs/testing.md b/frontend/solidjs/testing.md index c0e941f..0e264e0 100644 --- a/frontend/solidjs/testing.md +++ b/frontend/solidjs/testing.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "1+" tags: [solidjs, testing, best-practices, clean-code, reactivity, vibe-coding] ai_role: Senior SolidJS Testing Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงช SolidJS Testing Best Practices diff --git a/frontend/typescript/fundamentals.md b/frontend/typescript/fundamentals.md new file mode 100644 index 0000000..da659dc --- /dev/null +++ b/frontend/typescript/fundamentals.md @@ -0,0 +1,159 @@ +--- +technology: TypeScript +domain: frontend +level: Senior/Architect +version: "5.5+" +tags: [typescript, best-practices, clean-code, fundamentals] +ai_role: Senior TypeScript Expert +last_updated: 2026-05-05 +--- + +# ๐Ÿš€ Fundamentals (1-10) + +[โฌ†๏ธ Back to Top](./readme.md) + +## โšก 1. `any` vs `unknown` +> [!NOTE] +> **Context:** Handling data of an uncertain type. `any` disables all type-checking, while `unknown` forces safety. +### โŒ Bad Practice +```typescript +function process(data: unknown) { + console.log(data.name); // No error, but might crash at runtime +} +``` +### โš ๏ธ Problem +`any` is a "get out of jail free" card that propagates through the codebase, effectively turning off TypeScript's benefits and hiding potential runtime exceptions. +### โœ… Best Practice +```typescript +function process(data: unknown) { + if (data && typeof data === 'object' && 'name' in data) { + console.log((data as { name: string }).name); + } +} +``` +### ๐Ÿš€ Solution +Use `unknown` for values whose type is not yet determined. It requires a type check or assertion before usage, ensuring the developer acknowledges the data's structure. +--- +## โšก 2. `null` vs `undefined` in APIs +> [!NOTE] +> **Context:** Distinguishing between "value not provided" and "value is empty." +### โŒ Bad Practice +```typescript +interface UserResponse { + bio: string | null | undefined; +} +``` +### โš ๏ธ Problem +Using both creates ambiguity. In JSON, `undefined` properties are often stripped, while `null` is preserved. Mixing them increases complexity in conditional checks. +### โœ… Best Practice +```typescript +interface UserResponse { + bio?: string | null; // Optional if missing, null if explicitly empty +} +``` +### ๐Ÿš€ Solution +Standardize: use `undefined` (optional properties) for missing keys and `null` for intentional absence of value. Avoid using both for the same field unless strictly required by a legacy API. +--- +## โšก 3. `Array` vs `T[]` +> [!NOTE] +> **Context:** Visual consistency in array declarations. +### โŒ Bad Practice +```typescript +const users: Array = []; +const complex: Array = []; +``` +### โš ๏ธ Problem +`Array` is more verbose and can be confused with other generic types. It is harder to scan in complex signatures. +### โœ… Best Practice +```typescript +const users: User[] = []; +const complex: (string | number)[] = []; +``` +### ๐Ÿš€ Solution +Prefer the shorthand `T[]`. It is idiomatic, more readable, and clearly distinguishes arrays from other generic containers like `Record` or `Promise`. +--- +## โšก 4. `interface` vs `type` +> [!NOTE] +> **Context:** Defining object structures and aliases. +### โŒ Bad Practice +```typescript +type Point = { x: number; y: number; }; // Bad: Using type for object structure +interface Status { status: "active" | "inactive"; } // Bad: Trying to use interface for a union-like structure +``` +### โš ๏ธ Problem +Using `type` for object structures prevents declaration merging and reduces performance in TS compiler caching. Using `interface` for unions is impossible or leads to awkward wrapper objects. +### โœ… Best Practice +```typescript +interface Point { x: number; y: number; } +type Status = "active" | "inactive"; +``` +### ๐Ÿš€ Solution +> [!IMPORTANT] +> Prefer `interface` for structure, `type` for unions. Interfaces provide better error messages and performance for structural types in TypeScript 5.x. +> +> **Logical Conflict Resolution:** To enforce the repo standard, NEVER use `type` for defining object structures, and NEVER use `interface` for unions. +--- +## โšก 5. Function Overloads vs Union Types +> [!NOTE] +> **Context:** Handling functions with different input/output combinations. +### โŒ Bad Practice +```typescript +function format(input: string): string; +function format(input: number): string; +function format(input: unknown): string { + return String(input); +} +``` +### โš ๏ธ Problem +Overloads are verbose and can be harder to implement correctly. They often require `any` or complex type-casting in the implementation body. +### โœ… Best Practice +```typescript +function format(input: string | number): string { + return String(input); +} +``` +### ๐Ÿš€ Solution +Prefer Union types when the implementation logic is identical for all types. Reserve overloads only for cases where the return type strictly depends on the input type and cannot be expressed via generics. +--- +## ๐ŸŽฏ 6. Global Scope Pollution (Legacy Namespaces) +> [!NOTE] +> **Context:** Organizing code in the ES Module era. +### โŒ Bad Practice +```typescript +namespace Utils { + export const log = (msg: string) => console.log(msg); +} +``` +### โš ๏ธ Problem +Namespaces are a legacy TypeScript feature. They don't play well with modern bundlers (Tree Shaking), are harder to test, and can lead to naming collisions in the global scope. +### โœ… Best Practice +```typescript +// utils.ts +export const log = (msg: string) => console.log(msg); +``` +### ๐Ÿš€ Solution +Use ES Modules (`export`/`import`). They are the industry standard, supported by all modern environments, and allow for better static analysis. +--- +## โšก 7. `enum` vs `const object` +> [!NOTE] +> **Context:** Grouping related constants. +### โŒ Bad Practice +```typescript +enum Status { + Active, + Inactive +} +``` +### โš ๏ธ Problem +Enums generate extra runtime code and have "reverse mapping" behavior that can lead to bugs (e.g., `Status[0]` returns "Active"). They also don't align with "TypeScript as a type-only layer." +### โœ… Best Practice +```typescript +const STATUS = { + ACTIVE: 'active', + INACTIVE: 'inactive' +} as const; +type Status = typeof STATUS[keyof typeof STATUS]; +``` +### ๐Ÿš€ Solution +Use `const` objects with `as const` and a derived union type. This is more predictable, emits cleaner code, and is easier to iterate over. +--- diff --git a/frontend/typescript/logic-safety.md b/frontend/typescript/logic-safety.md index b523c51..b93aec8 100644 --- a/frontend/typescript/logic-safety.md +++ b/frontend/typescript/logic-safety.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "5.5+" tags: [typescript, type-safety, best-practices, clean-code, scalable-code] ai_role: Senior TypeScript Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ›ก๏ธ TypeScript Logic & Safety Best Practices diff --git a/frontend/typescript/objects-functions.md b/frontend/typescript/objects-functions.md index 1beff2d..dc166e0 100644 --- a/frontend/typescript/objects-functions.md +++ b/frontend/typescript/objects-functions.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "5.5+" tags: [typescript, objects, functions, best-practices, clean-code, scalable-code] ai_role: Senior TypeScript Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿ“ฆ TypeScript Objects & Functions Best Practices diff --git a/frontend/typescript/professional-niche.md b/frontend/typescript/professional-niche.md index e2525f9..69a1a31 100644 --- a/frontend/typescript/professional-niche.md +++ b/frontend/typescript/professional-niche.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "5.5+" tags: [typescript, advanced, best-practices, clean-code, scalable-code] ai_role: Senior TypeScript Expert -last_updated: 2026-03-22 +last_updated: 2026-05-05 --- # ๐Ÿง  TypeScript Professional & Niche Best Practices diff --git a/frontend/typescript/readme.md b/frontend/typescript/readme.md index 415b8c4..61a871f 100644 --- a/frontend/typescript/readme.md +++ b/frontend/typescript/readme.md @@ -5,158 +5,14 @@ level: Senior/Architect version: 5.5+ tags: [typescript, type-safety, clean-code, best-practices, architecture] ai_role: Senior TypeScript Architecture Expert -last_updated: 2026-03-29 +last_updated: 2026-05-05 --- # ๐ŸŽจ TypeScript Best Practise ![TypeScript Logo](https://img.icons8.com/?size=100&id=uJM6fQYqDaZK&format=png&color=000000) ## ๐Ÿš€ I. Fundamentals (1-10) -## โšก 1. `any` vs `unknown` -> [!NOTE] -> **Context:** Handling data of an uncertain type. `any` disables all type-checking, while `unknown` forces safety. -### โŒ Bad Practice -```typescript -function process(data: unknown) { - console.log(data.name); // No error, but might crash at runtime -} -``` -### โš ๏ธ Problem -`any` is a "get out of jail free" card that propagates through the codebase, effectively turning off TypeScript's benefits and hiding potential runtime exceptions. -### โœ… Best Practice -```typescript -function process(data: unknown) { - if (data && typeof data === 'object' && 'name' in data) { - console.log((data as { name: string }).name); - } -} -``` -### ๐Ÿš€ Solution -Use `unknown` for values whose type is not yet determined. It requires a type check or assertion before usage, ensuring the developer acknowledges the data's structure. ---- -## โšก 2. `null` vs `undefined` in APIs -> [!NOTE] -> **Context:** Distinguishing between "value not provided" and "value is empty." -### โŒ Bad Practice -```typescript -interface UserResponse { - bio: string | null | undefined; -} -``` -### โš ๏ธ Problem -Using both creates ambiguity. In JSON, `undefined` properties are often stripped, while `null` is preserved. Mixing them increases complexity in conditional checks. -### โœ… Best Practice -```typescript -interface UserResponse { - bio?: string | null; // Optional if missing, null if explicitly empty -} -``` -### ๐Ÿš€ Solution -Standardize: use `undefined` (optional properties) for missing keys and `null` for intentional absence of value. Avoid using both for the same field unless strictly required by a legacy API. ---- -## โšก 3. `Array` vs `T[]` -> [!NOTE] -> **Context:** Visual consistency in array declarations. -### โŒ Bad Practice -```typescript -const users: Array = []; -const complex: Array = []; -``` -### โš ๏ธ Problem -`Array` is more verbose and can be confused with other generic types. It is harder to scan in complex signatures. -### โœ… Best Practice -```typescript -const users: User[] = []; -const complex: (string | number)[] = []; -``` -### ๐Ÿš€ Solution -Prefer the shorthand `T[]`. It is idiomatic, more readable, and clearly distinguishes arrays from other generic containers like `Record` or `Promise`. ---- -## โšก 4. `interface` vs `type` -> [!NOTE] -> **Context:** Defining object structures and aliases. -### โŒ Bad Practice -```typescript -type Point = { x: number; y: number; }; // Bad: Using type for object structure -interface Status { status: "active" | "inactive"; } // Bad: Trying to use interface for a union-like structure -``` -### โš ๏ธ Problem -Using `type` for object structures prevents declaration merging and reduces performance in TS compiler caching. Using `interface` for unions is impossible or leads to awkward wrapper objects. -### โœ… Best Practice -```typescript -interface Point { x: number; y: number; } -type Status = "active" | "inactive"; -``` -### ๐Ÿš€ Solution -> [!IMPORTANT] -> Prefer `interface` for structure, `type` for unions. Interfaces provide better error messages and performance for structural types in TypeScript 5.x. -> -> **Logical Conflict Resolution:** To enforce the repo standard, NEVER use `type` for defining object structures, and NEVER use `interface` for unions. ---- -## โšก 5. Function Overloads vs Union Types -> [!NOTE] -> **Context:** Handling functions with different input/output combinations. -### โŒ Bad Practice -```typescript -function format(input: string): string; -function format(input: number): string; -function format(input: unknown): string { - return String(input); -} -``` -### โš ๏ธ Problem -Overloads are verbose and can be harder to implement correctly. They often require `any` or complex type-casting in the implementation body. -### โœ… Best Practice -```typescript -function format(input: string | number): string { - return String(input); -} -``` -### ๐Ÿš€ Solution -Prefer Union types when the implementation logic is identical for all types. Reserve overloads only for cases where the return type strictly depends on the input type and cannot be expressed via generics. ---- -## ๐ŸŽฏ 6. Global Scope Pollution (Legacy Namespaces) -> [!NOTE] -> **Context:** Organizing code in the ES Module era. -### โŒ Bad Practice -```typescript -namespace Utils { - export const log = (msg: string) => console.log(msg); -} -``` -### โš ๏ธ Problem -Namespaces are a legacy TypeScript feature. They don't play well with modern bundlers (Tree Shaking), are harder to test, and can lead to naming collisions in the global scope. -### โœ… Best Practice -```typescript -// utils.ts -export const log = (msg: string) => console.log(msg); -``` -### ๐Ÿš€ Solution -Use ES Modules (`export`/`import`). They are the industry standard, supported by all modern environments, and allow for better static analysis. ---- -## โšก 7. `enum` vs `const object` -> [!NOTE] -> **Context:** Grouping related constants. -### โŒ Bad Practice -```typescript -enum Status { - Active, - Inactive -} -``` -### โš ๏ธ Problem -Enums generate extra runtime code and have "reverse mapping" behavior that can lead to bugs (e.g., `Status[0]` returns "Active"). They also don't align with "TypeScript as a type-only layer." -### โœ… Best Practice -```typescript -const STATUS = { - ACTIVE: 'active', - INACTIVE: 'inactive' -} as const; -type Status = typeof STATUS[keyof typeof STATUS]; -``` -### ๐Ÿš€ Solution -Use `const` objects with `as const` and a derived union type. This is more predictable, emits cleaner code, and is easier to iterate over. ---- +- [๐Ÿš€ Fundamentals](./fundamentals.md) Please refer to the specialized guides for detailed best practices: diff --git a/frontend/typescript/testing.md b/frontend/typescript/testing.md index b58b277..e044b06 100644 --- a/frontend/typescript/testing.md +++ b/frontend/typescript/testing.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "5.5+" tags: [typescript, testing, best-practices, clean-code, type-safety, vibe-coding] ai_role: Senior TypeScript Testing Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿงช TypeScript Testing Best Practices diff --git a/frontend/typescript/types-interfaces.md b/frontend/typescript/types-interfaces.md index d0bdb90..b04f5d1 100644 --- a/frontend/typescript/types-interfaces.md +++ b/frontend/typescript/types-interfaces.md @@ -5,7 +5,7 @@ level: Senior/Architect version: "5.5+" tags: [typescript, best-practices, clean-code, types] ai_role: Senior TypeScript Expert -last_updated: 2026-04-05 +last_updated: 2026-05-05 --- # ๐Ÿ“œ Types & Interfaces