TypeScript Coding Standards

Principles

Type Safety

• Enable strict mode in tsconfig.json

• Avoid 'any' type - use 'unknown' when type is truly uncertain

• Use const assertions for literal types (as const)

• Prefer type inference over explicit types when obvious

• Use discriminated unions for complex state modeling

Naming Conventions

• Use PascalCase for types, interfaces, and classes

• Use camelCase for variables, functions, and properties

• Use UPPER_SNAKE_CASE for constants

• Prefix interfaces with 'I' only when necessary to avoid conflicts

• Use descriptive names that reveal intent

Type Definitions

• Prefer interfaces for object types (extensible)

• Use type aliases for unions, intersections, and utilities

• Define types close to where they're used

• Export types from index files for library modules

• Use utility types (Partial, Pick, Omit, Record, etc.)

Function Signatures

• Always specify return types for public functions

• Use optional parameters with default values sparingly

• Prefer function overloads for complex signatures

• Use generics for reusable, type-safe functions

Error Handling

• Use typed errors with discriminated unions

• Prefer Result<T, E> pattern over throwing exceptions

• Document thrown exceptions in JSDoc comments

• Handle all error cases explicitly

Best Practices

Imports

• Use path aliases for cleaner imports (@/ prefix)

• Group imports: external -> internal -> relative

• Use named imports over default imports when possible

• Avoid circular dependencies

Code Organization

• One component/class per file (exceptions for small helpers)

• Co-locate related files (component + styles + tests)

• Use index files for barrel exports

• Keep files under 300 lines when possible

Documentation

• Use JSDoc comments for public APIs

• Document complex type definitions

• Explain non-obvious type assertions

• Keep comments up-to-date with code changes

Anti-Patterns

Avoid

• Type assertions (as Type) without justification

• Non-null assertions (!) without null checks

• Empty interfaces extending other types

• Excessive use of Pick/Omit (indicates poor type design)

• Magic numbers - use named constants

• Mutating function parameters

Code Quality

Linting

• Configure ESLint with TypeScript plugin

• Enable recommended TypeScript rules

• Use Prettier for consistent formatting

• Fix all linting errors before commit

Testing

• Type test critical type utilities

• Test type narrowing logic

• Verify discriminated unions exhaustiveness