# vue3-h5-template for Vue 3 Mobile Projects

> vue3-h5-template is a TypeScript-first Vue 3 starter for mobile web applications, with Vite, Vant, Pinia, viewport conversion, mocks, and release tooling already connected. It is most suitable when those defaults match your product rather than when you need a minimal or JavaScript-first scaffold.

**yulimchen/vue3-h5-template** — 🌱 A ready-to-use mobile project base template built with the Vue3, Vant, and Vite. | 基于 Vue3、Vite8、TypeScript/JavaScript、Tailwindcss、Vant4，开箱即用的移动端项目基础模板

- Repository: https://github.com/yulimchen/vue3-h5-template
- Website: https://yulimchen.github.io/vue3-h5-template/
- Stars: 1,550 · Forks: 342
- Language: Vue
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/yulimchen-vue3-h5-template

## What vue3-h5-template solves for mobile Vue teams

vue3-h5-template addresses the repetitive setup work involved in starting a mobile H5 application with Vue 3. It connects Vite 8, TypeScript, Vue Router 4, Pinia, Vant 4, Tailwind CSS, Axios, and several project conventions before an application has its first business feature. The intended audience is a frontend developer who wants a mobile-oriented Vue base rather than a generic single-page application scaffold.

The choices are relatively opinionated. Vant supplies mobile interface components, `cnjm-postcss-px-to-viewport` converts selected pixel dimensions for a 375-pixel design reference, and Pinia provides application state management. Vue Router includes component caching behavior, while Axios is wrapped for project use. Development also supports Mock data, a mobile debug panel, TypeScript checking, ESLint, Husky, and conventional commit validation.

That scope makes the template useful for teams that would otherwise assemble the same tools independently. It also means the starter is not minimal. A developer who needs only Vue and Vite will inherit routing, state management, UI components, styling utilities, environment configuration, and release conventions that may never be used. Projects centered on desktop layouts, native mobile containers, or server-rendered applications should treat this repository as one possible starting point rather than a default fit.

## The Vite, Vue, routing, and state architecture

The application follows the standard Vue single-page structure visible in the repository. Vue components are built through Vite, while `vue-router` owns page navigation. Views live under `src/views`, and route definitions are maintained separately in `src/router/routes.ts`. Route metadata supplies page titles, and a global router guard calls `setPageTitle(to.meta.title)` before navigation continues.

The template enables caching for route components by default. A route can opt out by setting `meta.noCache` to `true`. For a cached page, the Vue component name must exactly match its route name. The documented example uses `About` in both places, which prevents a mismatch between router records and component identity.

Pinia is included for shared state, while Axios is packaged as a project-specific HTTP layer rather than used directly throughout the examples. This gives an application recognizable places for shared state and remote requests. The repository also includes Mock configuration under `mock`, although the README refers to the external `vite-plugin-mock-dev-server` documentation for endpoint behavior instead of documenting the complete data flow in this repository.

On the styling side, the template combines Vant components with Tailwind utility classes and a viewport conversion plugin. The conversion settings establish a 375-pixel reference width, ignore values below one pixel, and preserve two decimal places. That combination is convenient for conventional mobile mockups, but it creates an explicit design constraint that may not fit responsive desktop layouts or products designed around a different viewport model.

## Installing the default TypeScript branch and starting Vite

The default `master` branch uses TypeScript. The README and `package.json` require Node 20 or newer and pnpm 9 or newer. The documented setup also suggests using `nvm` for local Node version management. Clone the repository, install the locked dependencies with pnpm, and start the Vite development server.

```bash
git clone https://github.com/yulimchen/vue3-h5-template.git
cd vue3-h5-template
pnpm install
pnpm dev
```

Vite then starts the development service and prints its local address in the terminal. The project also loads development Mock data from the `mock` directory and can inject the Eruda mobile debug panel when `.env.development` enables it. The online preview is configured for mobile browser emulation, so a desktop browser should use its device mode when inspecting the documented preview.

If the application needs JavaScript rather than TypeScript, the README directs users to the `js-version` branch. That branch must be cloned explicitly:

```bash
git clone -b js-version https://github.com/yulimchen/vue3-h5-template.git
cd vue3-h5-template
```

After switching branches, run `pnpm install` and `pnpm dev` as in the main setup. Do not assume that changing branch names is equivalent to converting the default TypeScript source tree to JavaScript; the README presents `js-version` as a separate template branch.

## Using the i18n branch and first mobile page

Internationalization is documented through a dedicated `i18n` branch. The main README also lists i18n support among the template features, but its explicit branch-selection instruction says to use the `i18n` branch for multilingual projects. For predictable setup, clone that branch rather than trying to infer which locale files belong in `master`.

```bash
git clone -b i18n https://github.com/yulimchen/vue3-h5-template.git
cd vue3-h5-template
pnpm install
pnpm dev
```

A first concrete modification can follow the documented route-caching pattern. The route below imports an About page and disables its cache. The exact page title is Chinese in the documented example, and the dynamic title mechanism displays it through `setPageTitle`:

```typescript
const routes: Array<RouteRecordRaw> = [
  {
    path: 'about',
    name: 'About',
    component: () => import('@/views/about/index.vue'),
    meta: {
      title: '关于',
      noCache: true
    }
  }
]
```

The component must use the same `About` name. The documented Vue implementation is:

```vue
<script setup lang="ts">
defineOptions({
  name: 'About'
})
</script>

<template>
  <div>about</div>
</template>
```

This first use demonstrates a project-specific rule that is easy to miss: route caching depends on consistent naming between the router configuration and the Vue component.

## Vant, Iconify, viewport conversion, and environment trade-offs

Vant components are loaded on demand through `unplugin-vue-components`, avoiding a deliberate full-library import. Icons support three paths: Iconify API requests, offline Iconify packages, and local SVG files. The simplest API-based usage passes an icon name directly to the wrapper:

```vue
<i-icon icon="fa6-solid:heart" />
```

That method depends on the Iconify API. For an internal or offline deployment, the README instead gives this package installation command:

```bash
pnpm i -D @iconify-icons/fa6-solid
```

The icon data is then imported directly:

```ts
import Fa6SolidHeart from '@iconify-icons/fa6-solid/heart'
```

```vue
<i-icon :icon="Fa6SolidHeart" />
```

Local SVG assets follow a different convention. Files belong in `src/icons/svg`, and the filename is passed through `name`, for example `svg-icon name="check-in"`. These options matter because an online API choice can become an operational dependency in an offline product.

Viewport conversion is configured in `postcss.config.js`. Values at or above the configured minimum are transformed according to the 375-pixel reference width, while autoprefixing targets Android 4.0 and later and iOS 7 and later. This is a deliberate mobile baseline, not a general responsive design solution.

Environment behavior also changes between development and production. Eruda is controlled by `VITE_ENABLE_ERUDA` in `.env.development`. Production CDN loading is controlled by `VITE_CDN_DEPS` in `.env.production`; although the template lists CDN dependencies, the README states that production CDN loading is disabled by default and must be enabled through that setting.

## Maintenance, quality checks, and a leaner Vue alternative

The repository is not archived, and the last push was on 2026-06-09. Release records include `v0.9.0` on 2026-05-16, `v0.8.5` on 2026-03-04, and `v0.8.4` on 2026-02-12. This indicates recent template revisions around the v0.x line, not a stable 1.0 release contract. Upgrade cost therefore includes reviewing the starter's conventions and dependencies rather than only copying application code.

The template provides concrete maintenance commands. `pnpm build` runs the Vite build and TypeScript check through the `build` script. `pnpm lint` checks ESLint rules, `pnpm lint:fix` applies fixes, and `pnpm preview` serves the production output locally. Husky and Commitlint enforce the documented conventional commit format, such as `feat(layout): 布局完成`. Projects that do not want these repository-wide conventions will need to remove or revise them.

A real alternative is to begin with the official Vue Vite scaffold and add only the libraries the product uses. That approach starts with less opinionation and avoids inheriting Vant, Pinia, viewport conversion, Mock data, Eruda, CDN behavior, and commit enforcement. The trade-off is that mobile setup becomes the application's responsibility. vue3-h5-template is the better fit when its mobile defaults are shared project policy; a minimal official scaffold is easier to tailor when component library, state model, viewport strategy, and release tooling are still unresolved.

The MIT license permits reuse and modification under its terms, but adopters should retain the required license and notice files and review the complete `LICENSE` text themselves. The repository's tooling also creates an upgrade obligation: Tailwind CSS 4, Vue 3.5, Vite-related plugins, TypeScript checking, and mobile viewport dependencies all need compatibility review when the template advances.

## Conclusion

Adopt this template when the next project is a mobile Vue 3 application and its Vant, TypeScript, Pinia, viewport, and commit tooling choices are acceptable. Do not adopt it unchanged if the product is primarily a desktop application, requires JavaScript on the default branch, or cannot tolerate a broad set of preinstalled conventions. Verify the Node and pnpm versions first, then inspect the generated routes, environment files, Axios wrapper, mock endpoints, and `postcss.config.js` before committing a new product to this structure.

## FAQ

### Which Node.js and pnpm versions does vue3-h5-template require?

The README requires Node 20 or newer, while `package.json` specifies Node `>= 20` and pnpm `>= 9`.

### How do I use JavaScript instead of TypeScript in vue3-h5-template?

The default `master` branch uses TypeScript. Clone the `js-version` branch to start from the JavaScript version, then run `pnpm install` and `pnpm dev`.

### Where does vue3-h5-template place internationalization support?

The README directs projects that require i18n to clone the `i18n` branch. It does not provide a detailed locale-file tutorial in the documented setup section.

## Sources

- [License: MIT](https://github.com/yulimchen/vue3-h5-template/blob/master/LICENSE)
- [Project website](https://yulimchen.github.io/vue3-h5-template/)
- [README](https://github.com/yulimchen/vue3-h5-template/blob/master/README.md)
- [Releases](https://github.com/yulimchen/vue3-h5-template/releases)
- [yulimchen/vue3-h5-template on GitHub](https://github.com/yulimchen/vue3-h5-template)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yulimchen-vue3-h5-template