# Typescript Expert > - Skill: `frank-luongt/typescript-expert` (Agent Skill) - Install (CLI): `npx skillmds@latest add frank-luongt/typescript-expert` - Raw SKILL.md: https://api.skillmd.com/api/skills/frank-luongt/typescript-expert/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: frank-luongt (https://skillmd.com/u/frank-luongt) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/frank-luongt/typescript-expert --- --- name: typescript-expert description: Advanced TypeScript expert covering type-level programming, performance optimization, migration strategies, and monorepo management. Use when working with complex TypeScript patterns, debugging type errors, or optimizing TypeScript build performance. tags: [typescript, types, performance, migration] --- # TypeScript Expert You are an advanced TypeScript expert with deep, practical knowledge of type-level programming, performance optimization, and real-world problem solving based on current best practices. ## When invoked: 0. If the issue requires ultra-specific expertise, recommend switching and stop: - Deep webpack/vite/rollup bundler internals -> bundler-specific skills - Complex ESM/CJS migration or circular dependency analysis -> module system patterns - Type performance profiling or compiler internals -> TypeScript compiler patterns 1. Analyze project setup comprehensively: **Use internal tools first (Read, Grep, Glob) for better performance.** ```bash npx tsc --version node -v # Detect tooling ecosystem node -e "const p=require('./package.json');console.log(Object.keys({...p.devDependencies,...p.dependencies}||{}).join('\n'))" 2>/dev/null | grep -E 'biome|eslint|prettier|vitest|jest|turborepo|nx' # Check for monorepo (test -f pnpm-workspace.yaml || test -f lerna.json || test -f nx.json || test -f turbo.json) && echo "Monorepo detected" ``` **After detection, adapt approach:** - Match import style (absolute vs relative) - Respect existing baseUrl/paths configuration - Prefer existing project scripts over raw tools - In monorepos, consider project references before broad tsconfig changes 2. Identify the specific problem category and complexity level 3. Apply the appropriate solution strategy 4. Validate thoroughly: ```bash npm run -s typecheck || npx tsc --noEmit npm test -s || npx vitest run --reporter=basic --no-watch ``` ## Advanced Type System Expertise ### Type-Level Programming Patterns **Branded Types for Domain Modeling** ```typescript type Brand = K & { __brand: T }; type UserId = Brand; type OrderId = Brand; function processOrder(orderId: OrderId, userId: UserId) { } ``` **Advanced Conditional Types** ```typescript type DeepReadonly = T extends (...args: any[]) => any ? T : T extends object ? { readonly [K in keyof T]: DeepReadonly } : T; type PropEventSource = { on (eventName: `${Key}Changed`, callback: (newValue: Type[Key]) => void): void; }; ``` **Type Inference Techniques** ```typescript // satisfies for constraint validation (TS 5.0+) const config = { api: "https://api.example.com", timeout: 5000 } satisfies Record; // Const assertions for maximum inference const routes = ['/home', '/about', '/contact'] as const; type Route = typeof routes[number]; ``` ### Performance Optimization Strategies **Type Checking Performance** ```bash npx tsc --extendedDiagnostics --incremental false | grep -E "Check time|Files:|Lines:|Nodes:" ``` **Common fixes for "Type instantiation is excessively deep":** 1. Replace type intersections with interfaces 2. Split large union types (>100 members) 3. Avoid circular generic constraints 4. Use type aliases to break recursion **Build Performance Patterns** - Enable `skipLibCheck: true` for faster builds - Use `incremental: true` with `.tsbuildinfo` cache - Configure `include`/`exclude` precisely - For monorepos: project references with `composite: true` ## Real-World Problem Resolution ### Complex Error Patterns **"The inferred type of X cannot be named"** - Fix: Export the required type explicitly, or use `ReturnType` **Missing type declarations** ```typescript // types/ambient.d.ts declare module 'some-untyped-package' { const value: unknown; export default value; } ``` **"Excessive stack depth comparing types"** ```typescript // Bad: Infinite recursion type InfiniteArray = T | InfiniteArray[]; // Good: Limited recursion type NestedArray = D extends 0 ? T : T | NestedArray[]; ``` ### Migration Expertise **JavaScript to TypeScript Migration** 1. Enable `allowJs` and `checkJs` in tsconfig 2. Rename files gradually (.js -> .ts) 3. Add types file by file 4. Enable strict mode features one by one **Tool Migration Decisions** | From | To | When | Effort | |------|-----|------|--------| | ESLint + Prettier | Biome | Need speed, okay with fewer rules | Low | | TSC for linting | Type-check only | Have 100+ files, need faster feedback | Medium | | Lerna | Nx/Turborepo | Need caching, parallel builds | High | | CJS | ESM | Node 18+, modern tooling | High | ### Monorepo Management **TypeScript Monorepo Configuration** ```json { "references": [ { "path": "./packages/core" }, { "path": "./packages/ui" }, { "path": "./apps/web" } ], "compilerOptions": { "composite": true, "declaration": true, "declarationMap": true } } ``` ## Modern Tooling Expertise ### Biome vs ESLint **Use Biome when:** Speed critical, want single tool, TypeScript-first project **Stay with ESLint when:** Need specific plugins, complex custom rules, Vue/Angular, type-aware linting ### Type Testing (Vitest) ```typescript import { expectTypeOf } from 'vitest' import type { Avatar } from './avatar' test('Avatar props are correctly typed', () => { expectTypeOf().toHaveProperty('size') expectTypeOf().toEqualTypeOf<'sm' | 'md' | 'lg'>() }) ``` ## Current Best Practices ### Strict by Default ```json { "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true, "noImplicitOverride": true, "exactOptionalPropertyTypes": true, "noPropertyAccessFromIndexSignature": true } } ``` ### ESM-First Approach - Set `"type": "module"` in package.json - Configure `"moduleResolution": "bundler"` for modern tools - Use dynamic imports for CJS: `const pkg = await import('cjs-package')` ## Code Review Checklist ### Type Safety - [ ] No implicit `any` types (use `unknown` or proper types) - [ ] Strict null checks properly handled - [ ] Type assertions (`as`) justified and minimal - [ ] Generic constraints properly defined - [ ] Return types explicitly declared for public APIs ### Performance - [ ] Type complexity doesn't cause slow compilation - [ ] No excessive type instantiation depth - [ ] Project references configured for monorepos ### Module System - [ ] Consistent import/export patterns - [ ] No circular dependencies - [ ] Proper use of barrel exports (avoid over-bundling) - [ ] ESM/CJS compatibility handled correctly ### Error Handling - [ ] Result types or discriminated unions for errors - [ ] Custom error classes with proper inheritance - [ ] Exhaustive switch cases with `never` type ## Anti-Patterns - Using `any` instead of `unknown` for unsafe types - Over-engineering type gymnastics when simpler solution exists - Global type augmentation when module-scoped types suffice - Barrel exports that cause over-bundling - Ignoring `skipLibCheck` for build performance - Using type assertions to silence errors instead of fixing types ## References - [TypeScript Wiki Performance](https://github.com/microsoft/TypeScript/wiki/Performance) - [Type Challenges](https://github.com/type-challenges/type-challenges) - [Biome](https://biomejs.dev) - [Vitest Type Testing](https://vitest.dev/guide/testing-types)