typescript-dev

name	typescript-dev
description	TypeScript development best practices, code quality tools, and documentation templates. Activated when working with .ts, .tsx files or TypeScript projects.
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)

🛠️ Code Quality Tools

Development Workflow

# Format code
pnpm run format

# Run linter
pnpm run lint

# Type check
pnpm tsc --noEmit

# Run tests with coverage
pnpm test -- --coverage

📚 Documentation Template

Function Documentation (JSDoc)

/**
 * Brief description of what the function does
 *
 * @description Detailed explanation of the business logic and purpose
 * @param paramName - What this parameter represents
 * @returns What the function returns and why
 * @throws {ErrorType} When this error occurs
 * @example
 * ```typescript
 * // Example usage
 * const result = functionName({ key: 'value' });
 * console.log(result); // Expected output
 * ```
 * @see {@link RelatedFunction} For related functionality
 * @since 1.0.0
 */
export function functionName(paramName: ParamType): ReturnType {
  // Implementation
}

Interface Documentation

/**
 * Interface description
 * @interface
 */
export interface UserProfile {
  /** Unique user identifier */
  id: string;

  /** Username (3-20 characters) */
  username: string;

  /** Email address (verified) */
  email: string;

  /** Profile creation timestamp */
  createdAt: Date;
}

Type Alias Documentation

/**
 * Type representing user roles
 * @typedef {('admin' | 'user' | 'guest')} UserRole
 */
export type UserRole = 'admin' | 'user' | 'guest';

🎯 Quality Checklist

Check these during code review:

• All public functions have JSDoc comments
• 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

// 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

// 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

// 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

   import type { UserProfile } from './types';
   

🔍 Common Anti-patterns to Avoid

❌ Don't:

// Using any type
function process(data: any) { }

// Implicit any
function getValue(obj, key) { }

// Excessive type assertions
const user = data as User;

✅ Do:

// 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
}