domains / software-engineering / typescript-coding-guidelines / typescript

typescript

Skill card

combined

The two skills cover overlapping ground (TypeScript best practices, async handling, type safety) but have distinct focuses and conflicting advice. The first skill (sickn33) is a 'super-code' efficiency reference focused on idiomatic refactoring (e.g., preferring `type` for unions, avoiding explicit return types when obvious). The second skill (LeoYeAI) is a comprehensive style guide covering naming, file structure, and specific conventions (e.g., preferring `interface` for object shapes, requiring explicit return types for public APIs). Because they disagree on specific conventions (like `type` vs `interface` preference and return type annotation), crowning one would hide the other's valid alternative approach.

Repositories

Other copies

Combined skill

---
name: typescript
description: "Comprehensive TypeScript coding guidelines combining idiomatic efficiency and strict style conventions."
---

# TypeScript Coding Guidelines

## 1. General Principles
- **Strict Mode**: Always enable `"strict": true` in `tsconfig.json`.
- **Immutability**: Use `const` by default; prefer `readonly` properties.
- **Type Safety**: Minimize `any`. Use `unknown` with type guards or generics.
- **Readability**: Prefer explicit, self-documenting code over clever one-liners.

## 2. Naming Conventions
- **Variables/Functions**: `camelCase` (e.g., `getUserName`).
- **Booleans**: Prefix with `is`, `has`, `can` (e.g., `isLoading`).
- **Constants**: `UPPER_SNAKE_CASE` for module-level, `camelCase` for local.
- **Classes/Interfaces/Types**: `PascalCase` (e.g., `UserService`).
- **Files**: `kebab-case.ts` for modules, `PascalCase.tsx` for React components.
- **No `I` Prefix**: Do not prefix interfaces with `I` (use `User`, not `IUser`).

## 3. Types & Interfaces
- **Object Shapes**: Prefer `interface` for extensible object shapes and class-like structures.
- **Unions/Intersections**: Use `type` for unions, intersections, and mapped types.
- **Return Types**: Annotate return types explicitly for public APIs; let TS infer for simple local functions.
- **Utility Types**: Use `Partial<T>`, `Pick<T, K>`, `Omit<T, K>` to derive types.

## 4. Idiomatic Efficiency (Super-Code)
- **Array Operations**: Use `.filter()`, `.map()`, `.reduce()` instead of imperative loops.
  ```ts
  // ✅
  const result = items.filter(i => i.active).map(i => i.name.toUpperCase())
  ```
- **Destructuring**: Use object/array destructuring for extraction and omission.
  ```ts
  // ✅ Omit key
  const { password, ...safe } = obj
  ```
- **Async**: Use `Promise.all` for independent parallel operations.
  ```ts
  // ✅
  const [user, config] = await Promise.all([fetchUser(id), fetchConfig()])
  ```
- **Null Safety**: Use optional chaining (`?.`) and nullish coalescing (`??`).

## 5. React Specifics (if applicable)
- **Derived State**: Compute during render, do not use `useEffect` for simple derivations.
- **Keys**: Use stable IDs (`item.id`), not array indices, for list keys.
- **Memoization**: Use `useMemo`/`useCallback` only when necessary (e.g., for memoized children or effect deps).

## 6. Anti-patterns
- Avoid `var`.
- Avoid `for...in` on arrays; use `for...of` or array methods.
- Avoid `as` assertions to silence errors; use type guards instead.
- Avoid `== null` (loose); use `=== null` or `??`.