| 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:
