structuring-typescript-code

15195999826's avatarfrom 15195999826

Guides TypeScript code structure: imports, exports, module organization. Use when organizing code, setting up project structure, or resolving circular dependencies. Triggers: "import", "export", "模块", "文件结构", "barrel", "循环依赖".

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 9, 2026⬇️2downloads
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides comprehensive guidelines for organizing TypeScript projects, ensuring clean code through standardized import/export patterns, efficient module organization, and effective resolution of circular dependencies to improve maintainability and tree-shaking performance.

Use Cases

  • Setting up a new TypeScript project structure using feature-based organization rather than type-based folders.
  • Refactoring legacy codebases to eliminate circular dependencies and improve build stability using tools like madge.
  • Standardizing team coding conventions for imports, such as enforcing 'import type' and path aliases for cleaner code.
  • Optimizing application bundle sizes by managing barrel files correctly and avoiding 'export *' to ensure efficient tree-shaking.
namestructuring-typescript-code
description>-
Guides TypeScript code structureimports, exports, module organization.
Triggers"import", "export", "模块", "文件结构", "barrel", "循环依赖".

TypeScript 代码结构规范

核心约定

规范 项目选择
导出方式 命名导出（禁止 default）
类型导入 import type { }
重导出 显式列出（禁止 export *）
目录组织 按功能（不按类型）

路径别名

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

// ✗ import { User } from '../../../types/user'
// ✓ import { User } from '@/types/user'

目录结构

src/
├── features/           # 按功能组织
│   ├── user/
│   │   ├── user.types.ts
│   │   ├── user.service.ts
│   │   └── index.ts
│   └── order/
└── shared/             # 共享代码

Barrel 文件

// types/index.ts
export type { User, UserRole } from './user'
export type { Order } from './order'

// ✗ export * from './user'  // 影响 tree-shaking

何时用：小型模块、公共 API 入口 何时避免：大型项目深层目录

循环依赖

# 检测
npx madge --circular --extensions ts src/

解决：提取共享类型到独立文件。