---
name: TypeScript Best Practices
description: Idiomatic TypeScript patterns for clean, maintainable code.
metadata:
  labels: [typescript, best-practices, idioms, conventions]
  triggers:
    files: ['**/*.ts', '**/*.tsx']
    keywords: [class, function, module, import, export, async, promise]
---

# TypeScript Best Practices

## **Priority: P1 (OPERATIONAL)**

## Implementation Guidelines

- **Naming**: Classes/Types=`PascalCase`, vars/funcs=`camelCase`, consts=`UPPER_SNAKE`. Prefix `I` only if needed.
- **Functions**: Arrows for callbacks; regular for exports. Always type public API returns.
- **Modules**: Named exports only. Import order: external → internal → relative.
- **Async**: Use `async/await`, not raw Promises. `Promise.all()` for parallel.
- **Classes**: Explicit access modifiers. Favor composition. Use `readonly`.
- **Types**: Use `never` for exhaustiveness, `asserts` for runtime checks.
- **Optional**: Use `?:`, not `| undefined`.
- **Imports**: Use `import type` for tree-shaking.

## 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`**: NEVER use `any`. Force strict typing or use `unknown` with explicit casting.
- **Mocking Strategy**: In tests, use `jest.Mocked<T>` and cast values using `value as unknown as T` to satisfy strict linting without compromising type safety.
- **NO LINT DISABLE**: You are strictly PROHIBITED from using `eslint-disable` or `ts-ignore` comments. Fix underlying issues.

## Reference & Examples

See [references/examples.md](references/examples.md) for code samples including:

- Immutable Interfaces
- Exhaustiveness Checking
- Assertion Functions
- Dependency Injection Patterns
- Import Organization

## Related Topics

language | tooling | security