---

description: globs: alwaysApply: true

---

description: TypeScript coding standards and best practices for modern web development globs: **/.ts, **/.tsx, **/*.d.ts

TypeScript Best Practices

Type System

• Prefer interfaces over types for object definitions
• Use type for unions, intersections, and mapped types
• Avoid using any, prefer unknown for unknown types
• Use strict TypeScript configuration
• Leverage TypeScript's built-in utility types
• Use generics for reusable type patterns

Naming Conventions

• Use PascalCase for type names and interfaces
• Use camelCase for variables and functions
• Use UPPER_CASE for constants
• Use descriptive names with auxiliary verbs (e.g., isLoading, hasError)
• Prefix interfaces for React props with 'Props' (e.g., ButtonProps)

Code Organization

• Keep type definitions close to where they're used
• Export types and interfaces from dedicated type files when shared
• Use barrel exports (index.ts) for organizing exports
• Place shared types in a types directory
• Co-locate component props with their components

Functions

• Use explicit return types for public functions
• Use arrow functions for callbacks and methods
• Implement proper error handling with custom error types
• Use function overloads for complex type scenarios
• Prefer async/await over Promises

Best Practices

• Enable strict mode in tsconfig.json
• Use readonly for immutable properties
• Leverage discriminated unions for type safety
• Use type guards for runtime type checking
• Implement proper null checking
• Avoid type assertions unless necessary

Error Handling

• Create custom error types for domain-specific errors
• Use Result types for operations that can fail
• Implement proper error boundaries
• Use try-catch blocks with typed catch clauses
• Handle Promise rejections properly

Patterns

• Use the Builder pattern for complex object creation
• Implement the Repository pattern for data access
• Use the Factory pattern for object creation
• Leverage dependency injection
• Use the Module pattern for encapsulation

Module Imports

• Always use namespace imports (import * as name from '...'). This style ensures that the origin of any imported symbol is always explicit (e.g., types.Comment instead of just Comment), which improves code clarity and prevents naming conflicts. This aligns with standard practices in Go.
• Existing code using named imports (import { ... } from '...') must be refactored to use namespace imports upon discovery.