TypeScript Skill

This skill extends the main foundations of how Claude Code approaches TypeScript, providing a more detailed and specific approach for writing high-quality TS code.

General Philosophy

• Correctness first: code must be correct before being elegant.
• Types as documentation: types are explicit contracts, not a formality. If a type

says string, it must always be string — not accidentally string | undefined.

• Explicit over implicit: prefer clarity over brevity when there is ambiguity.
• No `any` without justification: any is technical debt. If used, the reason must be commented.

Default Assumed Configuration

Unless the user indicates otherwise, assume:

// tsconfig.json (strict mode)
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "moduleResolution": "bundler",
    "target": "ES2024",
    "module": "ESNext"
  }
}

// .prettierrc (for consistent formatting)
{
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100
}

If the project has a tsconfig.json and/or .prettierrc visible in context, read it first and adjust all suggestions to that real configuration.

Types and Structures

See Type Preferences for details.

Code Patterns

See Code Patterns for details.

Runtime Validation

See Runtime Validation for details.

Module Organization

See Module Organization for details.

Always:

• One file = one clear responsibility.
• Re-export from index.ts only what is public API of the module.
• Avoid circular imports — if they appear, it's a sign of a missing module.

Programming Paradigms

See Programming Paradigms for details.

Metaprogramming

See Metaprogramming for details.

Comments

See Comments for details.

Naming Conventions

Files can be named with an optional suffix indicating their purpose, like .service.ts, .controller.ts, .types.ts, etc., for example user-identity.service.ts for a service related to user identity.

Generics

// ✅ Constrain when the generic has real requirements
function getProperty<TTarget, TKey extends keyof TTarget>(obj: TTarget, key: TKey): TTarget[TKey] {
  return obj[key];
}

// ✅ Default types for APIs with good DX
type Paginated<T = unknown> = { items: T[]; total: number; page: number };

// ❌ Do not use generics just to look flexible — if it is always string, it is string
function logMessage<T>(message: T): void {
  console.log(message);
}

Checklist before delivering code

• [ ] Does it compile with strict: true?
• [ ] Is there any unjustified any?
• [ ] Are expected errors handled (not just network/runtime)?
• [ ] Do exported functions have explicit returns?
• [ ] Does external data pass through a validation schema?
• [ ] Do tests cover narrowing edge cases?

Ecosystem Context

Read the relevant section based on the detected stack in the project:

• Node.js / APIs: prefer native fetch (Node 18+), AsyncLocalStorage for context,

consider tRPC or Hono for end-to-end type-safety.

• React / Next.js: typed components with FC only if explicit children is needed,

prefer JSX.Element or ReactNode returns depending on the case.

• Deno / Bun: leverage global types of the runtime — do not install @types/node

unnecessarily.

• Testing: Vitest > Jest for new projects (better type inference in mocks).

Notes:

• Before writing code, read the project's tsconfig.json and package.json files

to understand the target, runtime, and available dependencies.

• If a linter is detected (.eslintrc, biome.json, etc.), respect its rules.
• Prefer editing the existing file over creating a new one unless it is clearly

a new addition to the project.

• When refactoring: make the minimal change that improves the situation, do not rewrite everything.