

## 前言

有时候想写一下对需求的分析以及最后落地的过程, 这个处理需求的思路也是可以和大家交流一下的

因为自己有想做一些小demo项目, 在技术选型上的调整会导致每次都要初始化一个脚手架, 之前写过一个脚手架, 但是那个是基于vite、react、antd的场景, 很多其他场景可能技术栈并不一致

因此想做一个基于vite的上层 `轻量` 应用脚手架, 希望支持如下需求:

* 适用于react、vue、next项目

* 适用于monorepo、单应用项目

* 开发配置默认包含 eslint、prettier、lint-staged、husky 等常用配置

* 应用配置默认包含router、store、ts、组件库等

* 支持命令行初始化项目

* 易扩展, 后续对接新技术栈

配置如下:

| 技术栈          | 内置模块               | 可选模块                   |
| --------------- | ---------------------- | -------------------------- |
| monorepo、react | react-router、mobx、ts | antd、tailwindcss          |
| react           | react-router、mobx、ts | antd、tailwindcss          |
| monorepo、vue3  | vue-router、pinia、ts  | antd、element、tailwindcss |
| vue3            | vue-router、pinia、ts  | antd、element、tailwindcss |
| next            | ts                     | antd、tailwindcss          |

其实这个场景和 `create-vite` 一模一样, 因此也借这个机会学习一下 vite 怎么做的

## 初始化脚手架仓库

### vite脚手架

vite仓库是 `monorepo` 格式, 主要结构如下:

```bash
├── playground
|   ├── xxx			# 测试vite的工程
├── packages
|   ├── create-vite	# 初始化vite脚手架工程
|   ├── vite		# vite主要工程
```

具体看 `create-vite` 结构如下:

```bash
├── src
|   ├── index.ts    	# 入口文件
├── templates    		# 提供的vite模板集合
|   ├── template-react
├── package.json    	# 配置文件
```

使用到的依赖大致如下:

| 工具        | 作用               |
| ----------- | ------------------ |
| unbuild     | 打包工具           |
| cross-spawn | 跨平台执行node命令 |
| kolorist    | 命令行颜色输出     |
| minimist    | 解析命令行         |
| prompts     | 命令行交互         |

### hush-cli脚手架

下方参照vite脚手架的代码结构

首先创建这个脚手架仓库, 先命名为 `hush-cli` , 因为我这里不涉及多个仓库, 所以把 `create-hush-cli` 放在根目录, 目录结构如下

```bash
├── playground
|   ├── hush-cli  	# 测试脚手架项目
├── create-hush-cli	# 初始化脚手架工程
```

create-hush-cli 目录结构如下

```bash
├── index.js
├── templates
├── src
|   ├── index.ts
```

根目录安装 ts, create-hush-cli 目录中安装上述vite中的依赖

```bash
pnpm add typescript -D -w

pnpm add unbuild kolorist minimist prompts @types/minimist @types/prompts -F create-hush-cli
```

在 `create-hush-cli/package.json` 写下如下命令:

```json
{
	"bin": {
		"create-hush-cli": "index.js",
		"chc": "index.js"
	},
	"files": ["index.js", "templates", "dist"],
	"scripts": {
		"dev": "unbuild --stub",
		"build": "unbuild",
		"typecheck": "tsc --noEmit"
	}
}
```

unbuild 的 `stub` 配置会开启 stub 模式, 构建产物里将会使用 jiti 来做链接, 这样构建一次其他引用的地方会引用到最新代码, 相当于 `watch` 模式, 所以这里没有用 `tsc` 去运行 src/index.ts, 这里 `dev` 命令直接打包, 在 `playground` 中测试

在 `create-hush-cli/src/index.ts` 中写入如下内容

```ts
const getVersion = () => {
	console.log("version", "1.0.0");
};

getVersion();
```

执行 `pnpm dev` 命令, 会发现 create-hush-cli 根目录产生了一个dist文件夹, 这就是stub模式下打包的产物

![](/images/custom-vite-cli/vite-cli-2.png)

在 `playground` 目录中创建一个 hush-cli 文件夹, 用来测试初始化仓库, 执行如下命令:

```bash
pnpm add create-hush-cli

# 因为上述 bin 配置, 所以可以执行 chc
pnpm exec chc
```

会发现控制台打印出来了 `"version", "1.0.0"`

这里穿插介绍一下 `exec` , vite 初始化仓库命令为 `npm create vite`

```bash
npm create xxx
# 等同如下
npm exec create-xxx
```

当我们执行 create 命令时，会先补全包名为 create-xxx, 然后转换为 exec 命令执行，即 npm exec create-xxx; 接着执行包对应的 create-xxx 命令(package.json 的 bin 字段指定的命令)

所以我们需要发布一个 `create-hush-cli` 的npm包, 然后package.json中bin里边要提供 `create-hush-cli` 方法. 发布后即可通过如下方式安装

```bash
pnpm create hush-cli
```

了解 [pnpm exec](https://pnpm.io/zh/cli/exec/)

![](/images/custom-vite-cli/vite-cli-1.png)

修改一下 `getVersion` 方法返回值, 不用执行dev或者build命令, 直接继续执行 `pnpm exec chva` 会发现打印的是修改后的内容, 证明热更新成功

以上我的脚手架仓库创建好了, 后续开发流程为在 `create-hush-cli` 中添加脚手架模板, 执行 `pnpm dev` , 在 `playground` 中测试

## 命令行初始化项目

主要功能写在 `/src/index.ts` 中, 大致流程应该是:

1. 询问一些基本信息, 项目名、框架、依赖等

2. 根据用户选择的框架, 复制自己对应的项目模板过去

3. 修改项目模板中的依赖、配置等

### 命令行交互

因此开始我们的 `index.ts` 的编写

首先看下vite脚手架初始化时是什么流程:

在控制台输入 `pnpm create vite` , 展示如下一些信息

![](/images/custom-vite-cli/vite-cli-3.png)

提示让我们填写项目名, 且直接回车会填写默认值 `vite-project` , 继续往下, 发现一共是询问如下几个信息

![](/images/custom-vite-cli/vite-cli-4.png)

1. 询问项目名
2. 询问框架
3. 询问配置, (ts, swc等)

这里使用 `prompts` 插件完成交互, 用 `kolorist` 做样式输出

因此我们的 `index.ts` 代码如下(做下简化, 以防代码量太大):

```ts
import prompts from "prompts";
import { blue, cyan, green, magenta, red, reset, yellow } from "kolorist";

const init = () => {
	let result: prompts.Answers<
		| "projectName"
		| "overwrite"
		| "packageName"
		| "framework"
		| "cliType"
		| "variant"
	>;

	try {
		result = await prompts(
			[
				{
					type: "text",
					name: "projectName",
					message: reset("Project name:"),
					initial: "hush-project",
				},
				{
					type: "select",
					name: "framework",
					message: reset("Select a framework:"),
					initial: 0,
					choices: [
						{
							title: 'React',
							value: 'react'
						},
						{
							title: 'Vue',
							value: 'vue'
						}
					]
				},
			],
			{
				onCancel: () => {
					throw new Error(red("✖") + " Operation cancelled");
				},
			},
		)
	} catch (cancelled: any) {
		console.log(cancelled.message);
		return;
	}
}

init();
```

实际代码中这里会更加完善, 这里不做完整代码展示

1. 如果 `projectName` 文件夹名称已存在则提示文件夹已存在, 是删除原文件夹继续还是退出还是将之前Ignore掉再继续

2. 若 `projectName` 不符合 `package.json` 的name规范, 则需要输入package name

3. 选择对应的框架时后续展示的分支会有所不同, react中才有swc选项

因此上述第一步 `prompts` 流程完毕后, 我们获取到 `result` 信息, 接下来即可执行第二步初始化项目仓库了

### 初始化项目仓库

我们的模板都放在 `templates` 文件夹下, 该文件夹结构如下

```bash
├── templates    		# 提供的vite模板集合
|   ├── template-react
|   ├── template-react-mo
|   ├── template-vue
|   ├── template-vue-mo
|   ├── template-next
```

因此我们要根据用户选择的框架, 获取对应的模板文件夹, 然后复制到 `projectName` 文件夹中, 实现如下(简化版):

```ts
import path from "node:path";
import { fileURLToPath } from "node:url";

const cwd = process.cwd();

const root = path.join(cwd, result.projectName);

// 创建文件夹
fs.mkdirSync(root, { recursive: true });

// 获取目标路径
const targetPath = path.join(root);

// 获取模板文件夹(需要确保templates下已经存在该模板)
const templateDir = path.resolve(
	fileURLToPath(import.meta.url),
	"../../templates/",
	`template-${framework.name}`,
);

// 复制模板到目标路径
copy(templateDir, targetPath);
```

其中 copy 辅助方法如下:

```ts
function copyDir(srcDir: string, destDir: string) {
	fs.mkdirSync(destDir, { recursive: true });
	for (const file of fs.readdirSync(srcDir)) {
		const srcFile = path.resolve(srcDir, file);
		const destFile = path.resolve(destDir, file);
		copy(srcFile, destFile);
	}
}

function copy(src: string, dest: string) {
	const stat = fs.statSync(src);
	if (stat.isDirectory()) {
		copyDir(src, dest);
	} else {
		fs.copyFileSync(src, dest);
	}
}
```

测试一下, 建立一个 `templates/template-react` , 里边写入一个 `index.ts` 测试文件

再去 `playground/hush-cli` 下执行 `pnpm exec chc` , 该仓库上述已经建立过, 已经安装了 `create-hush-cli` , 所以可以直接执行 `pnpm exec chc`

效果如下:

1. 输入项目名
   ![](/images/custom-vite-cli/vite-cli-5.png)

2. 选择技术栈
   ![](/images/custom-vite-cli/vite-cli-6.png)

3. 选择仓库类型
   ![](/images/custom-vite-cli/vite-cli-7.png)

4. 选择依赖
   ![](/images/custom-vite-cli/vite-cli-8.png)

完成后会在 `playground/hush-cli` 下生成一个 `hush-project` 文件夹, 里边有 `index.ts` 文件

![](/images/custom-vite-cli/vite-cli-9.png)

至此通过命令行初始化项目可以了, 接下来做第三步修改项目模板中的一些配置等

### 修改项目模板配置信息

修改 `package.json` 中的项目名:

```ts
const targetPath = path.join(root);
const pkgPath = path.join(targetPath, `package.json`);
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));

pkg.name = result.packageName || result.projectName;

fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
```

接下来我们需要完善 `templates` 下的脚手架仓库

这里拿react脚手架做示例, 我们需要预安装如下插件:

| 插件名称         | 作用                |
| ---------------- | ------------------- |
| initialize-css   | 样式初始化          |
| mobx             | 状态管理            |
| tailwindcss      | 样式框架            |
| eslint           | 代码校验工具        |
| prettier         | 代码格式化工具      |
| lint-staged      | 暂存区代码处理工具  |
| husky            | git hook 工具       |
| commitlint       | git提交命令校验工具 |
| @hushaha/request | 请求工具            |

因此我们需要依次安装此些插件

代码目录结构如下:

```bash
|-- src
    |-- assets  	# 样式以及图片
    |-- components  # 基础组件
    |-- config      # 公共配置
    |-- features    # 业务组件
    |-- pages       # 路由对应页面
    |-- routers   	# 路由配置
    |-- stores      # 全局状态
    |-- types       # types
    |-- utils       # 工具库
    |-- App.tsx		# 主组件
    |-- main.tsx	# 入口文件
```

脚手架创建的具体流程可以查看这篇文章:
[vite-react-ts-cli](https://blog.hushaha.top/blog/vite-react-ts-cli)

`@hushaha/request` 库的使用方法可以查看这篇文章:
[q-request](https://blog.hushaha.top/blog/q-request)

## 链接

[create-hush-cli](https://github.com/hushaha/hush-cli.git)

[vite-git仓库](https://github.com/vitejs/vite.git)

[prompts官网](https://chinabigpan.github.io/prompts_docs_cn/)

[博客地址](https://blog.hushaha.top)

[q-request](https://blog.hushaha.top/blog/q-request)


自定义脚手架开发



## 前言

找个前端规范的最佳实践, 先从脚手架开始, 该脚手架只会提供最基础的功能, 上层功能还得继续封装

该脚手架支持如下功能:

1. tailwindCSS
2. react-router、mobx
3. error-boundary
4. eslint、prettier、commitlint、lint-staged

## 创建基础脚手架模版

1. 在node安装的情况下，本文用 `pnpm` 进行安装

   先执行如下命令

```bash
   pnpm create vite
```

选择 `template` 为 `react-ts`

2. 选择使用 `pnpm` 管理包工具，执行如下命令即安装依赖且启动项目服务

```bash
   pnpm i
   pnpm dev
```

3. 删除多余文件, 只保留 `main.tsx`、`App.tsx` 文件,并移除tsx文件中引用的各项依赖

```bash
|-- src
    |-- App.tsx     # 主组件
    |-- main.tsx    # 入口文件
```

将src文件夹下添加如下文件夹

```bash
|-- src
    |-- assets      # 样式以及图片
    |-- components  # 基础组件
    |-- config      # 公共配置
    |-- features    # 业务组件
    |-- pages       # 路由对应页面
    |-- routers     # 路由配置
    |-- stores      # 全局状态
    |-- types       # types
    |-- utils       # 工具库
    |-- App.tsx     # 主组件
    |-- main.tsx    # 入口文件
```

## 集成开发插件

开发环境支持配置如下:

1. 支持别名
2. 支持接口代理
3. 集成eslint、eslint-plugin-simple-import-sort, 支持格式化导入项
4. 集成prettier
5. 集成husky、commitlint、lint-staged等
6. 集成unplugin-auto-import, 自动导入常用api

### 配置alias

先安装 `@types/node`

```bash
pnpm add -D @types/node
```

编辑 `vite.config.ts` 文件

```ts
import { resolve } from "path";

export default defineConfig({
	resolve: {
		alias: {
			"@": resolve(__dirname, "./src"),
		},
		extensions: [".js", ".json", ".ts", "tsx"],
	},
});
```

编辑 `tsconfig.json` 文件, 添加如下配置

```ts
"compilerOptions":{
  "baseUrl": ".",
  "paths": {
    "@/*": ["./src/*"]
  }
}
```

### 配置proxy

编辑 `vite.config.ts` 文件, 这里根据自身需求来

```ts
server: {
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:8001',
        changeOrigin: false,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  },
```

### 集成eslint

vite 默认已经集成了eslint, 因此这里我先不做补充, 直接集成 `eslint-plugin-simple-import-sort`

```bash
pnpm add -D eslint-plugin-simple-import-sort
```

补充 `eslint.config.js` 文件:

```js
import js from "@eslint/js";
import globals from "globals";
import reactHooks from "eslint-plugin-react-hooks";
import reactRefresh from "eslint-plugin-react-refresh";
import tseslint from "typescript-eslint";
import simpleImportSort from "eslint-plugin-simple-import-sort";

export default tseslint.config({
    ignores: ["dist", "node_modules"]
}, {
    extends: [js.configs.recommended, ...tseslint.configs.recommended],
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
        ecmaVersion: 2020,
        globals: globals.browser,
    },
    plugins: {
        "react-hooks": reactHooks,
        "react-refresh": reactRefresh,
        "simple-import-sort": simpleImportSort,
    },
    rules: {
        ...reactHooks.configs.recommended.rules,
        "react-refresh/only-export-components": [
            "warn",
            {
                allowConstantExport: true
            },
        ],
        "simple-import-sort/imports": "error",
        "simple-import-sort/exports": "error",
    },
}, );
```

### 集成prettier

因为这里会使用 `tailwindCSS` , 所以先把 `tailwindCSS` 插件先一并装上

```bash
pnpm add -D prettier prettier-plugin-tailwindcss
```

根目录创建 `.prettierrc` 文件, 写入如下内容, 这里的规则可以自行修改, 我只提供一个示例

```json
{
	"useTabs": true,
	"tabWidth": 2,
	"printWidth": 100,
	"singleQuote": true,
	"trailingComma": "none",
	"bracketSpacing": true,
	"semi": true,
	"plugins": ["prettier-plugin-tailwindcss"],
	"tailwindConfig": "./tailwind.config.js"
}
```

### 集成提交三件套

提交三件套为 `husky` 、 `lint-staged` 、 `commitlint` , 主要是对提交时做文件校验以及提交文案校验

此时 husky 版本来到v9

```bash
pnpm add -D husky lint-staged @commitlint/cli @commitlint/config-conventional
```

修改 `package.json` 文件如下:

```json
{
	"scripts": {
		"prepare": "husky",
		"lint": "eslint .",
		"prettier": "prettier --write **.{tsx,ts,json}",
		"lint-staged": "lint-staged"
		// ...
	},
	"lint-staged": {
		"*.{js,ts,tsx,jsx}": ["pnpm eslint"],
		"*.{js,ts,tsx,jsx,css,less,scss}": ["pnpm prettier"]
	}
}
```

执行 `pnpm prepare` 命令, 会自动生成 `.husky` 文件夹, 里边手动创建 `commit-msg` 文件写入如下内容:

```bash
npx --no -- commitlint --edit \
```

手动创建 `pre-commit` 文件，写入如下内容:

```bash
pnpm lint-staged
```

根目录添加 `commitlint.config.js` 文件

```js
export default {
    extends: ["@commitlint/config-conventional"],
    // 以下时我们自定义的规则
    rules: {
        "subject-case": [0],
        "type-enum": [
            2,
            "always",
            [
                "bug", // 此项特别针对bug号，用于向测试反馈bug列表的bug修改情况
                "feat", // 新功能（feature）
                "fix", // 修补bug
                "docs", // 文档（documentation）
                "style", // 格式（不影响代码运行的变动）
                "refactor", // 重构（即不是新增功能，也不是修改bug的代码变动）
                "test", // 增加测试
                "chore", // 构建过程或辅助工具的变动
                "revert", // feat(pencil): add ‘graphiteWidth’ option (撤销之前的commit)
                "merge", // 合并分支， 例如： merge（前端页面）： feature-xxxx修改线程地址
            ],
        ],
    },
};
```

此时完成配置, 测试一下, 提交一个错误的文件提交

![](/images/vite-react-ts-cli/vite-react-cli1.png)

上述报错阻止提交成功, 证明lint-staged 配置成功

继续测试提交一个正确的文件, 但是 commit 语句不规范, 按照 `git commit -m "123"` 提交

![](/images/vite-react-ts-cli/vite-react-cli2.png)

此时也报错, 提示没有 subject 以及 type, 因此补充完整结构再次提交, `git commit -m "feat: init"` , 此时成功提交

![](/images/vite-react-ts-cli/vite-react-cli3.png)

### 集成自动引入api

使用 `unplugin-auto-import` 插件

```bash
pnpm add -D unplugin-auto-import
```

修改 `vite.config.ts` 文件

```js
import AutoImport from "unplugin-auto-import/vite";

export default defineConfig({
    plugins: [
        react(),
        AutoImport({
            imports: ["react", "mobx", "react-router", "react-router-dom"],
        }),
    ],
    // ...
});
```

编写 `app.tsx` 文件, 引入useState, 但不需要 import 语句, 重新 `pnpm dev`

发现根目录多了一个 `auto-imports.d.ts` 文件, 这个文件就是相当于ts类型声明文件, 将项目中用到的api类型从对应的插件中导入, 防止代码报错, 在编译时会自动引入对应的插件

这个文件需要在 `tsconfig.json` 中引入一下, 且不需要提交, 因此修改 `tsconfig.json` 文件 `include` 配置

```json
{
	"include": ["src", "src/vite-env.d.ts", "auto-imports.d.ts"]
}
```

在 `.gitignore` 中添加 `auto-imports.d.ts`

## 集成应用插件

### 集成react-router-dom

执行如下命令安装 `react-router-dom` , 此时 `react-router` 版本到了6

```bash
pnpm add react-router-dom
```

在 `routers` 文件夹下创建 `index.tsx` 文件，并写入

```tsx
import { createBrowserRouter, Navigate, RouterProvider } from 'react-router-dom';

const Home = lazy(() => import('@/pages/Home/index.tsx'));
const About = lazy(() => import('@/pages/About/index.tsx'));
const NotFound = lazy(() => import('@/features/NotFound/index.tsx'));

const routers = [
  {
		path: '/',
		element: <Navigate to="/home" replace={true} />
	},
	{
		path: '/home',
		element: <Home />
	},
	{
		path: '/about',
		element: <About />
	},
	{
		path: '*',
		element: <NotFound />
	}
];

const browserRouter = createBrowserRouter(routers);

const Routes = () => <RouterProvider router={browserRouter} />;

export default Routes;

```

其中 `About` 和 `Home` 为在 `pages` 中定义好的组件，内容随意

### 集成react-error-boundary

`react-error-boundary` 用来捕获组件错误

编辑 `app.tsx` 文件中写入如下代码

```tsx
import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';

import { ErrorFallback, Loading } from '@/features';

import Routes from './routers/index.tsx';

function App() {
	return (
		<>
			<Suspense fallback={<Loading />}>
				<ErrorBoundary fallback={<ErrorFallback />}>
					<Routes />
				</ErrorBoundary>
			</Suspense>
		</>
	);
}

export default App;
```

ErrorFallback, Loading 为 `features` 中的组件，具体可以自行定义内容

### 集成Mobx

引入 mobx 作为状态管理

```bash
pnpm add mobx mobx-react
```

在 `stores` 文件夹中创建 index.ts 文件 和 countStore.ts 示例文件

编写 countStore.ts 文件

```ts
import { action, makeObservable, observable } from 'mobx';

class CounterStore {
	constructor() {
		makeObservable(this, {
			count: observable,
			increment: action,
		});
	}

	count = 0;

	increment() {
		console.log(this);
		this.count++;
	}
}
export default new CounterStore();
```

在 `index.ts` 进行统一导出

```ts
import countStore from './countStore';

export { countStore };
```

### 集成tailwindcss

安装如下依赖:

```bash
pnpm add -D tailwindcss postcss autoprefixer
```

这里使用 iconify 中的 icon 组件, 因此继续安装如下两个插件, 如果你不用这个组件库可以忽略

```bash
pnpm add -D @iconify/json @iconify/tailwind
```

根目录新建文件 `tailwind.config.js` , 写入如下内容:

```js
const {
    addDynamicIconSelectors
} = require("@iconify/tailwind");

export default {
    content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
    theme: {
        extend: {},
    },
    plugins: [addDynamicIconSelectors()],
};
```

根目录新建文件 `postcss.config.js` , 写入如下内容:

```js
export default {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
};
```

在 assets/styles/index.css 顶部添加如下内容:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

该css应在 `main.tsx` 中被引用

此时 tailwindcss 已经集成完毕, 在 app.tsx 中测试一下

写入一个div类名

```tsx
function App() {
	return (
		<>
			<button className="rounded-md border px-5 py-2 hover:shadow-md">
				test
			</button>
			<button className="icon-[ep--menu]" />
		</>
	);
}

export default App;
```

展示效果如下:

![](/images/vite-react-ts-cli/vite-react-cli4.png)

`icon-[ep--menu]` 为 iconify 的图标, 可以在 [iconify](https://icon-sets.iconify.design/) 中找到

### 集成请求库

我这里使用的是自己封装的 `@hushaha/request` , 如果你使用axios或者fetch则可以跳过这里

```bash
pnpm add @hushaha/request
```

在 utils/request/index.ts 中添加如下代码

```ts
import { createRequest } from '@hushaha/request';

import { apis, APISchemaRes } from './schema';

const { apiList: http } = createRequest<APISchemaRes>(
	{
		baseURL: '/api'
	},
	apis
);

export { http };
```

在 utils/request/schema.ts 中添加如下代码

```ts
import type { APISchemaResponse, ApiSchemas } from '@hushaha/request';

export interface APISchemaRes extends APISchemaResponse {
	getUser: {
		request: {
			petId: string;
		};
		response: {
			code: number;
			data: {
				id: number;
				name: string;
			};
		};
	};
}

export const apis: ApiSchemas<APISchemaRes> = {
	getUser: {
		path: 'GET pet/:petId',
		headers: {
			'Content-Type': 'application/json'
		}
	}
};
```

此时即可在组件中通过如下方式调取接口

```tsx
import { http } from '@/utils';

const getUserData = async () => {
  const res = await http.getUser({ petId: '1' })
}
```

## tips

这整篇文章代码量居多, 具体的每个插件更新迭代速度比较快, 大版本更新可能会导致使用方法有差异, 因此最好的方式是知道自己想要什么, 然后针对性去看对应文档的使用方法, 再逐步集成

主要常用的插件如上方介绍, 如果有新的好使的插件可以自行封装进去, 至于其他的技术栈脚手架, 道理都是一样的, 主要分为开发插件及应用插件, 开发插件大同小异, 应用插件按照业务场景来, 因此无论是 next、vue、monorepo仓库等, 都可以参照这个流程进行封装

这个脚手架已经集成到我的 hush-cli 脚手架中, 可以通过如下命令快速创建

```bash
pnpm create hush-cli
```

hush-cli 就是一个基于vite二次封装的脚手架库, 把常用的插件封装进去了, 后续会继续补充更多插件类型以及使用示例, 可以向我提 issues 一起维护

## 参考

[博客地址](https://blog.hushaha.top)

[q-request](https://blog.hushaha.top/blog/q-request)

[create-hush-cli](https://github.com/hushaha/hush-cli.git)

[iconify](https://icon-sets.iconify.design/)

[tailwindcss](https://www.tailwindcss.cn/)


vite-react脚手架搭建



## 前言

说一个场景

我们现在需要写一个组件库, 还需要写一个工具库, 而这个组件库依赖于工具库, 这两个库更新频率会比较高, 我希望这两个库可以分开发布. 因为写的是库, 所以我们还需要有一个示例仓库来放使用用例, 这个使用示例我们也需要同步更新且部署

因此问题来了, 我怎么在一个项目里边引用另一个库, 且快速更新发布对应的库

**方案1: 笨方法**

正常情况下我们只能启动一个项目, 将另外个项目作为依赖引入, 但如果依赖更新了, 这边也需要同步拉取最新的依赖, 这样会涉及到这个依赖需要一直发布, 或者一直本地替换依赖, 会比较麻烦

**方案2: 软链接**

高级些的做法可以是我们将依赖在本地通过软链接的方式连接起来, 具体操作如下:

将项目结构定为如下结构

```bash
├── packages
|   ├── components
|   ├── utils
```

在 `components` 目录下执行如下命令:

```bash
pnpm add ../utils
```

此时则会将utils的代码软链接到 `components` 的 node_modules 中, 且 package.json 中会添加如下依赖 `utils: "link:../utils"` , 此时在项目中可直接用 `utils` 提供的方法

**方案3: monorepo**

有个解决方案叫做 `monorepo` , 将多个项目或包文件放到一个git仓库来管理, 其中的依赖也是用软链接的形式进行相互依赖

`monorepo` 仓库大致如下文件夹结构:

```bash
├── apps
|   ├── docs
├── packages
|   ├── pkg1
|   ├── pkg2
├── package.json
```

文件名称可以自定义, 我这里使用的是 `apps` 下放置示例项目或者文档, `packages` 中放置组件库、工具库等, 每个pkg都是单独的一个项目

此时我们可以定义这整个仓库为一个 `monorepo` 仓库, `apps` 和 `packages` 文件夹下的项目都是该仓库下的项目

`pnpm` 默认支持 `monorepo` , 也可以使用 `lerna` 进行管理

下方介绍以pnpm进行管理

## 创建monorepo仓库

1. 创建一个空文件夹并执行如下命令

```shell
pnpm init
```

2. 调整 `package.json`

* 添加 `engines`, 指定node、pnpm最低版本

* 设置 `private` 属性为 `true`, 防止当前仓库整体被发布

* 添加 `workspaces`, 指定当前仓库为 monorepo 格式

```json
{
	"private": true,
	"engines": {
		"node": ">=16",
		"pnpm": ">=7"
	},
	"workspaces": ["packages/*", "apps/*"]
}
```

3. 根目录添加 `pnpm-workspace.yaml` 文件, 配置 `monorepo` 仓库信息

```yaml
packages:
  - 'packages/*'
  - 'apps/*'
```

4. 根目录添加 `.npmrc` 文件, 填写如下内容

> 如不做这一步可能导致子模块安装子模块时只从远端安装, 不从本地安装依赖

```bash
link-workspace-packages = true 		# 启用工作区内部的包链接
prefer-workspace-packages = true 	# 优先选择工作区中的包
recursive-install = true 			# 递归地安装工作区中所有项目的依赖
```

## 初始化子仓库

我希望建立一个components组件库, 一个utils工具库, 一个doc文档库, 
这个doc文档库展示当前最新的组件和工具方法

这里我以如下仓库结构作为示例:

```bash
├── apps
|   ├── docs
├── packages
|   ├── components
|   ├── utils
├── package.json
```

因为用了 `monorepo` 格式, 所以证明我们应该会发布多个包, 因此应该用统一个命名前缀, 假设我们这里使用 `@hush` 作为前缀

### 初始化components

在 `packages` 目录下创建文件夹 `components` , 进入目录执行如下命令

```bash
pnpm create vite
```

创建完成后进入 `components/package.json` 文件中  
调整包名为 `@hush/components` , 删除 `devDependencies` 项中的 `typescript` , 因为 `ts` 将会在我们各个仓库中用到, 因此可以将公共依赖放到根目录安装

到根目录执行如下命令:

```bash
pnpm add typescript -D -w
```

`-w` 参数用来确认是在根目录安装该依赖

### 初始化utils

在 `packages` 目录下创建文件夹 `utils` , 进入目录执行如下命令

因为 `ts` 已经挪到根目录, 所以不需要安装 `typescript` , 可以直接用ts, 执行如下命令:

```bash
pnpm init -y

npx tsc --init
```

这个仓库我只放一些公共方法, 所以不需要什么脚手架

创建文件夹结构如下:

```bash
├── utils
|   ├── src
|   |   ├── index.ts
|   ├── test
|   ├── package.json
```

package.json文件修改如下:

```json
{
	"name": "@hush/utils",
	"version": "1.0.0",
	"private": false,
	"files": ["dist", "README.md"],
	"types": "./dist/index.d.ts",
	"main": "./dist/index.js",
	"module": "./dist/index.js",
	"exports": {
		"./*": "./*",
		".": {
			"types": "./dist/index.d.ts",
			"import": "./dist/index.js",
			"require": "./dist/index.js"
		}
	},
	"scripts": {
		"build": "tsc"
	}
}
```

`tsconfig.json` 配置文件中添加如下配置:

```json
{
	"rootDir": "./src",
	"outDir": "./dist",
	"declaration": true
}
```

配置 `src/index.ts` 添加一个示例方法

```ts
// index.ts
export const getVersion = () => {
	return 'V1.0.0'
}
```

此时即可执行 `pnpm build` 打包, 打包结果会放到 `dist` 目录下

### components使用utils包

先进入utils目录下执行命令

```bash
pnpm build
```

进入components目录下执行命令

```bash
pnpm add @hush/utils

// or 在根目录执行如下命令
pnpm add @hush/utils -F @hush/components
```

成功后可以看到 `components` 项目 `package.json` 文件中 `dependencies` 项中添加了 `"@hush/utils": "workspace:^",` , 
这个版本为 `workspace:^` 指的就是从本地取对应的依赖, 因此对应的依赖也需要先打包才行

此时可以看到 `components` 项目中的 `node_modules` 里的 `@hush/utils` 目录结构和项目代码一致, 是因为 monorepo 架构就是将本地依赖以软链接的形式引入

![](/images/create-monorepo-cli/code-catalog.png)

### 测试

在 `components` 项目中引用 `@hush/utils` 包中的方法, 按理说已经有ts类型提示, 访问页面确认方法正常执行即可

## 构建

根目录 `package.json` 添加如下命令:

```json
{
	"script": {
		"dev": "pnpm --filter=./apps/* --parallel dev",
		"dev:lib": "pnpm --filter=./packages/* --parallel dev",
		"build": "pnpm --filter=./apps/* build",
		"build:lib": "pnpm build:utils && pnpm build:components",
		"build:components": "pnpm build --filter=./packages/components",
		"build:utils": "pnpm build --filter=./packages/utils"
	}
}
```

 `--filter`

过滤出匹配到的项目

 `--parallel`

这是个推荐的标志, 用于在许多 packages上长时间运行的进程, 例如冗长的构建进程

 `build:lib`

 因为 components 依赖于 utils , 所以先打包 utils, 否则可能导致 components 打包失败

## 安装其他依赖

上述过程中已经安装 `typescript` 到根目录, 接下来就需要安装其他依赖

遵循只要是各仓库通用的依赖则可提到根目录的要求, 开发环境所需要的 `eslint` 、 `prettier` 、 `lint-staged` 、 `husky` 等依赖均可挪到根目录安装, 因此这些不在这里赘述操作, 详情可以看这里

[vite-react-ts-cli脚手架搭建](/blog/vite-react-ts-cli)

## Tips

1. 软链接和monorepo的区别

* `npm link`

**优点:**  
方便调试: 开发者可以在一个项目中修改库的代码, 然后立即在另一个项目中看到效果, 无需重新打包发布
节省时间: 不需要频繁地发布到 npm 仓库以进行测试

**缺点:**  
可能的不一致性: 如果多个项目链接到了同一个模块的不同版本, 可能会导致行为上的不一致
复杂性: 对于大型团队或项目, 跟踪哪些模块被链接以及它们的状态可能会比较困难
跨平台问题: npm link 在不同操作系统上可能有不同的表现, 尤其是在 Windows 上

* `monorepo`

**优点:**  
依赖一致性: 所有项目使用相同的依赖版本, 减少了版本冲突的可能性
易于协作: 项目之间更容易共享代码和资源, 简化了开发流程
简化依赖管理: 可以更有效地管理内部依赖关系, 减少外部依赖的使用

**缺点:**  
构建时间: 单一仓库可能导致构建时间变长, 因为所有项目都需要一起构建
复杂性: 大型 Monorepo 可能难以维护, 特别是在没有适当的工具和策略的情况下
初始设置成本: 设置 Monorepo 需要一定的前期投入, 比如选择合适的工具(如 Lerna, Yarn, Pnpm等)和配置
