TypeScript Core Patterns

Modern TypeScript development patterns for type safety, runtime validation, and optimal configuration.

Quick Start

New Project: Use 2025 tsconfig → Enable

strict

noUncheckedIndexedAccess

Existing Project: Enable

strict: false

any

unknown

noUncheckedIndexedAccess

API Development: Zod schemas at boundaries →

z.infer<typeof Schema>

satisfies

Library Development: Enable

declaration: true

const

Quick Reference

tsconfig.json 2025 Baseline

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationMap": true
  }
}

Key Compiler Options

noUncheckedIndexedAccess

exactOptionalPropertyTypes

undefined

verbatimModuleSyntax

erasableSyntaxOnly

Local Baselines

See

references/configuration.md

Core Type Patterns

Const Type Parameters

Preserve literal types through generic functions:

function createConfig<const T extends Record<string, unknown>>(config: T): T {
  return config;
}

const config = createConfig({ 
  apiUrl: "https://api.example.com", 
  timeout: 5000 
});
// Type: { readonly apiUrl: "https://api.example.com"; readonly timeout: 5000 }

Satisfies Operator

Validate against a type while preserving literal inference:

type Route = { path: string; children?: Routes };
type Routes = Record<string, Route>;

const routes = {
  AUTH: { path: "/auth" },
  HOME: { path: "/" }
} satisfies Routes;

routes.AUTH.path;     // Type: "/auth" (literal preserved)
routes.NONEXISTENT;   // ❌ Type error

Template Literal Types

Type-safe string manipulation and route extraction:

type ExtractParams<T extends string> = 
  T extends `${string}:${infer Param}/${infer Rest}`
    ? Param | ExtractParams<Rest>
    : T extends `${string}:${infer Param}`
      ? Param
      : never;

type Params = ExtractParams<"/users/:id/posts/:postId">; // "id" | "postId"

Discriminated Unions with Exhaustiveness

type Result<T, E = Error> = 
  | { success: true; data: T }
  | { success: false; error: E };

function handleResult<T>(result: Result<T>): T {
  if (result.success) return result.data;
  throw result.error;
}

// Exhaustiveness checking
type Action = 
  | { type: 'create'; payload: string }
  | { type: 'delete'; id: number };

function handle(action: Action) {
  switch (action.type) {
    case 'create': return action.payload;
    case 'delete': return action.id;
    default: {
      const _exhaustive: never = action;
      throw new Error(`Unhandled: ${_exhaustive}`);
    }
  }
}

Runtime Validation

TypeScript types disappear at runtime. Use validation libraries for external data (APIs, forms, config files).

Quick Comparison

Basic Pattern (Zod)

import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "guest"]),
});

type User = z.infer<typeof UserSchema>;

// Validate external data
function parseUser(input: unknown): User {
  return UserSchema.parse(input);
}

→ See runtime-validation.md for complete Zod, TypeBox, and Valibot patterns

Decision Support

Quick Decision Guide

Need to choose between

type

interface

• Public API / library types →

  interface

• Union types / mapped types →

  type

• Simple object shapes →

  interface

  (default)

Need generics or union types?

• Output type depends on input type → Generics
• Fixed set of known types → Union types
• Building reusable data structures → Generics

Dealing with unknown data?

• External data (API, user input) →

  unknown

  (type-safe)
• Rapid prototyping / migration →

  any

  (temporarily)

Need runtime validation?

• Full-stack TypeScript with tRPC → Zod
• OpenAPI / high performance → TypeBox
• Edge functions / minimal bundle → Valibot

→ See decision-trees.md for comprehensive decision frameworks

Troubleshooting

Common Issues Quick Reference

Property does not exist on type → Define proper interface or use optional properties

Type is not assignable → Fix property types or use runtime validation (Zod)

Object is possibly 'undefined' → Use optional chaining (

?.

Cannot find module → Check file extensions (.js for ESM) and module resolution

Slow compilation → Enable

incremental

skipLibCheck

→ See troubleshooting.md for detailed solutions with examples

Navigation

Detailed References

• 📐 Advanced Types - Conditional types, mapped types, infer keyword, recursive types. Load when building complex type utilities or generic libraries.

• ⚙️ Configuration - Complete tsconfig.json guide, project references, monorepo patterns. Load when setting up new projects or optimizing builds.

• 🔒 Runtime Validation - Zod, TypeBox, Valibot deep patterns, error handling, integration strategies. Load when implementing API validation or form handling.

• ✨ Advanced Patterns 2025 - TypeScript 5.2+ features:

  using

  keyword, stable decorators, import type behavior, satisfies with generics. Load when using modern language features.

• 🌳 Decision Trees - Clear decision frameworks for

  type

  vs

  interface

  , generics vs unions,

  unknown

  vs

  any

  , validation library selection, type narrowing strategies, and module resolution. Load when making TypeScript design decisions.

• 🔧 Troubleshooting - Common TypeScript errors and fixes, type inference issues, module resolution problems, tsconfig misconfigurations, build performance optimization, and type compatibility errors. Load when debugging TypeScript issues.

Red Flags

Stop and reconsider if:

• Using

  any

  instead of

  unknown

  for external data
• Casting with

  as

  without runtime validation
• Disabling strict mode for convenience
• Using

  @ts-ignore

  without clear justification
• Index access without

  noUncheckedIndexedAccess

Integration with Other Skills

• nextjs-core: Type-safe Server Actions and route handlers
• nextjs-v16: Async API patterns and Cache Components typing
• mcp-builder: Zod schemas for MCP tool inputs

Related Skills

When using Core, these skills enhance your workflow:

• react: TypeScript with React: component typing, hooks, generics
• nextjs: TypeScript in Next.js: Server Components, Server Actions typing
• drizzle: Type-safe database queries with Drizzle ORM
• prisma: Prisma's generated TypeScript types for database schemas

[Full documentation available in these skills if deployed in your bundle]