TypeScript核心开发模式2025：类型安全、运行时验证与最佳配置指南

typescript-core by bobmatnyc/claude-mpm-skills

154 周安装量

28 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill typescript-core

开发 TypeScript 代码规范

🇨🇳中文介绍

TypeScript 核心模式

现代 TypeScript 开发模式，用于类型安全、运行时验证和最佳配置。

快速开始

新项目： 使用 2025 tsconfig → 启用 strict + noUncheckedIndexedAccess → 选择 Zod 进行验证

现有项目： 初始启用 strict: false → 用 unknown 修复 any → 添加 noUncheckedIndexedAccess

API 开发： 在边界使用 Zod 模式 → 使用 z.infer<typeof Schema> 获取类型 → 使用 satisfies 定义路由

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

tsconfig.json 2025 基准配置

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

关键编译器选项

选项	目的	何时启用
`noUncheckedIndexedAccess`	强制对数组/对象访问进行空值检查	始终启用以确保安全
`exactOptionalPropertyTypes`	区分 `undefined` 与缺失属性	具有可选字段的 API
`verbatimModuleSyntax`	强制显式类型导入	ESM 项目
`erasableSyntaxOnly`	Node.js 22+ 原生 TS 支持	类型剥离环境

查看 references/configuration.md 获取仓库特定的 tsconfig 模式（CommonJS CLI、NodeNext 严格模式、Next.js 打包器）。

通过泛型函数保留字面量类型：

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

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

针对类型进行验证，同时保留字面量推断：

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

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

routes.AUTH.path;     // 类型: "/auth" (字面量保留)
routes.NONEXISTENT;   // ❌ 类型错误

模板字面量类型

类型安全的字符串操作和路由参数提取：

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"

可辨识联合与穷尽性检查

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;
}

// 穷尽性检查
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}`);
    }
  }
}

TypeScript 类型在运行时消失。使用验证库处理外部数据（API、表单、配置文件）。

库	打包大小	速度	最佳适用场景
Zod	~13.5kB	基准	全栈应用、tRPC 集成
TypeBox	~8kB	~10 倍更快	OpenAPI、性能关键场景
Valibot	~1.4kB	~2 倍更快	边缘函数、最小化打包

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>;

// 验证外部数据
function parseUser(input: unknown): User {
  return UserSchema.parse(input);
}

→ 查看runtime-validation.md 获取完整的 Zod、TypeBox 和 Valibot 模式

需要在type 和 interface 之间选择？

公共 API / 库类型 → interface
联合类型 / 映射类型 → type
简单对象形状 → interface (默认)

需要泛型还是联合类型？

输出类型依赖于输入类型 → 泛型
固定的已知类型集合 → 联合类型
构建可重用数据结构 → 泛型

处理未知数据？

外部数据 (API、用户输入) → unknown (类型安全)
快速原型设计 / 迁移 → any (临时使用)

需要运行时验证？

全栈 TypeScript 与 tRPC → Zod
OpenAPI / 高性能 → TypeBox
边缘函数 / 最小化打包 → Valibot

→ 查看decision-trees.md 获取全面的决策框架

常见问题快速参考

类型上不存在属性 → 定义正确的接口或使用可选属性

类型不可分配 → 修复属性类型或使用运行时验证 (Zod)

对象可能为 'undefined' → 使用可选链 (?.) 或类型守卫

找不到模块 → 检查文件扩展名（ESM 使用 .js）和模块解析

编译缓慢 → 启用 incremental，使用 skipLibCheck，考虑 esbuild/swc

→ 查看troubleshooting.md 获取带示例的详细解决方案

📐 高级类型 - 条件类型、映射类型、infer 关键字、递归类型。构建复杂类型工具或通用库时加载。
⚙️ 配置 - 完整的 tsconfig.json 指南、项目引用、monorepo 模式。设置新项目或优化构建时加载。
🔒 运行时验证 - Zod、TypeBox、Valibot 深度模式、错误处理、集成策略。实现 API 验证或表单处理时加载。
✨ 2025 高级模式 - TypeScript 5.2+ 特性：using 关键字、稳定装饰器、导入类型行为、带泛型的 satisfies。使用现代语言特性时加载。
🌳 决策树 - 清晰的决策框架，涵盖 type vs interface、泛型 vs 联合类型、unknown vs any、验证库选择、类型收窄策略和模块解析。做出 TypeScript 设计决策时加载。
🔧 故障排除 - 常见 TypeScript 错误和修复、类型推断问题、模块解析问题、tsconfig 配置错误、构建性能优化和类型兼容性错误。调试 TypeScript 问题时加载。

如果出现以下情况，请停止并重新考虑：

对外部数据使用 any 而不是 unknown
没有运行时验证就使用 as 进行类型断言
为了方便而禁用严格模式
没有明确理由就使用 @ts-ignore
没有启用 noUncheckedIndexedAccess 就进行索引访问

与其他技能的集成

nextjs-core : 类型安全的服务器操作和路由处理程序
nextjs-v16 : 异步 API 模式和缓存组件类型化
mcp-builder : MCP 工具输入的 Zod 模式

使用 Core 时，这些技能可以增强您的工作流程：

react : 使用 TypeScript 的 React：组件类型化、钩子、泛型
nextjs : Next.js 中的 TypeScript：服务器组件、服务器操作类型化
drizzle : 使用 Drizzle ORM 进行类型安全的数据库查询
prisma : Prisma 生成的 TypeScript 类型用于数据库模式

[完整文档可在这些技能中找到，如果已部署到您的包中]

2026 年 1 月 23 日

🇺🇸English

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 → Choose Zod for validation

Existing Project: Enable strict: false initially → Fix any with unknown → Add noUncheckedIndexedAccess

API Development: Zod schemas at boundaries → z.infer<typeof Schema> for types → satisfies for routes

Library Development: Enable declaration: true → Use const type parameters → See advanced-patterns-2025.md

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

Option	Purpose	When to Enable
`noUncheckedIndexedAccess`	Forces null checks on array/object access	Always for safety
`exactOptionalPropertyTypes`	Distinguishes `undefined` from missing	APIs with optional fields
`verbatimModuleSyntax`	Enforces explicit type-only imports	ESM projects
`erasableSyntaxOnly`	Node.js 22+ native TS support	Type stripping environments

Local Baselines

See references/configuration.md for repo-specific tsconfig patterns (CommonJS CLI, NodeNext strict, Next.js bundler).

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

Library	Bundle Size	Speed	Best For
Zod	~13.5kB	Baseline	Full-stack apps, tRPC integration
TypeBox	~8kB	~10x faster	OpenAPI, performance-critical
Valibot	~1.4kB	~2x faster	Edge functions, minimal bundles

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);
}

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

Decision Support

Quick Decision Guide

Need to choose betweentype vs 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

→ Seedecision-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 (?.) or type guards

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

Slow compilation → Enable incremental, use skipLibCheck, consider esbuild/swc

→ Seetroubleshooting.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, vs , validation library selection, type narrowing strategies, and module resolution. Load when making TypeScript design decisions.

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]

Weekly Installs

106

Repository

bobmatnyc/claud…m-skills

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

cursor67

claude-code65

opencode64

codex63

gemini-cli59

github-copilot58

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

116,600 周安装

🔧 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.

TypeScript核心开发模式2025：类型安全、运行时验证与最佳配置指南

🇨🇳中文介绍

TypeScript 核心模式

快速开始

相关 Skills

快速参考

tsconfig.json 2025 基准配置

关键编译器选项

本地基准配置

核心类型模式

常量类型参数

Satisfies 操作符