# Typescript

> TypeScript coding conventions, best practices, and patterns for writing clean, maintainable code.

- Skill: `genkit-ai/typescript` (Agent Skill)
- Install (CLI): `npx skillmds@latest add genkit-ai/typescript`
- Raw SKILL.md: https://api.skillmd.com/api/skills/genkit-ai/typescript/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: genkit-ai (https://skillmd.com/u/genkit-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/genkit-ai/typescript

---


# TypeScript Coding Conventions

## General Principles

- Use **TypeScript strict mode** (`"strict": true` in tsconfig.json).
- Prefer `const` over `let`; never use `var`.
- Use explicit return types on exported functions.
- Prefer interfaces over type aliases for object shapes.
- Use `unknown` instead of `any` where possible.

## Naming Conventions

- **Variables & functions**: `camelCase`
- **Classes & interfaces**: `PascalCase`
- **Constants**: `UPPER_SNAKE_CASE` for true constants, `camelCase` for derived values
- **Files**: `kebab-case.ts`
- **Type parameters**: Single uppercase letter (`T`, `K`, `V`) or descriptive (`TResult`)

## File Structure

```
src/
  index.ts          # Entry point, exports
  types.ts          # Shared type definitions
  utils/            # Utility functions
  services/         # Business logic
  middleware/       # Express/framework middleware
```

## Error Handling

- Use typed errors (extend `Error` class).
- Always handle promise rejections.
- Prefer `try/catch` with specific error types over generic catches.

```typescript
class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500
  ) {
    super(message);
    this.name = 'AppError';
  }
}
```

## Async Patterns

- Use `async/await` over raw promises.
- Use `Promise.all()` for concurrent independent operations.
- Avoid mixing callbacks and promises.

## Imports

- Use named imports: `import { thing } from './module'`
- Group imports: external packages first, then internal modules.
- Use `.js` extensions in import paths for ESM compatibility.

## Code Style

- Maximum line length: 100 characters.
- Use template literals for string interpolation.
- Prefer `Array.map/filter/reduce` over `for` loops for transformations.
- Use optional chaining (`?.`) and nullish coalescing (`??`).
- Destructure objects and arrays when accessing multiple properties.

## Testing

- Co-locate test files: `thing.ts` → `thing.test.ts`
- Use descriptive test names: `it('should return empty array when no items match')`
- Test edge cases: empty inputs, null values, error conditions.