TypeScript Best Practices

Name: typescript-best-practices
Rating: 92
Author: VdustR

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

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

Quick Reference

interface vs type

Use	When
`interface`	Object structures, class contracts, extensible APIs
`type`	Union types, mapped types, conditional types, tuples

Naming Conventions

Element	Convention	Example
Interface/Type	PascalCase	`UserProfile`, `ResponseData`
Generic parameters	`T` prefix	`TUser`, `TConfig` (never bare `T`, `K`, `V`)
Acronyms	First cap only	`userId`, `ApiResponse` (NOT `userID`, `APIResponse`)
Constants	UPPER_SNAKE	`MAX_RETRY_COUNT`
Variables/Functions	camelCase	`getUserById`, `isActive`

Array Syntax

DO	DON'T
`Array<TItem>`	`TItem[]`
`ReadonlyArray<TItem>`	`readonly TItem[]`

Object Types

Use Case	DO	DON'T
Empty object	`Record<string, never>`	`{}`
Any object (extends)	`Record<string, any>`	`Record<string, unknown>`
Any object (annotation)	`Record<string, unknown>`	`Record<string, any>`
Non-primitive	`object`	`{}`

Assertions

DO	DON'T
Zod/arktype for runtime validation	`response as User`
`satisfies` for compile-time checks	`value as unknown as Type`
Type guards (`if ('prop' in obj)`)	`as any` to silence errors
Explicit null checks	`x!` non-null assertion

Function Declarations

typescript

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

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

Type Extraction

typescript

// DO: Extract from existing definitions
type OnClick = React.ComponentProps<'button'>['onClick'];
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