create-vst v2.1.1
create-vst
create-vst
是前端项目起手模版的脚手架工具,用于快速创建一个基于 vue
+ typescript
+ vite
的前端项目。
如何使用
兼容性提示: create-vst 要求 Node.js 版本 >= 14.18.0,在使用之前请确保正确的 Node 版本。
使用 npm:
$ npm create vst
使用 yarn:
$ yarn create vst
使用 pnpm:
$ pnpm create vst
然后根据提示输入项目名称即可创建一个新的项目。
你也可以直接指明项目名称,这样就免去了输入项目名称的步骤,运行如下命令:
$ npm create vst my-project
如果你想在当前目录创建一个新的项目,可以使用 .
作为项目名称:
$ npm create vst .
注意:如果使用 .
作为项目名的话,需要确保当前目录为空,否则会报错。
功能
vst(vue starter template) 是在 create-vue 初始化模版的基础上进行的二次开发,主要增加了以下功能:
- 模版基于 Vue3 和 Vite4
- TypeScript 支持
- 基于文件的路由系统
- 布局系统
- 组件自动化引入
- Iconify 图标按需引入
- 使用 Pinia 作为状态管理工具
- 使用 Vitest 进行单元测试
- 使用组合式 API 开发
- 使用新的
<script setup>
语法 - 支持 jsx/tsx
- 集成 vueuse 组合式函数工具集
- tailwindcss,实用工具优化的 CSS 框架
- axios 的请求响应拦截
- vue-request Vue 组合式函数的请求库
- 切换路由时进度条显示
- 以命令行的形式快速生成页面、组件和布局模版文件
- eslint 代码检查、prettier 代码格式化。提交代码前自动格式化代码
项目结构
环境变量
├── .env # 公共环境变量,所有环境都会加载
├── .env.development # 开发环境变量
├── .env.gray # 灰度环境变量
├── .env.production # 生产环境变量
├── .env.test # 测试环境变量
├── .env.mock # mock 环境变量
注意:环境变量应以 VITE_
开头,如 VITE_BASE_URL
。
配置完环境变量以后,在 env.d.ts
中添加对应的类型声明,以得到更好的类型支持,如:
interface ImportMetaEnv {
/**
* 接口请求的 base url
*/
VITE_BASE_URL: string
/**
* 静态资源的 public path
*/
VITE_PUBLIC_PATH: string
}
公共组件
写在 components 里面的组件,会自动按需引入,无需手动引入。
├── src
│ ├── components # 公共组件
│ │ ├── Button # 按钮组件,支持 tsx 组件
│ │ │ └── index.tsx
│ │ ├── DarkSwitch # 切换主题组件
│ │ │ └── index.vue
│ │ ├── __tests__ # 组件单元测试,文件名与组件文件名一致
│ │ │ └── DarkSwitch.spec.ts # 切换主题组件单元测试
│ │ └── icons # 图标组件,一些 svg 图标可以放在这里,以 Icon 开头
│ │ └── IconNotFound.vue
公共组合函数
一些可以复用的公共组合函数放在 src/composables
文件夹下,以 use
开头命名。
├── src
│ ├── composables # 公共组合函数
│ │ ├── useGoBack.ts # 返回上一页
│ │ └── useLocalStorage.ts # 本地存储
布局系统
布局组件放在 src/layouts
文件夹下,插件会自动识别里面的内容。
├── src
│ ├── layouts
│ │ ├── base.vue
│ │ └── default.vue
使用布局系统,可以在 src/layouts
文件夹下创建一个布局组件,然后在 src/pages
文件夹下创建一个页面组件,页面组件的内容会被插入到布局组件的 <router-view />
中。
页面组件 .vue
文件需加上 route
标签并配置 layout
属性,指定使用的布局组件。
<route lang="yaml">
meta:
layout: base
</route>
第三方包
第三方包放在 src/libs
文件夹下,封装成 Vue 插件的形式再引入到 src/main.ts
中。
├── src
│ ├── libs # 第三方包
│ │ ├── axios # axios 封装
│ │ │ ├── index.ts # axios 入口文件,设置超时时间和 base url
│ │ │ ├── interceptors.request.ts # 请求拦截器
│ │ │ └── interceptors.response.ts # 响应拦截器
│ │ ├── nprogress # nprogress 封装
│ │ │ ├── index.css # 进度条样式
│ │ │ └── index.ts # nprogress 配置
│ │ └── vue-request # vue-request 封装
│ │ └── index.ts # vue-request 配置
一般来说,使用第三方库或 sdk 需要进行一些配置,然后再为应用所用。对于这样的包我们都可以将它们封装成 Vue 插件的形式放在 src/libs
文件夹中,然后在 src/main.ts
中引入。
sdk -> 个性化配置 -> Vue 插件 -> 在应用中使用
文件式路由
路由将会根据 src/views
里面的 .vue
文件和 .tsx
文件自动生成,不需要手动配置。
基础路由
页面会自动将你的页面目录中的文件映射到同名的路由中。
src/pages/users.vue
->/users
src/pages/users/profile.vue
->/users/profile
src/pages/settings.vue
->/settings
索引路由
名称为 index 的文件被当作路由的索引页。
src/pages/index.vue
->/
src/pages/users/index.vue
->/users
动态路由
动态路线用方括号表示。目录和页面都可以是动态的。
src/pages/users/[id].vue
->/users/:id (/users/one)
src/pages/[user]/settings.vue
->/:user/settings (/one/settings)
任何动态参数都将作为 props
传递给页面。例如,给定文件 src/pages/users/[id].vue
id 动态参数,将会在路由 /users/abc
中接收到 id
prop。
{ "id": "abc" }
嵌套路由
我们可以利用 vue-router 的子路由来创建嵌套式布局。父组件可以通过给它一个与包含子路由的目录相同的名字来定义。
例如有如下文件目录:
src/pages/
├── users/
│ ├── [id].vue
│ └── index.vue
└── users.vue
那么将会生成如下路由配置:
[
{
"path": "/users",
"component": "/src/pages/users.vue",
"children": [
{
"path": "",
"component": "/src/pages/users/index.vue",
"name": "users"
},
{
"path": ":id",
"component": "/src/pages/users/[id].vue",
"name": "users-id"
}
]
}
]
兜底路由
兜底路由用包含省略号的方括号来表示。
src/pages/[...all].vue
->/* (/non-existent-page)
省略号后面的文字将被用来命名路由,并作为传递路由参数的 props
的名称。
我们用 views/[...notFound].vue
来表示 404 页面,所有匹配不到的路由都会走到 404 页面。
图标
图标使用的是 unplugin-icon 插件,Iconify 的解决方案,可以在 Icônes 上寻找喜欢的图标。
然后直接用图标的名字做标签名即可,例如:
<carbon:sun />
快速创建样板代码
在开发项目时,我们经常需要创建一些样板代码,比如页面、组件、布局等,为了减少重复劳动,我们可以使用 npm run plop
命令来快速创建样板代码。
➜ npm run plop
> flow@0.0.0 plop
> plop
? [PLOP] Please choose a generator. (Use arrow keys)
❯ page - 在 views 文件夹下生成一个页面
component - 在 components 文件夹下生成一个组件
layout - 在 layouts 文件夹下生成一个布局组件
生成页面
➜ npm run plop
> flow@0.0.0 plop
> plop
? [PLOP] Please choose a generator. page - 在 views 文件夹下生成一个页面
? 请输入页面名称 home
? 请选择需要使用的布局 default
✔ ++ /src/views/home.vue
生成组件
➜ npm run plop
> flow@0.0.0 plop
> plop
? [PLOP] Please choose a generator. component - 在 components 文件夹下生成一个组件
? 请输入组件名称 Button
✔ ++ /src/components/Button/index.vue
生成布局
➜ npm run plop
> flow@0.0.0 plop
> plop
? [PLOP] Please choose a generator. layout - 在 layouts 文件夹下生成一个布局组件
? 请输入布局组件名称 test
✔ ++ /src/layouts/test.vue
修改模版文件
如果想修改样板代码的模版文件,可以在 plop-templates
文件夹下找到对应的模版文件进行修改。
├── plop-templates
│ ├── component.hbs
│ ├── layout.hbs
│ └── page.hbs
plopfile.mjs
文件为命令行脚本文件。
编码风格
eslint
eslint 使用的是 eslint-plugin-vue、@vue/eslint-config-prettier 和 @vue/eslint-config-typescript
prettier
prettier 使用的是 swayjs 的 prettier 配置 @swayjs/prettier-config
{
"printWidth": 100,
"tabWidth": 2,
"useTabs": false,
"semi": false,
"singleQuote": true,
"quoteProps": "as-needed",
"jsxSingleQuote": false,
"trailingComma": "all",
"bracketSpacing": true,
"bracketSameLine": false,
"arrowParens": "avoid",
"proseWrap": "never",
"endOfLine": "auto"
}
sfc 编码风格
使用 composition-api 和 <script setup lang="ts">
语法。
VS Code 扩展
- Vue Language Features(Volar) - script setup 支持
- TypeScript Vue Plugin(Volar) - typescript 支持
- Iconify IntelliSense - 图标内联显示和自动补全
- Prettier - 代码格式化
CheckList
在使用 VST 时建项目时,请检查以下的 CheckList 来更新您项目的信息。
- 在
index.html
中更新 title - 在
public
文件夹中更新favicon.ico
- 在
.env.test
、.env.gray
和.env.production
中配置请求接口的VITE_BASE_URL
- 在
.env.test
、.env.gray
和.env.production
中配置VITE_PUBLIC_PATH
- 和后端老师约定好接口返回值结构,更新响应拦截器
- 更新 README.md 并删除无用路由