Agent Skills › Taoidle/plan-cascade › typescript-best-practices

typescript-best-practices

GitHub

提供TypeScript/Node.js开发的最佳实践指南，涵盖代码规范、类型安全、错误处理、项目结构、异步模式及Vitest测试方法，旨在提升代码质量与安全性。

builtin-skills/typescript/SKILL.md Taoidle/plan-cascade

触发场景

编写TypeScript代码审查TypeScript代码解决类型安全问题配置ESLint或Prettier

安装

npx skills add Taoidle/plan-cascade --skill typescript-best-practices -g -y

更多选项

非标准路径

npx skills add https://github.com/Taoidle/plan-cascade/tree/master/builtin-skills/typescript -g -y

不安装直接使用

npx skills use Taoidle/plan-cascade@typescript-best-practices

指定 Agent (Claude Code)

npx skills add Taoidle/plan-cascade --skill typescript-best-practices -a claude-code -g -y

安装 repo 全部 skill

npx skills add Taoidle/plan-cascade --all -g -y

预览 repo 内 skill

npx skills add Taoidle/plan-cascade --list

SKILL.md

Frontmatter

{
    "name": "typescript-best-practices",
    "license": "MIT",
    "metadata": {
        "author": "plan-cascade",
        "version": "1.0.0"
    },
    "description": "TypeScript\/Node.js best practices. Use when writing or reviewing TypeScript code. Covers type safety, async patterns, and error handling."
}

TypeScript Best Practices

Code Style

Rule	Guideline
Formatter	Prettier
Linter	ESLint + `@typescript-eslint`
Strict mode	`strict: true` in tsconfig

Type Safety

Rule	Guideline
Avoid `any`	Use `unknown` + narrowing
Type guards	Custom predicates
Discriminated unions	For variants

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

function isUser(v: unknown): v is User {
  return typeof v === 'object' && v !== null && 'id' in v;
}

Error Handling

class ApiError extends Error {
  constructor(message: string, public status: number) {
    super(message);
    this.name = 'ApiError';
  }
}

async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new ApiError('Failed', res.status);
  return res.json();
}

Project Structure

src/{index.ts, types/, services/, utils/}
tests/
package.json, tsconfig.json

Async Patterns

Pattern	Usage
`Promise.all`	Parallel operations
`AbortController`	Cancellation

const [user, settings] = await Promise.all([fetchUser(id), fetchSettings(id)]);

Anti-Patterns

Avoid	Use Instead
`as` assertions	Type guards
`!` non-null	`?.` and `??`
`any`	`unknown` + narrowing

// Bad: data as User, user!.name
// Good:
if (isUser(data)) { /* data is User */ }
const name = user?.name ?? 'Unknown';

Testing (Vitest)

describe('Service', () => {
  it('should create', async () => {
    const mock = { save: vi.fn().mockResolvedValue({ id: '1' }) };
    const result = await new Service(mock).create({ name: 'Test' });
    expect(result.id).toBe('1');
  });
});