# Typescript Coding Standards

> Invoke when code-developer or quality-reviewer works on TypeScript files. Provides strict typing rules, union/intersection type patterns, generic constraints, utility type usage, and a PostToolUse hook that validates TypeScript file edits.

- Skill: `masanao-ohba/typescript-coding-standards` (Agent Skill)
- Install (CLI): `npx skillmds@latest add masanao-ohba/typescript-coding-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masanao-ohba/typescript-coding-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: masanao-ohba (https://skillmd.com/u/masanao-ohba)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/masanao-ohba/typescript-coding-standards

---


# 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