---
name: typescript-dev
description: >-
TypeScript development best practices, code quality tools, and documentation conventions.
Use when writing, editing, or reviewing .ts or .tsx files, when setting up a TypeScript project,
when the user asks about TypeScript patterns/conventions, or when type safety guidance is needed.
user-invocable: false
allowed-tools: ['Read', 'Glob', 'Grep', 'Bash']
---
# TypeScript Development Expert
This skill supports TypeScript project development.
## 🎯 Core Rules
### Package Management
- **Required**: Use `pnpm` as package manager
- Do not use `npm` or `yarn`
### Type Safety
- **tsconfig.json**: `strict: true` required
- **Null Handling**: Leverage optional chaining `?.` and nullish coalescing `??`
- **Imports**: Use ES modules, avoid `require()`
- **NO ANY**: Do not use `any` type in production code
### Best Practices
- **Type Inference**: Let TypeScript infer when obvious
- **Generics**: Use for reusable components
- **Union Types**: Prefer union types over enums for string literals
- **Utility Types**: Leverage built-in types (Partial, Pick, Omit)
### Documentation
- **Required**: Use TSDoc format for documentation comments
- **Public APIs only**: Document exported functions, classes, and interfaces
- **Self-documenting code**: Prefer clear naming over excessive comments
- **Document when necessary**: Add TSDoc only when the code intent isn't obvious from the signature
## 🛠 Code Quality Tools
### Development Workflow
```bash
# Format code
pnpm run format
# Run linter
pnpm run lint
# Type check
pnpm tsc --noEmit
# Run tests with coverage
pnpm test -- --coverage
```
## 🎯 Quality Checklist
Check these during code review:
- [ ] Public APIs have TSDoc comments (when intent isn't clear from signature)
- [ ] No `any` type usage
- [ ] Proper error handling
- [ ] Test coverage above 80%
- [ ] Type inference properly leveraged
- [ ] Utility Types utilized
- [ ] Optional chaining (`?.`) and Nullish coalescing (`??`) used
- [ ] ES modules used (avoid `require()`)
## 🚀 Common Patterns
### Error Handling
```typescript
// Good: Clear error types
class ValidationError extends Error {
constructor(message: string, public field: string) {
super(message);
this.name = 'ValidationError';
}
}
// Good: Result type pattern
type Result<T, E = Error> =
| { success: true; data: T }
| { success: false; error: E };
```
### Async/Await
```typescript
// Good: With error handling
async function fetchUserData(id: string): Promise<Result<UserData>> {
try {
const response = await fetch(`/api/users/${id}`);
const data = await response.json();
return { success: true, data };
} catch (error) {
return { success: false, error: error as Error };
}
}
```
### Type Guards
```typescript
// Good: Custom type guard
function isUserProfile(value: unknown): value is UserProfile {
return (
typeof value === 'object' &&
value !== null &&
'id' in value &&
'username' in value
);
}
```
## 💡 Performance Tips
1. **Avoid unnecessary re-renders** (React)
- Use `React.memo` for expensive components
- Use `useMemo` / `useCallback` appropriately
2. **Lazy Loading**
- Dynamic imports for code splitting
- `React.lazy()` for components
3. **Type-only imports**
```typescript
import type { UserProfile } from './types';
```
## 🔍 Common Anti-patterns to Avoid
❌ **Don't**:
```typescript
// Using any type
function process(data: any) { }
// Implicit any
function getValue(obj, key) { }
// Excessive type assertions
const user = data as User;
```
✅ **Do**:
```typescript
// Proper type definitions
function process(data: UserData) { }
// Explicit types
function getValue<T>(obj: T, key: keyof T) { }
// Use type guards
if (isUser(data)) {
// data is User here
}
```
