opacitySun / tov-template

一个 vite + vue3 + ts 开箱即用现代开发模板

tov-template

一个 vite + vue3 + ts 开箱即用现代开发模板

特点 🐳

1. Vite 的
2. Vue3 的
3. 文件路由
4. 布局系统
5. Mock 支持
6. Api 自动引入
7. 组件自动引入
8. 图标自动引入
9. VueUse 支持
10. TypeScript 的
11. Windi CSS 的
12. 暗黑模式支持
13. SWR 请求支持
14. pinia 状态管理
15. pnpm 包管理器
16. 跳转进度条支持
17. Inspect 调试支持
18. 插件自动加载支持
19. Vitest 单元测试支持
20. 支持 Markdown 渲染
21. 路径别名 ~ 支持

使用 🐂

1. 安装依赖

pnpm install

2. 开发

pnpm dev 

3. 预览

pnpm preview

4. 打包

pnpm build

5. 单元测试

pnpm test

6. 单元测试报告生成

pnpm coverage

7. 样式报告预览

pnpm analysis

8. 样式报告打包

pnpm analysis:build

9. 类型检查

pnpm typecheck

动机 🐗

为什么要做这个 模板 呢？

1. 为下次开发节省浪费在配置上的时间
2. 结合主流插件整合现代开发架构，提高开发效率

使用场景 🐻

什么时候你应该用?

1. 不想浪费时间在项目配置上
2. 希望尝试用更现代的方式开发 web 应用，提高开发效率

启发 🐃

该模板受 vitesse 启发，如果你有 SSG 的场景，那么推荐你始终使用 vitesse。

组织 🦔

欢迎关注 帝莎编程

• 官网

• Gitee

• Github

• 网易云课堂

详情 🐳

1. Vite 的

该模板采用 vite 作为构建工具，你可以在根目录下的 vite.config.ts 对项目的构建进行配置。

对于众多主流插件的引入和繁杂配置已经整合到根目录下的预设 presets 中，大多数情况下你是不需要重新对它们进行配置的。

2. Vue3 的

3. 文件路由

目录结构即路由。

eg:

• src/pages/index.vue => /
• src/pages/about.vue => /about
• src/pages/users/index.vue => /users
• src/pages/users/profile.vue => /users/profile
• src/pages/users/[id].vue => /users/:id
• src/pages/[user]/settings.vue => /:user/settings
• src/pages/[...NoFound].vue => 404 路由

具体可见 👉 vite-plugin-pages

4. 布局系统

默认布局

src/layouts/default.vue 将作为默认布局。

<!-- src/layouts/default.vue -->
<template>
    我是默认布局
    <router-view /> <!-- 页面视图出口 -->
</template>

此时 src/pages/index.vue

<!-- src/pages/index.vue -->
<template>
    <div>我是首页</div> 
</template>

路由到 /时， 页面将渲染

我是默认布局
我是首页

此时 src/pages/about.vue

<!-- src/pages/about.vue -->
<template>
    <div>我是关于页</div> 
</template>

路由到 /about 时，页面将渲染

我是默认布局
我是关于页

非默认布局

随便创建一个 src/layouts/custom.vue

<!-- src/layouts/custom.vue -->
<template>
    我是非默认布局custom
    <router-view /> <!-- 页面视图出口 -->
</template>

此时 src/pages/index.vue 内

<!-- src/pages/index.vue -->
<template>
    <div>我是首页</div> 
</template>

<!-- 添加自定义块 👇 -->
<route lang="yaml">
meta:
  layout: custom
</route>

此时路由到 /, 页面将渲染

我是非默认布局custom
我是首页

具体可见 👉 vite-plugin-vue-layouts

5. Mock 支持

在根目录下的 mock 目录下，可以在模块中导出默认的 api 资源。

例如 mock/test.ts 内导出

import { MockMethod } from 'vite-plugin-mock'
export default [
    {
        url: '/api/get',
        method: 'get',
        response: () => {
            return {
                code: 0,
                data: {
                    name: 'vben'
                }
            }
        }
    }
] as MockMethod[]

在 src 中就可以进行模拟请求。

<script setup lang="ts">
    import { useRequest } from "vue-request"
    // 请求接口 /api/get
    const { data, loading, error } = useRequest('/api/get') 
</script>

<template>
    <div>data: {{data}}</div>
    <div>loading: {{loading}}</div>
    <div>error: {{error}}</div>
</template>

这里用到 vue-request 去做请求，不过因为该 mock 拦截的是一整个接口，所以换成 axios 等请求库也是可以的。

更多 mock 设置可见 👉 vite-plugin-mock

6. Api 自动引入

原本 vue 的 api 需要自行 import。

import { ref, computed } from 'vue'
const count = ref(0)
const doubled = computed(() => count.value * 2)

现在可以直接使用。

const count = ref(0)
const doubled = computed(() => count.value * 2)

而且上边的 api 是按需自动引入的。

目前模板支持自动引入 api 的库列表包括:

1. vue
2. pinia
3. vueuse
4. vue-router

7. 组件自动引入

原来需要 import

<!-- src/pages/index.vue -->
<script setup lang="ts">
    import Hello from "../components/Hello.vue"
</script>

<template>
    <Hello />
</template>

现在只要在 src/components 下定义的组件都将会按需引入，即 import 是不需要的。

<!-- src/pages/index.vue -->
<template>
    <Hello />
</template>

同时流行组件库自动引入也是支持的，例如 Naive ui。

只需安装依赖。

pnpm add naive-ui

即可在模板中使用。

<!-- src/pages/index.vue -->
<template>
    <n-button type="success">Success</n-button>
</template>

目前支持的组件库有:

• Naive ui
• element-plus
• @vueuse/components

具体可见 👉 unplugin-vue-components

8. 图标自动引入

可前往 👉 icones，随意选择点击进入其中一个图标库

再点击选择其中一个喜欢的图标

复制其名称

在模板中即可直接用组件的形式直接使用。

<template>
    <mdi:account-box-multiple />
</template>

保存后等待自动下载该图标库后，就可以在页面中看到对应图标。

同时推荐你使用 vscode 插件 Iconify IntelliSense。

该插件会在模板中显示图标的预览。就像这样 👇

<!-- 模板中代码 -->
<template>
    <mdi:account-box-multiple />
</template>

将在 vscode 中得到图标预览

具体可见 👉 unplugin-icons

9. VueUse 支持

VueUse 是一个超级强的 hooks 库，例如你要获取鼠标位置，只需要这样 👇

<script setup lang="ts">
    // useMouse 被自动按需引入了，不需要import
    const { x, y } = useMouse()
</script>

<template>
    <div>x坐标 {{x}}</div>
    <div>y坐标 {{y}}</div>
</template>

具体可见 👉 VueUse

10. TypeScript 的

不需要重新配置，直接用 ts 书写就行了。

11. Windi CSS 的

Windi CSS 是一个开发中速度更快的 原子css 库。

直接在模板中用就行了，不需要配置。

<template>
    <div class="bg-red-500 text-white">
        我是红色背景的白色文本
    </div>
<template>

上述模板将渲染红色背景白色的字。

同时支持 属性化模式，即可以用简写。

<template>
    <div text="white" bg="red-500">
        我是红色背景的白色文本
    </div>
<template>

这在调整边距尺寸以及等方面可以减少代码量。

同时预设 排版 插件，解决简单的布局困难问题。

当然也支持 可视化分析器 生成 原子css 报告.

在终端中输入命令，即可看到报告

pnpm analysis

或者打包输出该报告

pnpm analysis:build

具体可见 👉 Windi CSS

12. 暗黑模式支持

暗黑模式由 Windi CSS 的 暗黑模式 和 VueUse 实现。

src/composables 目录用来存储 composition-api 模块。

该目录下预设了dark 模块，该模块导出 isDark 和 toggleDark 用来显示和切换暗黑模式。

// src/composables/dark.ts

// vueuse的api会自动按需引入，无需import
export const isDark = useDark()
export const toggleDark = useToggle(isDark)

模板中即可直接用

<script setup lang="ts">
import { isDark, toggleDark } from "../composables/dark";
</script>

<template>
    <div m="6">
        Hello，This is the tov template！！
    </div>
    <div m="6" cursor="pointer" @click="toggleDark()">
        light: {{ isDark }} click me!!
    </div>
</template>

具体可见 👉 暗黑模式

13. SWR 请求支持

SWR 是更现代的请求方式，具体可见文章 👉 SWR。

而 vue-request 是一个 SWR 的 Vue 版本请求库。

你可以这样用，例如请求 /api/test

<script setup lang="ts">
    import { useRequest } from "vue-request"
    const { data, loading, error } = useRequest('/api/test')
</script>

<template>
    <div>data: {{data}}</div>
    <div>error: {{error}}</div>
    <div>loading: {{loading}}</div>
</template>

所有基本的数据，状态和缓存都帮你搞定了，不需要重新封装。

具体可见 👉 vue-request

14. pinia 状态管理

pinia 是下一代的状态管理库，比 vuex 更简单，ts 支持更好。

你可以在 src/stores 中进行状态的定义。

例如创建 src/stores/counter.ts 👇

// src/stores/counter.ts
import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => {
    return { count: 0 }
  },
  actions: {
    inc() {
      this.count++
    },
  },
})

定义完后在 setup 中直接使用即可

<!-- src/pages/index.vue -->
<script setup lang="ts">
    import { useCounterStore } from "../stores/counter"
    const Counter = useCounterStore()
<script>

<template>
    <div @click="Counter.inc">{{Counter.count}}</div>
</template>

更多具体使用可见 👉 pinia

15. pnpm 包管理器

pnpm 是非常优秀的包管理器，更快、更节省空间、更合理。

具体可见 👉 pnpm

16. 跳转进度条支持

跳转进度条由 nprogress 实现，可在src/styles/main.css 中调整配色。

/** src/styles/main.css **/

/** 省略其他样式 **/
#nprogress .bar {
    @apply bg-purple-700 bg-opacity-75; /** 配色 **/

    position: fixed;
    z-index: 1031;
    top: 0;
    left: 0;

    width: 100%;
    height: 2px;
}

关于 @apply 由 Windi Css apply 指令 实现。

具体可见 👉 nprogress

17. Inspect 调试支持

启动项目

pnpm dev

可以看到一个 url

先进入 http://localhost:3000，再进入 http://localhost:3000/__inspect/ 即可获得依赖图谱。

通过顶部的一些按钮还可以调整依赖呈现。

具体可见 👉 vite-plugin-inspect

18. 插件自动加载支持

该功能由 vite 的 Global 导入 实现。

只需要在 src/modules 中的模块里导出默认函数即可。

例如 pinia，只需要这样做。

// src/modules/pinia.ts

import { App } from 'vue'

// 导出 default 接口
export default (app: App) => app.use(createPinia())

或者 vue-router

// src/modules/router.ts

import { App } from 'vue'

// 省略各种配置

// 导出 default 接口
export default (app: App) => app.use(router)

当然 pinia 和 vue-router 已经预设好了，你不需要重新关注他们。

具体可见实现 👉 插件自动加载实现

19. Vitest 单元测试支持

在 src/test 目录中可以书写单元测试。

import { it, describe, expect, assert } from 'vitest'

describe('suite name', () => {
    it('foo', () => {
        expect(1 + 1).toEqual(2)
        expect(true).to.be.true
    })

    it('bar', () => {
        assert.equal(Math.sqrt(4), 2)
    })

    it('snapshot', () => {
        expect({ foo: 'bar' }).toMatchSnapshot()
    })
})

然后在终端中输入命令即可测试

pnpm test

或者生成报告

pnpm coverage

具体可见 👉 Vitest

20. 支持 Markdown 渲染

markdown 渲染可以用来书写一些简单的说明。

只需要把 src/pages 目录下的页面后缀由 .vue 改为 .md，然后再改为 markdown 语法即可。

例如 src/pages/about.md

## About Page

> The page is markdown file

当你路由到 /about 后即可看到对应的 markdown 渲染。

具体可见 👉 vite-plugin-md

21. 路径别名 ~ 支持

~ 路径将被导向项目的 src 目录。

<!-- src/pages/index.vue -->
<script lang="ts" setup>
    import { isDark, toggleDark } from "~/composables/dark"

// 等价于
// import { isDark, toggleDark } from "../composables/dark"
</script>