typescript

laulauland 的头像作者 laulauland

TypeScript编码约定和最佳实践。处理TypeScript文件、定义类型或设置TypeScript项目时使用。

📖 中文导读:TypeScript编码约定和最佳实践。处理TypeScript文件、定义类型或设置TypeScript项目时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: typescript description: TypeScript coding conventions and best practices. Use when working with TypeScript files, defining types, or setting up TypeScript projects.

TypeScript Guidelines

Type System Usage

  • Use TypeScript for all code
  • Prefer interfaces over types for object definitions
  • Avoid enums; use const objects with 'as const' assertion
// Prefer:
const UserRole = {
  ADMIN: 'ADMIN',
  USER: 'USER',
} as const;
type UserRole = typeof UserRole[keyof typeof UserRole];

// Avoid:
enum UserRole {
  ADMIN = 'ADMIN',
  USER = 'USER',
}

Type Safety Rules

  • Define strict types for all message passing between components
  • Use explicit return types for all functions
  • Use functional components with TypeScript interfaces
interface Props {
  user: UserProfile;
  onUpdate: (user: UserProfile) => void;
}

function UserComponent ({ user, onUpdate }: Props): JSX.Element {
  // ...
};

Schema Libraries for Data Modeling

When a project uses a schema library (Zod, Effect Schema, Valibot, etc.), prefer using it for data modeling over plain TypeScript types:

// If project uses Zod, prefer:
const User = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
});
type User = z.infer<typeof User>;

// Over plain TypeScript:
interface User {
  id: string;
  email: string;
  role: 'admin' | 'user';
}

Benefits:

  • Runtime validation at system boundaries
  • Single source of truth (schema derives type)
  • Automatic parsing and transformation
  • Better error messages

Import and Error Handling

  • Avoid try/catch blocks unless error translation is needed at that level
  • If needed, prefer using tryCatch/tryCatchAsync utility functions that return errors or data
import { UserService } from '@/services/user';
import { Logger } from '@/utils/logger';