Better typescript

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

Element	Convention	Example
Variables / functions	camelCase	getUserById
Types / Interfaces	PascalCase	UserRepository
Global constants	SCREAMING_SNAKE_CASE	MAX_RETRIES
Files	kebab-case	user-repository.ts
Booleans	prefix is/has/can	isActive, hasPermission
Simple generics	T, U, K, V	Array<T>
Descriptive generics	PascalCase	Result<TValue, TError>

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.