flatbread / rules

---
description: typescript, .tsx
alwaysApply: false
---

# TypeScript Best Practices

## Type Definitions

- Do not ever use `any`. Ever. If you feel like you have to use `any`, use `unknown` instead.
- Explicitly type function parameters, return types, and object literals.
- Use `readonly` modifiers for immutable properties and arrays
- Leverage the built-in utility types
- Use discriminated unions with exhaustiveness checking for type narrowing
- Implement proper generics with appropriate constraints
- Use mapped types, template literal types, and conditional types to reduce duplication
- Leverage `satisfies` and `const` assertions for literal types
- Implement branded/nominal types for type-level validation

## Code Organization

- Document complex types with JSDoc comments in plain english

## When encountering TS errors

- Never use `// @ts-ignore` or `// @ts-expect-error` without explanatory comments
- Use `--noEmitOnError` compiler flag to prevent generating JS files when TypeScript errors exist