Version history: TypeScript
v1
scan: pass2026-08-11 — Ingested from sourceInitial version.
v2
currentscan: pass2026-11-02 — Currency pass 2026-11-01: dropped the generic Builder/Repository/Factory/Module/DI pattern block; softened the arrow-functions-for-methods rule; added satisfies, as const over enum, noUncheckedIndexedAccess, caught errors as unknown; frontmatter description unquoted and globs made valid YAML.---- description: "TypeScript coding standards and best practices for modern web development" - globs: **/*.ts, **/*.tsx, **/*.d.ts+ description: TypeScript coding standards for strict, type-safe application code. + globs: "**/*.{ts,tsx}" alwaysApply: false --- # 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+ - Prefer interfaces for object shapes that may be extended; use `type` for unions, intersections, and mapped types + - Avoid `any`; use `unknown` for values of unknown shape and narrow before use + - Enable `strict` (and consider `noUncheckedIndexedAccess`) in `tsconfig.json` + - Leverage built-in utility types (`Partial`, `Pick`, `Omit`, `Record`, `ReturnType`) + - Use generics for reusable type patterns; keep type parameters minimal and constrained + - Use `satisfies` to check an object against a type without widening it + - Prefer `as const` (or `const` type parameters) over `enum` for fixed sets of values ## 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)+ - Use UPPER_CASE for module-level constants + - Use descriptive names with auxiliary verbs (e.g., `isLoading`, `hasError`) + - Suffix React prop interfaces 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+ - Export shared types from dedicated type files + - Use barrel exports (`index.ts`) sparingly; they can hurt tree-shaking and create import cycles - 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+ - Use explicit return types for exported functions + - Use arrow functions for callbacks; use regular methods on classes unless you need lexical `this` + - Use function overloads only when a union or generic cannot express the signature + - Prefer `async`/`await` over raw Promise chains ## 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+ - Use `readonly` for properties that should not change after construction + - Model state with discriminated unions instead of optional flags + - Use type guards (`x is T`) for runtime narrowing + - Handle `null` and `undefined` explicitly; do not use the non-null assertion `!` to silence the compiler + - Avoid type assertions (`as`) unless you have verified the value at runtime ## 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+ - Create custom error classes for domain-specific errors + - Use `Result` types (`{ ok: true, value } | { ok: false, error }`) for expected failures + - Treat caught errors as `unknown` and narrow before use + - Handle Promise rejections; never leave a floating promise ## 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+ - Reach for plain functions and modules first; add classes or dependency injection only when the code needs them