TypeScript Coder Skill

Master TypeScript development with expert-level knowledge of type systems, migration strategies, and modern JavaScript/TypeScript patterns. This skill transforms you into a 10x engineer capable of writing type-safe, maintainable code and migrating existing JavaScript projects to TypeScript with confidence.

When to Use This Skill

• User asks to "add TypeScript", "migrate to TypeScript", or "convert to TypeScript"
• Need to "add type checking" or "fix TypeScript errors" in a project
• Creating or configuring tsconfig.json for a project
• Working with .ts, .tsx, .mts, or .d.ts files
• Adding JSDoc type annotations to JavaScript files
• Debugging type errors or improving type safety
• Setting up TypeScript in a Node.js or JavaScript project
• Creating type definitions or ambient declarations
• Implementing advanced TypeScript patterns (generics, conditional types, mapped types)

Prerequisites

• Basic understanding of JavaScript (ES6+)
• Node.js and npm/yarn installed (for TypeScript compilation)
• Familiarity with the project structure and build tools
• Access to the typescript package (can be installed if needed)

Shorthand Keywords

Keywords to trigger this skill as if using a command-line tool:

openPrompt = ["typescript-coder", "ts-coder"]

Use these shorthand commands to quickly invoke TypeScript expertise without lengthy explanations. For example:

• typescript-coder --check "this code"
• typescript-coder check this type guard
• ts-coder migrate this file
• ts-coder --migrate project-to-typescript

Role and Expertise

As a TypeScript expert, you operate with:

• Deep Type System Knowledge: Understanding of TypeScript's structural type system, generics, and advanced types
• Migration Expertise: Proven strategies for incremental JavaScript to TypeScript migration
• Best Practices: Knowledge of TypeScript patterns, conventions, and anti-patterns
• Tooling Mastery: Configuration of TypeScript compiler, build tools, and IDE integration
• Problem Solving: Ability to resolve complex type errors and design type-safe architectures

Core TypeScript Concepts

The TypeScript Type System

TypeScript uses structural typing (duck typing) rather than nominal typing:

interface Point {
  x: number;
  y: number;
}

// This works because the object has the right structure
const point: Point = { x: 10, y: 20 };

// This also works - structural compatibility
const point3D = { x: 1, y: 2, z: 3 };
const point2D: Point = point3D;  // OK - has x and y

Type Inference

TypeScript infers types when possible, reducing boilerplate:

// Type inferred as string
const message = "Hello, TypeScript!";

// Type inferred as number
const count = 42;

// Type inferred as string[]
const names = ["Alice", "Bob", "Charlie"];

// Return type inferred as number
function add(a: number, b: number) {
  return a + b;  // Returns number
}

Key TypeScript Features

Step-by-Step Workflows

Task 1: Install and Configure TypeScript

For a new or existing JavaScript project:

1. Install TypeScript as a dev dependency:

   npm install --save-dev typescript
   

2. Install type definitions for Node.js (if using Node.js):

   npm install --save-dev @types/node
   

3. Initialize TypeScript configuration:

   npx tsc --init
   

4. Configure tsconfig.json for your project:

   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "commonjs",
       "lib": ["ES2020"],
       "outDir": "./dist",
       "rootDir": "./src",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
       "forceConsistentCasingInFileNames": true,
       "resolveJsonModule": true,
       "declaration": true,
       "declarationMap": true,
       "sourceMap": true
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules", "dist"]
   }
   

5. Add build script to package.json:

   {
     "scripts": {
       "build": "tsc",
       "dev": "tsc --watch",
       "check": "tsc --noEmit"
     }
   }
   

Task 2: Migrate JavaScript to TypeScript (Incremental Approach)

Safe, incremental migration strategy:

1. Enable TypeScript to process JavaScript files:

   {
     "compilerOptions": {
       "allowJs": true,
       "checkJs": false,
       "noEmit": true
     }
   }
   

2. Add JSDoc type annotations to JavaScript files (optional intermediate step):

   // @ts-check
   
   /**
    * Calculates the sum of two numbers
    * @param {number} a - First number
    * @param {number} b - Second number
    * @returns {number} The sum
    */
   function add(a, b) {
     return a + b;
   }
   
   /** @type {string[]} */
   const names = ["Alice", "Bob"];
   
   /** @typedef {{ id: number, name: string, email?: string }} User */
   
   /** @type {User} */
   const user = {
     id: 1,
     name: "Alice"
   };
   

3. Rename files incrementally from .js to .ts:

   # Start with utility files and leaf modules
   mv src/utils/helpers.js src/utils/helpers.ts
   

4. Fix TypeScript errors in converted files:

   • Add explicit type annotations where inference fails
   • Define interfaces for complex objects
   • Handle any types appropriately
   • Add type guards for runtime checks

5. Gradually convert remaining files:

   • Start with utilities and shared modules
   • Move to leaf components (no dependencies)
   • Finally convert orchestration/entry files

6. Enable strict mode progressively:

   {
     "compilerOptions": {
       "strict": false,
       "noImplicitAny": true,
       "strictNullChecks": true
       // Enable other strict flags one at a time
     }
   }
   

Task 3: Define Types and Interfaces

Creating robust type definitions:

1. Define interfaces for data structures:

   // User data model
   interface User {
     id: number;
     name: string;
     email: string;
     age?: number;  // Optional property
     readonly createdAt: Date;  // Read-only property
   }
   
   // API response structure
   interface ApiResponse<T> {
     success: boolean;
     data?: T;
     error?: {
       code: string;
       message: string;
     };
   }
   

2. Use type aliases for complex types:

   // Union type
   type Status = 'pending' | 'active' | 'completed' | 'failed';
   
   // Intersection type
   type Employee = User & {
     employeeId: string;
     department: string;
     salary: number;
   };
   
   // Function type
   type TransformFn<T, U> = (input: T) => U;
   
   // Conditional type
   type NonNullable<T> = T extends null | undefined ? never : T;
   

3. Create type definitions in .d.ts files for external modules:

   // types/custom-module.d.ts
   declare module 'custom-module' {
     export interface Config {
       apiKey: string;
       timeout?: number;
     }
   
     export function initialize(config: Config): Promise<void>;
     export function fetchData<T>(endpoint: string): Promise<T>;
   }
   

Task 4: Work with Generics

Type-safe reusable components:

1. Generic functions:

   // Basic generic function
   function identity<T>(value: T): T {
     return value;
   }
   
   const num = identity(42);        // Type: number
   const str = identity("hello");   // Type: string
   
   // Generic with constraints
   function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
     return obj[key];
   }
   
   const user = { name: "Alice", age: 30 };
   const name = getProperty(user, "name");  // Type: string
   const age = getProperty(user, "age");    // Type: number
   

2. Generic classes:

   class DataStore<T> {
     private items: T[] = [];
   
     add(item: T): void {
       this.items.push(item);
     }
   
     get(index: number): T | undefined {
       return this.items[index];
     }
   
     filter(predicate: (item: T) => boolean): T[] {
       return this.items.filter(predicate);
     }
   }
   
   const numberStore = new DataStore<number>();
   numberStore.add(42);
   
   const userStore = new DataStore<User>();
   userStore.add({ id: 1, name: "Alice", email: "alice@example.com" });
   

3. Generic interfaces:

   interface Repository<T> {
     findById(id: string): Promise<T | null>;
     findAll(): Promise<T[]>;
     create(item: Omit<T, 'id'>): Promise<T>;
     update(id: string, item: Partial<T>): Promise<T>;
     delete(id: string): Promise<boolean>;
   }
   
   class UserRepository implements Repository<User> {
     async findById(id: string): Promise<User | null> {
       // Implementation
       return null;
     }
     // ... other methods
   }
   

Task 5: Handle Type Errors

Common type errors and solutions:

1. "Property does not exist" errors:

   // ❌ Error: Property 'name' does not exist on type '{}'
   const user = {};
   user.name = "Alice";
   
   // ✅ Solution 1: Define interface
   interface User {
     name: string;
   }
   const user: User = { name: "Alice" };
   
   // ✅ Solution 2: Type assertion (use cautiously)
   const user = {} as User;
   user.name = "Alice";
   
   // ✅ Solution 3: Index signature
   interface DynamicObject {
     [key: string]: any;
   }
   const user: DynamicObject = {};
   user.name = "Alice";
   

2. "Cannot find name" errors:

   // ❌ Error: Cannot find name 'process'
   const env = process.env.NODE_ENV;
   
   // ✅ Solution: Install type definitions
   // npm install --save-dev @types/node
   const env = process.env.NODE_ENV;  // Now works
   

3. any type issues:

   // ❌ Implicit any (with noImplicitAny: true)
   function process(data) {
     return data.value;
   }
   
   // ✅ Solution: Add explicit types
   function process(data: { value: number }): number {
     return data.value;
   }
   
   // ✅ Or use generic
   function process<T>(data: T): T {
     return data;
   }
   

4. Union type narrowing:

   function processValue(value: string | number) {
     // ❌ Error: Property 'toUpperCase' does not exist on type 'string | number'
     return value.toUpperCase();
   
     // ✅ Solution: Type guard
     if (typeof value === "string") {
       return value.toUpperCase();  // TypeScript knows it's string here
     }
     return value.toString();
   }
   

Task 6: Configure for Specific Environments

Environment-specific configurations:

Node.js Project

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "types": ["node"],
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Browser/DOM Project

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "esnext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "noEmit": true
  }
}

Library/Package

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "esnext",
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

TypeScript Best Practices

Do's

• ✅ Enable strict mode ("strict": true) for maximum type safety
• ✅ Use type inference - let TypeScript infer types when it's obvious
• ✅ Prefer interfaces over type aliases for object shapes (better error messages)
• ✅ Use unknown instead of any - forces type checking before use
• ✅ Create utility types for common transformations
• ✅ Use const assertions (as const) for literal types
• ✅ Leverage type guards for runtime type checking
• ✅ Document complex types with JSDoc comments
• ✅ Use discriminated unions for type-safe state management
• ✅ Keep types DRY - extract and reuse type definitions

Don'ts

• ❌ Don't use any everywhere - defeats the purpose of TypeScript
• ❌ Don't ignore TypeScript errors with @ts-ignore without good reason
• ❌ Don't over-complicate types - balance safety with readability
• ❌ Don't use type assertions excessively - indicates design issues
• ❌ Don't duplicate type definitions - use shared types
• ❌ Don't forget null/undefined checks - enable strictNullChecks
• ❌ Don't use enums for everything - consider union types instead
• ❌ Don't skip type definitions for external libraries - install @types/*
• ❌ Don't disable strict flags without justification
• ❌ Don't mix JavaScript and TypeScript in production - complete the migration

Common Patterns

Pattern 1: Discriminated Unions

Type-safe state management:

type LoadingState = { status: 'loading' };
type SuccessState<T> = { status: 'success'; data: T };
type ErrorState = { status: 'error'; error: Error };

type AsyncState<T> = LoadingState | SuccessState<T> | ErrorState;

function handleState<T>(state: AsyncState<T>) {
  switch (state.status) {
    case 'loading':
      console.log('Loading...');
      break;
    case 'success':
      console.log('Data:', state.data);  // TypeScript knows state.data exists
      break;
    case 'error':
      console.log('Error:', state.error.message);  // TypeScript knows state.error exists
      break;
  }
}

Pattern 2: Builder Pattern

Type-safe fluent API:

class QueryBuilder<T> {
  private filters: Array<(item: T) => boolean> = [];
  private sortFn?: (a: T, b: T) => number;
  private limitCount?: number;

  where(predicate: (item: T) => boolean): this {
    this.filters.push(predicate);
    return this;
  }

  sortBy(compareFn: (a: T, b: T) => number): this {
    this.sortFn = compareFn;
    return this;
  }

  limit(count: number): this {
    this.limitCount = count;
    return this;
  }

  execute(data: T[]): T[] {
    let result = data.filter(item =>
      this.filters.every(filter => filter(item))
    );

    if (this.sortFn) {
      result = result.sort(this.sortFn);
    }

    if (this.limitCount) {
      result = result.slice(0, this.limitCount);
    }

    return result;
  }
}

// Usage
const users = [/* ... */];
const result = new QueryBuilder<User>()
  .where(u => u.age > 18)
  .where(u => u.email.includes('@example.com'))
  .sortBy((a, b) => a.name.localeCompare(b.name))
  .limit(10)
  .execute(users);

Pattern 3: Type-Safe Event Emitter

type EventMap = {
  'user:created': { id: string; name: string };
  'user:updated': { id: string; changes: Partial<User> };
  'user:deleted': { id: string };
};

class TypedEventEmitter<T extends Record<string, any>> {
  private listeners: { [K in keyof T]?: Array<(data: T[K]) => void> } = {};

  on<K extends keyof T>(event: K, listener: (data: T[K]) => void): void {
    if (!this.listeners[event]) {
      this.listeners[event] = [];
    }
    this.listeners[event]!.push(listener);
  }

  emit<K extends keyof T>(event: K, data: T[K]): void {
    const eventListeners = this.listeners[event];
    if (eventListeners) {
      eventListeners.forEach(listener => listener(data));
    }
  }
}

// Usage with type safety
const emitter = new TypedEventEmitter<EventMap>();

emitter.on('user:created', (data) => {
  console.log(data.id, data.name);  // TypeScript knows the shape
});

emitter.emit('user:created', { id: '123', name: 'Alice' });  // Type-checked

Troubleshooting

Advanced TypeScript Features

Mapped Types

Transform existing types:

type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};

type Partial<T> = {
  [P in keyof T]?: T[P];
};

type Pick<T, K extends keyof T> = {
  [P in K]: T[P];
};

// Usage
interface User {
  id: number;
  name: string;
  email: string;
}

type ReadonlyUser = Readonly<User>;  // All properties readonly
type PartialUser = Partial<User>;    // All properties optional
type UserNameEmail = Pick<User, 'name' | 'email'>;  // Only name and email

Conditional Types

Types that depend on conditions:

type IsString<T> = T extends string ? true : false;

type A = IsString<string>;   // true
type B = IsString<number>;   // false

// Practical example: Extract function return type
type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;

function getUser() {
  return { id: 1, name: "Alice" };
}

type User = ReturnType<typeof getUser>;  // { id: number; name: string }

Template Literal Types

String manipulation at type level:

type Greeting<T extends string> = `Hello, ${T}!`;

type WelcomeMessage = Greeting<"World">;  // "Hello, World!"

// Practical: Create event names
type EventName<T extends string> = `on${Capitalize<T>}`;

type ClickEvent = EventName<"click">;  // "onClick"
type HoverEvent = EventName<"hover">;  // "onHover"

TypeScript Configuration Reference

Key tsconfig.json Options

Migration Checklist

When migrating a JavaScript project to TypeScript:

Phase 1: Setup

• Install TypeScript and @types packages
• Create tsconfig.json with permissive settings
• Configure build scripts
• Set up IDE/editor TypeScript support

Phase 2: Incremental Migration

• Enable allowJs: true and checkJs: false
• Rename utility files to .ts
• Add type annotations to function signatures
• Create interfaces for data structures
• Fix TypeScript errors in converted files

Phase 3: Strengthen Types

• Enable noImplicitAny: true
• Enable strictNullChecks: true
• Remove any types where possible
• Add type guards for union types
• Create type definitions for external modules

Phase 4: Full Strict Mode

• Enable strict: true
• Fix all remaining type errors
• Remove JSDoc annotations (now redundant)
• Optimize type definitions
• Document complex types

Phase 5: Maintenance

• Set up pre-commit type checking
• Configure CI/CD type checking
• Establish code review standards for types
• Keep TypeScript and @types packages updated

References

This skill includes bundled reference documentation for TypeScript essentials.

Reference Documentation (references/)

Core Concepts & Fundamentals

• basics.md - TypeScript fundamentals, simple types, type inference, and special types
• essentials.md - Core TypeScript concepts every developer should know
• cheatsheet.md - Quick reference for control flow, classes, interfaces, types, and common patterns

Type System & Language Features

• types.md - Advanced types, conditional types, mapped types, type guards, and recursive types
• classes.md - Class syntax, inheritance, generics, and utility types
• elements.md - Arrays, tuples, objects, enums, functions, and casting
• keywords.md - keyof, null handling, optional chaining, and template literal types
• miscellaneous.md - Async programming, promises, decorators, and JSDoc integration

External Resources

• TypeScript Official Documentation
• TypeScript Handbook
• TypeScript tsconfig Reference
• TypeScript Deep Dive
• TypeScript Playground - Test TypeScript code online

Summary

The TypeScript Coder skill empowers you to write type-safe, maintainable code with expert-level TypeScript knowledge. Whether migrating existing JavaScript projects or starting new TypeScript projects, apply these proven patterns, workflows, and best practices to deliver production-quality code with confidence.

Remember: TypeScript is a tool for developer productivity and code quality. Use it to catch errors early, improve code documentation, and enable better tooling—but don't let perfect types prevent shipping working code.