建立一个 共享多个项目的 ts 类型库

<think>我们正在创建一个可在多个项目间共享的TypeScript类型库。以下是实现步骤： 1. 创建新项目 2. 配置TypeScript 3. 编写类型定义 4. 配置构建 5. 发布到npm（或使用本地引用） 6. 在其他项目中引用 详细步骤： ### 1. 创建项目目录并初始化 ```bash mkdir ts-types-library cd ts-types-library npm init -y ``` ### 2. 安装TypeScript ```bash npm install typescript --save-dev ``` ### 3. 初始化TypeScript配置 生成`tsconfig.json`： ```bash npx tsc --init ``` 修改`tsconfig.json`，设置编译选项，例如： ```json { "compilerOptions": { "declaration": true, // 生成.d.ts声明文件 "declarationDir": "dist", // 声明文件输出目录 "rootDir": "src", // 源代码目录 "outDir": "dist", // 输出目录 "module": "ESNext", // 模块系统 "target": "ES2017", // 编译目标 "moduleResolution": "node", // 模块解析方式 "esModuleInterop": true, "strict": true // 启用严格类型检查 }, "include": ["src/**/*"] } ``` ### 4. 创建目录结构 ``` ts-types-library/ ├── src/ │ └── index.ts # 导出所有类型 ├── package.json ├── tsconfig.json └── .npmignore # 忽略文件（可选） ``` ### 5. 编写类型定义 在`src/index.ts`中定义并导出类型： ```typescript // 示例：用户相关类型 export interface User { id: number; name: string; email: string; } // 使用工具类型派生新类型 export type UserPreview = Pick<User, 'id' | 'name'>; export type PartialUser = Partial<User>; ``` ### 6. 配置构建脚本 在`package.json`中添加构建命令： ```json "scripts": { "build": "tsc" } ``` 运行`npm run build`，生成的文件将位于`dist`目录。 ### 7. 配置package.json发布设置 确保`package.json`中包含以下字段： ```json { "name": "ts-types-library", // 包名（唯一） "version": "1.0.0", "main": "dist/index.js", // 入口文件 "types": "dist/index.d.ts", // 类型声明入口 "files": ["dist"] // 发布时包含的目录 } ``` ### 8. 发布到npm 注册npm账号并登录： ```bash npm login ``` 发布： ```bash npm publish ``` ### 9. 本地使用（不发布） 使用`npm link`： 在类型库目录： ```bash npm link ``` 在需要使用类型库的项目目录： ```bash npm link ts-types-library ``` ### 10. 在其他项目中引用 安装已发布的包： ```bash npm install ts-types-library ``` 在代码中使用： ```typescript import { User, UserPreview } from 'ts-types-library'; ``` ### 注意事项 - **版本管理**：每次更新后递增版本号，并重新发布。 - **类型扩展**：使用模块增强（`declare module`）扩展第三方库类型[^2]。 - **依赖管理**：如果类型依赖其他库，需在`package.json`的`dependencies`或`peerDependencies`中声明。 ### 示例：扩展第三方库类型 在类型库中创建`src/vue.d.ts`： ```typescript declare module 'vue' { interface ComponentCustomProperties { $myPlugin: () => void; } } ``` 然后在`src/index.ts`中导入： ```typescript import './vue'; ``` 这样使用该类型库的项目中，Vue实例就会包含`$myPlugin`属性。 ### 替代方案：Git子模块 如果不想发布到npm，可使用Git子模块： 1. 将类型库作为独立仓库 2. 在项目中添加子模块： ```bash git submodule add https://github.com/your-account/ts-types-library.git ``` 3. 配置项目中的`tsconfig.json`包含子模块路径： ```json { "compilerOptions": { "baseUrl": ".", "paths": { "ts-types-library": ["./ts-types-library/src"] } } } ``` ### 常见问题 1. **类型未更新**：确保项目重新安装依赖或重启TypeScript服务（VSCode中按Ctrl+Shift+P，输入"Restart TS Server"）。 2. **循环依赖**：避免类型库与项目间相互引用。 通过以上步骤，即可创建可复用的TypeScript类型库[^1][^2]。 §§相关问题§§ 1. 如何为TypeScript类型库编写单元测试？ 2. 如何管理类型库的版本兼容性？ 3. 如何扩展全局类型（如Window对象）？ 4. 类型库中如何引入第三方类型定义？</think>### 创建可共享的 TypeScript 类型库指南 #### 1. 创建独立类型库项目 ```bash mkdir shared-types && cd shared-types npm init -y npm install typescript --save-dev npx tsc --init ``` #### 2. 项目结构 ```markdown shared-types/ ├── src/ │ ├── user-types.ts # 用户相关类型 │ ├── api-types.ts # API接口类型 │ └── index.ts # 统一导出入口 ├── dist/ # 编译输出目录 ├── package.json └── tsconfig.json ``` #### 3. 配置关键文件 **tsconfig.json**: ```json { "compilerOptions": { "declaration": true, // 生成.d.ts类型声明 "declarationDir": "dist", // 类型输出目录 "rootDir": "src", // 源码目录 "outDir": "dist", // 编译输出目录 "module": "ESNext", // 模块系统 "target": "ES2019", // 编译目标 "moduleResolution": "node", "esModuleInterop": true, "strict": true }, "include": ["src/**/*"] } ``` **package.json** 关键配置: ```json { "name": "@yourname/shared-types", "version": "1.0.0", "main": "dist/index.js", "types": "dist/index.d.ts", // 类型声明入口 "files": ["dist"] // 发布包含的文件 } ``` #### 4. 编写类型定义 **src/user-types.ts**: ```typescript export interface User { id: number; name: string; email: string; createdAt: Date; } // 使用工具类型派生新类型[^2] export type UserPreview = Pick<User, 'id' | 'name'>; export type PartialUser = Partial<User>; ``` **src/index.ts** (统一导出): ```typescript export * from './user-types'; export * from './api-types'; ``` #### 5. 构建与发布 ```bash # 编译项目 npx tsc # 发布到npm npm publish --access public # 或使用本地引用 npm link # 在类型库目录执行 npm link @yourname/shared-types # 在消费项目中执行 ``` #### 6. 在其他项目中引用 ```typescript // 安装类型库 npm install @yourname/shared-types // 在组件中使用[^3] import { User, UserPreview } from '@yourname/shared-types'; const currentUser: User = { id: 1, name: "Alice", email: "[email protected]", createdAt: new Date() }; const preview: UserPreview = { id: currentUser.id, name: currentUser.name }; ``` #### 最佳实践 1. **语义化版本**：遵循 semver 规范，类型变更时升级次版本号 2. **类型测试**：使用 `tsd` 库验证类型定义 ```bash npm install tsd --save-dev ``` 3. **全局类型扩展**：在 `global.d.ts` 中添加全局类型 ```typescript declare global { interface Window { __APP_CONFIG__: Record<string, string>; } } ``` 4. **文档生成**：使用 TypeDoc 自动生成文档 ```bash npm install typedoc --save-dev npx typedoc --out docs src/ ``` #### 常见问题解决 **类型不生效**： 1. 确保消费项目的 `tsconfig.json` 包含类型库 ```json { "compilerOptions": { "typeRoots": ["./node_modules/@types", "./custom-types"] } } ``` 2. 重启 TypeScript 服务（VS Code 中执行 `>Restart TS Server`） **循环依赖**： - 使用 `import type` 语法避免运行时依赖 ```typescript import type { User } from './user-types'; ``` 通过这种方式创建的类型库，可在多个项目中保持类型一致性，提高开发效率和代码质量[^1][^2]。 --- ### 相关问题 1. 如何在类型库中处理第三方依赖的类型声明？ 2. 如何为类型库编写自动化测试？ 3. 使用 monorepo 管理类型库的最佳实践是什么？ 4. 如何实现类型库的按需加载？ 5. 类型库版本冲突时如何优雅降级？