typescript

TypeScript Best Practices

Type System

• Prefer interfaces over types for object definitions
• Use type for unions, intersections, and mapped types
• NEVER use any or as any types or coercion
• Use strict TypeScript configuration
• Leverage TypeScript's built-in utility types
• Use generics for reusable type patterns
• Use unknown for variables that are not yet typed
• Use Zod for schema validation
• Use the type guards pattern for runtime type checking
• Use assertString for runtime string checking

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.ts file
• Co-locate component props with their components
• Prefer to use multiple files.
• Never place two classes or components in the same file.

Functions

• Use explicit return types for public functions
• Use arrow functions for callbacks and methods
• Use function overloads for complex type scenarios
• Prefer async/await over Promises
• Prefer function declarations over function expressions.
• Prefer functional programming over classes.

Best Practices

• Enable strict mode in tsconfig.json
• Use readonly for immutable properties
• Leverage discriminated unions for type safety
• Implement proper null checking

Imports

• ALWAYS use @/ style imports vs relative imports, except when importing from the same directory.
• NEVER do an inline await import(...) call.
• NEVER use 'UNKNOWN' or 'UNKNOWN_VALUE', or similar to indicate an unknown value - use null instead.

Error Handling

• DO NOT proactively add error handling