---

name: typescript-best-practices description: Write idiomatic TypeScript patterns for clean, maintainable code. Use when writing or refactoring TypeScript classes, functions, modules, or async logic. metadata: triggers: files: - '/*.ts' - '/*.tsx' keywords: - class - function - module - import - export - async - promise

TypeScript Best Practices

Priority: P1 (HIGH)

Implementation Guidelines

• Naming: Use PascalCase for Classes/Types/Interfaces, camelCase for variables/functions, and UPPER_SNAKE for static constants.
• Functions: Use arrow functions for callbacks/logic; function declaration for top-level exports. Always type public API returns.
• Modules: Use Named exports ONLY to enable better refactoring/auto-imports.
• Async: Use async/await with Promise.all() for parallel execution. Implement try-catch for error handling; type catch(e) as unknown and narrow before use. Avoid .then().catch() chains.
• Classes: Explicitly use private, protected, and public modifiers. Favor composition over inheritance and dependency injection with constructor injection and interfaces over singletons for testability.
• Type Safety: Use never for exhaustiveness checks in switch-cases.
• Optional: Use optional chaining (?.) and nullish coalescing (??) over manual checks.
• Imports: Enforce external packages → internal modules → relative imports order automatically via eslint-plugin-import. Use import type for interfaces/types to ensure better tree-shaking and zero runtime overhead.
• Validation: Use Zod or Tsoa for runtime boundary validation.

Anti-Patterns

• No Default Exports: Use named exports.
• No Implicit Returns: Specify return types.
• No Unused Variables: Enable noUnusedLocals.
• No require: Use ES6 import.
• No Empty Interfaces: Use type or non-empty interface.
• No any: Use unknown or specific type.
• No Unsafe Mocks: Cast with jest.Mocked<T> or as unknown as T.
• No eslint-disable: Fix root cause; never suppress warnings.

References

See references/examples.md for Immutable Interfaces, Exhaustiveness Checking, Assertion Functions, DI Patterns, and Import Organization.

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• async/await
• injection