Typescript Best Practices

作者 alleneubank2921eb8a685a无许可证52 个星标收录于 2026年10月8日更新于 2026年10月8日仓库3个月前更新

Use when reading or writing TypeScript or JavaScript files (.ts, .tsx, .js, tsconfig.json).

已归档仅含说明Software Development

AI 生成的概览

以类型优先、函数式和错误处理模式指导 TypeScript 与 JavaScript 编码。

功能: 该技能提供 TypeScript 和 JavaScript 的语言级惯用法，包括可辨识联合、品牌类型、const 断言、穷尽 switch 检查以及 Zod 运行时校验。它建议在处理 React 组件时配合另一个 React 技能使用，并提到可选的 type-fest 工具类型。它产出的是指导与代码模式，而不是文件或脚本。
适用场景: 在阅读或编写 TypeScript、JavaScript 文件（如 .ts、.tsx、.js 或 tsconfig.json）时使用。它面向语言层面的模式，不涉及 React 组件设计，后者交由另一个技能处理。
运行要求: 除智能体本身外无需脚本或工具。指南中提及 Zod 库以及可选的 type-fest，并假定项目使用 TypeScript 或 JavaScript。

TypeScript Best Practices

Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only.

Pair with React Best Practices

When working with React components (.tsx, .jsx files or @react imports), always load react-best-practices alongside this skill. This skill covers TypeScript fundamentals; React-specific patterns (effects, hooks, refs, component design) are in the dedicated React skill.

Make Illegal States Unrepresentable

Use the type system to prevent invalid states at compile time.

Discriminated unions for mutually exclusive states:

// Good: only valid combinations possibletype RequestState<T> =  | { status: 'idle' }  | { status: 'loading' }  | { status: 'success'; data: T }  | { status: 'error'; error: Error };
// Bad: allows invalid combinations like { loading: true, error: Error }type RequestState<T> = {  loading: boolean;  data?: T;  error?: Error;};

// Good: only valid combinations possibletype RequestState<T> =  | { status: 'idle' }  | { status: 'loading' }  | { status: 'success'; data: T }  | { status: 'error'; error: Error };
// Bad: allows invalid combinations like { loading: true, error: Error }type RequestState<T> = {  loading: boolean;  data?: T;  error?: Error;};

Branded types for domain primitives:

type UserId = string & { readonly __brand: 'UserId' };type OrderId = string & { readonly __brand: 'OrderId' };
// Compiler prevents passing OrderId where UserId expectedfunction getUser(id: UserId): Promise<User> { /* ... */ }

type UserId = string & { readonly __brand: 'UserId' };type OrderId = string & { readonly __brand: 'OrderId' };
// Compiler prevents passing OrderId where UserId expectedfunction getUser(id: UserId): Promise<User> { /* ... */ }

Const assertions for literal unions:

const ROLES = ['admin', 'user', 'guest'] as const;type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
// Array and type stay in sync automaticallyfunction isValidRole(role: string): role is Role {  return ROLES.includes(role as Role);}

const ROLES = ['admin', 'user', 'guest'] as const;type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
// Array and type stay in sync automaticallyfunction isValidRole(role: string): role is Role {  return ROLES.includes(role as Role);}

Exhaustive switch with never check:

type Status = "active" | "inactive";
function processStatus(status: Status): string {  switch (status) {    case "active":      return "processing";    case "inactive":      return "skipped";    default: {      const _exhaustive: never = status;      throw new Error(`unhandled status: ${_exhaustive}`);    }  }}

type Status = "active" | "inactive";
function processStatus(status: Status): string {  switch (status) {    case "active":      return "processing";    case "inactive":      return "skipped";    default: {      const _exhaustive: never = status;      throw new Error(`unhandled status: ${_exhaustive}`);    }  }}

Runtime Validation with Zod

Define schemas as single source of truth; infer TypeScript types with z.infer<>. Avoid duplicating types and schemas.
Use safeParse for user input where failure is expected; use parse at trust boundaries where invalid data is a bug.
Compose schemas with .extend(), .pick(), .omit(), .merge() for DRY definitions.
Add .transform() for data normalization at parse time (trim strings, parse dates).

import { z } from "zod";
const UserSchema = z.object({  id: z.string().uuid(),  email: z.string().email(),  name: z.string().min(1),  createdAt: z.string().transform((s) => new Date(s)),});
type User = z.infer<typeof UserSchema>;
// Strict parsing at trust boundaries — throws if API contract violatedexport async function fetchUser(id: string): Promise<User> {  const response = await fetch(`/api/users/${id}`);  if (!response.ok) {    throw new Error(`fetch user ${id} failed: ${response.status}`);  }  return UserSchema.parse(await response.json());}
// Caller handles both success and error from user inputconst result = UserSchema.safeParse(formData);if (!result.success) {  setErrors(result.error.flatten().fieldErrors);  return;}

import { z } from "zod";
const UserSchema = z.object({  id: z.string().uuid(),  email: z.string().email(),  name: z.string().min(1),  createdAt: z.string().transform((s) => new Date(s)),});
type User = z.infer<typeof UserSchema>;
// Strict parsing at trust boundaries — throws if API contract violatedexport async function fetchUser(id: string): Promise<User> {  const response = await fetch(`/api/users/${id}`);  if (!response.ok) {    throw new Error(`fetch user ${id} failed: ${response.status}`);  }  return UserSchema.parse(await response.json());}
// Caller handles both success and error from user inputconst result = UserSchema.safeParse(formData);if (!result.success) {  setErrors(result.error.flatten().fieldErrors);  return;}

Optional: type-fest

For advanced type utilities beyond TypeScript builtins, consider type-fest:

Opaque<T, Token> - cleaner branded types than manual & { __brand } pattern
PartialDeep<T> - recursive partial for nested objects
ReadonlyDeep<T> - recursive readonly for immutable data
SetRequired<T, K> / SetOptional<T, K> - targeted field modifications
Simplify<T> - flatten complex intersection types in IDE tooltips

import type { Opaque, PartialDeep } from 'type-fest';
type UserId = Opaque<string, 'UserId'>;type UserPatch = PartialDeep<User>;

import type { Opaque, PartialDeep } from 'type-fest';
type UserId = Opaque<string, 'UserId'>;type UserPatch = PartialDeep<User>;

来源与署名

来源：alleneubank/claude-code位于.claude/skills/typescript-best-practices提交2921eb8

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

Typescript Best Practices

TypeScript Best Practices

Pair with React Best Practices

Make Illegal States Unrepresentable

Runtime Validation with Zod

Optional: type-fest

来源与署名

更多来自 alleneubank/claude-code 的技能

React Best Practices

Web Fetch

Zig Best Practices

Python Best Practices

Nix Best Practices

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices