ylyx-common

Monorepo 新增 Workspace 包流程

本文档记录在 vue-vben-admin monorepo 中新增 workspace 包的完整流程。

1. 创建包目录结构

在 packages/ 目录下创建新包：

packages/
└── ylyx-common/
    ├── package.json
    ├── tsconfig.json
    └── src/
        ├── index.ts          # 入口文件
        ├── index.d.ts        # 类型声明（可选，用于复杂导出）
        └── shims-vue.d.ts    # Vue 组件类型声明（包含 Vue 组件时需要）

2. 配置 package.json

{
  "name": "ylyx-common",
  "version": "1.0.0",
  "license": "MIT",
  "type": "module",
  "sideEffects": [
    "**/*.css"
  ],
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "default": "./src/index.ts"
    }
  },
  "dependencies": {
    "vue": "catalog:"
  }
}

关键配置说明：

字段	说明
name	包名，可以是 @vben/xxx 或 xxx
type: "module"	使用 ESM 模块
exports	定义包的入口点，types 指向类型文件，default 指向源码
catalog:	使用 pnpm-workspace.yaml 中定义的版本
workspace:*	引用其他 workspace 包

3. 配置 tsconfig.json

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "extends": "@vben/tsconfig/web.json",
  "include": ["src"],
  "exclude": ["node_modules"]
}

extends 选择：

基础配置	适用场景
@vben/tsconfig/web.json	包含 Vue 组件的包
@vben/tsconfig/library.json	纯 TS/JS 工具库

4. 创建 shims-vue.d.ts（包含 Vue 组件时）

declare module '*.vue' {
  import type { DefineComponent } from 'vue';

  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, any>;
  export default component;
}

5. 创建入口文件 src/index.ts

// 导出工具函数
export * from './utils';

// 导出 Vue 组件
export { default as MyComponent } from './components/MyComponent.vue';

6. 创建类型声明 src/index.d.ts（可选）

当包含 Vue 组件的复杂导出时，需要显式声明类型：

import type { DefineComponent } from 'vue';

// 导出函数类型
export * from './utils';

// Vue 组件类型声明
export const MyComponent: DefineComponent<
  { prop1?: string },
  Record<string, never>,
  unknown
>;

7. 在应用中添加依赖

编辑 apps/intelligent-compression/package.json：

{
  "dependencies": {
    "ylyx-common": "workspace:*"
  }
}

8. 配置应用的 tsconfig.json 路径映射

编辑 apps/intelligent-compression/tsconfig.json：

{
  "compilerOptions": {
    "paths": {
      "#/*": ["./src/*"],
      "ylyx-common": ["../../packages/ylyx-common/src/index.ts"],
      "ylyx-common/*": ["../../packages/ylyx-common/src/*"]
    }
  }
}

注意：路径映射是必需的，因为 TypeScript 不会自动解析 workspace 包。

9. 安装依赖

在项目根目录运行：

pnpm install

这会自动链接 workspace 包。

10. 在应用中使用

import { createCrud, Pagination, RrOperation, Upload } from 'ylyx-common';

组件文档

CRUD 组件

CRUD 相关组件和 hooks 的使用请参考代码注释和类型定义。

Upload 上传组件

详细的 Upload 组件使用文档请参考：Upload 组件文档

常见问题

Q: 报错 "Cannot find module 'xxx'"

原因：tsconfig.json 中缺少路径映射

解决：添加对应的 paths 配置

Q: 报错 "Module has no exported member 'xxx'"

原因：Vue 组件的类型没有正确声明

解决：创建 index.d.ts 显式声明 Vue 组件导出

Q: 运行时报错 "Failed to resolve import"

原因：Vite 无法解析 workspace 包

解决：

• 确保运行了 pnpm install
• 重启开发服务器

Q: 包的依赖版本如何管理？

答：

• 外部依赖使用 catalog: 引用 pnpm-workspace.yaml 中的版本
• 内部包使用 workspace:* 引用

目录结构参考

packages/ylyx-common/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts
    ├── index.d.ts
    ├── shims-vue.d.ts
    └── crud/
        ├── useCrud.js
        ├── useCrud.d.ts
        ├── CRUD.operation.vue
        ├── UD.operation.vue
        ├── RR.operation.vue
        └── Pagination.vue