Typescript Best Practices

TypeScript Best Practices

Guidelines for writing clean, type-safe, and maintainable TypeScript code.

Note: If the repository has established code style conventions, follow those first. These guidelines serve as defaults.

Core Principles

1. Type-First Design - Define types before implementation; minimize reliance on inference
2. Interface for Structure - Use interface for objects, type for unions/mapped/conditional
3. Namespace for Type Organization - Group related types with namespaces (types only, not runtime)
4. Generic Const for Strictness - Use <const TConfig> for strict literal inference
5. Extract, Don't Redefine - Get types from existing definitions instead of duplicating
6. Strictest Config - Use strictest tsconfig base; install ts-reset for saner built-in types

Quick Reference

interface vs type

Naming Conventions

Array Syntax

Object Types

Assertions

Function Declarations

// DO: Type on the const
const myFunction: myFunction.Type = (options) => {
  // implementation
};

// DO: satisfies when namespace doesn't exist
const => {
  // implementation
}) satisfies React.ComponentProps<'button'>['onClick'];

Type Extraction

// DO: Extract from existing definitions
type
type ItemIds = Array<Item['id']>;
type TimeoutType = NonNullable<typeof config['timeout']>;

// DON'T: Manually redefine types
type BadItemIds = Array<number>; // Won't update if Item.id changes

Summary Checklist

Before committing TypeScript code, verify:

• Used interface for object types, type for unions/mapped/conditional
• No as or ! assertions — use Zod, satisfies, type guards, or explicit null checks
• Branded types use Zod .brand() or type-fest Tagged (not manual casting)
• Naming follows conventions (PascalCase types, T prefix for generics, Id not ID)
• Types extracted from existing definitions where possible
• Functions use namespace pattern for complex type organization
• Arrow functions for const declarations
• Complex generics have type tests

Reference Files

For detailed patterns and examples, see:

• type-patterns.md - Type syntax, assertions, namespace pattern, generics
• code-style.md - Safe array access, early return, avoid destructuring, avoid enum
• union-exhaustive.md - Discriminated unions + exhaustive handling (e.g., for state, events, API responses)
• branded-types.md - Nominal types for ID/unit safety (e.g., UserId vs OrderId)
• template-literals.md - String pattern types (e.g., event names, CSS values, route parameters)
• type-testing.md - Type-level testing with *.test-d.ts files
• setup.md - tsconfig, strict options, ts-reset configuration

Notes

• These guidelines complement, not replace, project-specific conventions
• When in doubt, prioritize readability and maintainability
• Runtime type validation (zod, arktype) is recommended for external data
• Avoid over-engineering types; simple is better than clever