playbooks

home / skills / julianobarbosa / claude-code-skills / writing-typescript-skill

writing-typescript-skill skill

/skills/writing-typescript-skill

This skill helps you write idiomatic TypeScript by enforcing strict typing, composition, and modern tooling across Node.js and React projects.

npx playbooks add skill julianobarbosa/claude-code-skills --skill writing-typescript-skill

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.0 KB
---
name: writing-typescript
description: Idiomatic TypeScript development. Use when writing TypeScript code, Node.js services, React apps, or discussing TS patterns. Emphasizes strict typing, composition, and modern tooling (bun/vite).
allowed-tools: Read, Bash, Grep, Glob
---

# TypeScript Development (2025)

## Core Principles

- **Strict typing**: Enable all strict checks
- **Parse, don't validate**: Transform untrusted data at boundaries
- **Composition over inheritance**: Small, focused functions
- **Explicit over implicit**: No `any`, prefer `unknown`

## Toolchain

```bash
bun          # Runtime + package manager (fast)
vite         # Frontend bundling
vitest       # Testing
eslint       # Linting
prettier     # Formatting
```

## Quick Patterns

### Type Guards

```typescript
function isUser(value: unknown): value is User {
  return typeof value === "object" && value !== null && "id" in value;
}
```

### Discriminated Unions

```typescript
type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

function processResult<T>(result: Result<T>): T {
  if (result.ok) return result.value;
  throw result.error;
}
```

### Utility Types

```typescript
type UserUpdate = Partial<User>;
type UserSummary = Pick<User, "id" | "name">;
type UserWithoutPassword = Omit<User, "password">;
type ReadonlyUser = Readonly<User>;
```

## tsconfig.json Essentials

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitReturns": true,
    "isolatedModules": true
  }
}
```

## References

- [PATTERNS.md](PATTERNS.md) - Code patterns and style
- [REACT.md](REACT.md) - React component patterns
- [TESTING.md](TESTING.md) - Testing with vitest

## Commands

```bash
bun install              # Install deps
bun run build            # Build
bun test                 # Test
bun run lint             # Lint
bun run format           # Format
```

Overview

This skill guides idiomatic TypeScript development for Node.js services, React apps, and libraries. It focuses on strict typing, safe data boundaries, composition, and modern fast tooling like bun and vite. Use it to enforce robust types, predictable runtime behavior, and streamlined developer workflows.

How this skill works

It inspects code patterns and recommends TypeScript-first solutions: strict tsconfig settings, type guards, discriminated unions, and utility types to reduce runtime errors. It also maps recommended toolchain commands and configuration snippets for bun, vite, vitest, eslint, and prettier. Suggestions emphasize transforming untrusted input at boundaries and composing small, focused functions instead of heavy inheritance.

When to use it

  • Starting a new TypeScript project (Node or frontend) to set strict defaults
  • Refactoring JavaScript to TypeScript with safer typings and fewer any usages
  • Designing APIs or service boundaries that accept external/untrusted data
  • Implementing React components with strict props and composition patterns
  • Setting up fast local tooling with bun, vite, and vitest

Best practices

  • Enable all strict compiler checks and use noUncheckedIndexedAccess and exactOptionalPropertyTypes
  • Prefer unknown for external inputs and write narrow type guards to parse data at boundaries
  • Favor composition and small pure functions over inheritance and monolithic classes
  • Use discriminated unions for clear runtime-safe variants and Result-style error handling
  • Leverage utility types (Partial, Pick, Omit, Readonly) to derive safe shapes rather than mutating models
  • Standardize linting and formatting with eslint and prettier, and run tests with vitest

Example use cases

  • Define a safe API handler that parses JSON into typed domain models using type guards
  • Refactor a legacy Node service to strict TS, adding tsconfig strict options and removing implicit anys
  • Create a React component library using composition, exact prop types, and vite for fast HMR
  • Build a small microservice with bun, run unit tests with vitest, and enforce types in CI
  • Model domain operations with Result<T> discriminated unions and central error handling

FAQ

What tsconfig options are essential?

Enable strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitReturns, isolatedModules, and target ES2022 with module ESNext.

How should I handle external JSON or query data?

Treat it as unknown, write focused type guards or parsing functions to transform it into well-typed domain objects at the boundary.