---

name: typescript-best-practices description: This skill should be used when the user asks to "review TypeScript code", "check my TS code", "review this TypeScript", "write TypeScript", or when writing, reviewing, or refactoring TypeScript code in projects with tsconfig.json or .ts/.tsx files. Provides dos and don'ts for type design, naming conventions, generics, and patterns.

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

Copy// 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

Copy// 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