# Inside vue3-vant-mobile: file routing, a mock server on 8086 and mismatched version pins

> vue3-vant-mobile is a Vue 3 and Vite 8 template for mobile web apps that bundles Vant, UnoCSS, file based routing and a mock server on port 8086. Its README, its topic list and its package.json disagree with each other in several places, and two of those gaps matter before you copy the code.

**vue-zone/vue3-vant-mobile** — A mobile web app template based on the Vue 3 ecosystem, to help you build business features quickly.

- Repository: https://github.com/vue-zone/vue3-vant-mobile
- Website: https://vue3-vant-mobile.netlify.app
- Stars: 2,074 · Forks: 386
- Language: TypeScript
- License: MIT
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/vue-zone-vue3-vant-mobile

## What the template settles before you write app code

Opening a mobile web project on Vue 3 means answering a dozen questions before any business logic exists: router, store, UI kit, CSS engine, mock server, internationalisation, offline support, deploy target. vue3-vant-mobile answers them in advance. It pins Vue 3, Vite 8, pnpm, Vant and UnoCSS, then adds Vue Router, Pinia with `pinia-plugin-persistedstate`, Vue I18n, `vite-plugin-pwa`, vConsole through `vite-plugin-vconsole`, `vite-plugin-mock-dev-server` and `postcss-mobile-forever`, with Netlify as the deployment target. The audience is developers who already write Vue and want the plumbing finished: Vant is a kit built for mobile web apps, so this serves H5 work rather than desktop dashboards or server-rendered sites. Since the repository is a template you generate from rather than a package you add to `dependencies`, each of those choices lands in your own `package.json` on day one and stays there.

## File routing and auto import as the house style

The template's central convention is that you write less boilerplate than the compiler can see. Routes come from the filesystem under `src/router`, components under `src/components` are picked up without an import statement, and `unplugin-auto-import` injects Composition API helpers such as ref and computed into every module. `@vant/auto-import-resolver` extends the same trick to the UI kit, so a Vant component is usable by name in a template with no registration call. Translations sit alongside them in `src/locales`, wired through `@intlify/unplugin-vue-i18n`. What you give up is traceability. Because those imports are generated during the build, a text search for a component name will not reveal where it came from, and anyone reading the code without the matching editor extensions cannot follow the aliases across the boundary. That is why the recommended VS Code list pairs Goto Alias with Volar, and why the copied `src` tree is the first file worth reading in full rather than skimming.

## The alternative is assembling the same plugin list by hand

The realistic alternative is a bare Vue 3 project with the same packages added one at a time. That route gives you a shorter `package.json`, a different router major if you want one, no PWA plugin and no legacy bundle, and it avoids paying for chart and HTTP libraries you never import. What it costs is exactly the invisible half: filesystem routing conventions, the Vant resolver, a mock server wired to a port, a viewport transform, lint and commit hooks installed on `pnpm i`. Choose the template when the mobile case is the default and every line of that list matches your app. Assemble it by hand the moment one default is wrong, because every choice is a visible line you can delete rather than a build plugin you have to discover later. Once the copy exists, the difference between the two paths mostly disappears. Both leave the same code in your repository; only the blame history differs.

## The dev script pins the mock server to port 8086

Mock APIs are not optional here; the dev server brings them up before anything else. The dev script sets `MOCK_SERVER_PORT=8086` through cross-env and then runs Vite, while the fixtures live in `mock/` at the repository root and are served by `vite-plugin-mock-dev-server`. Because the port is written into the script rather than into an environment file, changing it means editing `package.json`, and the root files `.env`, `.env.development` and `.env.production` do not carry it. That is a defensible readability trade for a template, and it has one consequence worth knowing: `vite preview` runs with no mock server in front of it, so the bundle you check locally is calling whatever API the active build mode points at.

## Two Node floors and two versions of @unhead/vue

Two version conflicts sit inside the repository itself. The try-it section opens with the sentence that the template requires `Node 22.22.0+`, while `engines` in `package.json` demands `>=22.23.0`. The looser number sits in the prose readers see first, so a machine on 22.22.0 clears the documentation and then runs into the stricter value the package declares for itself. `.node-version` at the repository root is a third place to check, and the README does not quote its contents. The same slip repeats with the head manager, where the plugin list links `@unhead/vue v2` and `dependencies` pins `"@unhead/vue": "3.2.3"`. Neither mismatch is fatal on its own, and both cost a few minutes once you know they exist. Copy the project, then treat `engines` as the authority and the README floor as marketing copy.

## A wechat-h5 topic with no WeChat code behind it

The repository topics include `wechat-h5` alongside `h5`, `starter`, `unocss` and `vite-template`, yet nothing in the README or in the script list builds a WeChat environment, and no mini-program target appears among the package scripts. Read that topic as a label rather than a feature. A second gap runs the other way: `echarts`, `axios`, `lodash-es`, `nprogress` and `resize-detector` are installed as runtime dependencies, and none of them is named in the feature list or the pre-packed breakdown. You therefore inherit a charting library, an HTTP client and a resize observer with no note about which pages use them. The description string repeats the same kind of slip in both languages, since `An mobile web apps template based on the Vue 3 ecosystem` carries an article error that `package.json` copies into its `description` field unchanged.

## Cloning with tiged is a fork, not an install

Two acquisition paths exist: the GitHub template button, or tiged for what the README calls a cleaner git history. The manual route is three commands.

```bash
pnpm dlx tiged vue-zone/vue3-vant-mobile my-mobile-app # If you don't have pnpm installed, run: npm install -g pnpm
cd my-mobile-app
pnpm i
```

What follows is not an install. `pnpm i` runs the `prepare` script, `simple-git-hooks`, which installs the lint and commit hooks, and `commitlint --edit` with `commitlint.config.ts` lints the message you are writing. The repository carries an MIT licence and its last push was on 2026-07-31, so later upstream work reaches you by hand rather than through a dependency bump. The checklist that closes the try-it section asks you to change the author name in `LICENSE`, the page title in `index.html`, the hostname in `vite.config.ts` and the favicon in `public`, which confirms that a fresh copy arrives carrying the template's own values.

## vue-tsc guards every bundle while ESLint handles style

Type errors stop a build before Vite produces a bundle. Both build scripts run `vue-tsc --noEmit` first, and `typecheck` runs that command alone, so a mistake in a SFC surfaces on the command line instead of in a browser console. The two build modes differ only in the mode flag they pass, which means `.env.development` and `.env.production` decide the output, and the repository does not reveal which keys those files hold.

```json
    "build:dev": "vue-tsc --noEmit && vite build --mode development",
    "build:pro": "vue-tsc --noEmit && vite build --mode production",
    "typecheck": "vue-tsc --noEmit",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "preview": "vite preview"
```

Style is a separate pass: `eslint .` with `@antfu/eslint-config` enforces single quotes and no semicolons, and `lint:fix` applies the same rules in place. A copied repository starts at version 3.16.0, and the template's own versioning step runs `bumpp --commit --push --tag`, which none of your copies inherit. That is the permanent cost of choosing a template over a dependency: every future upgrade is a manual diff.

## Conclusion

Take this template when the product is a mobile web page, Vant is a kit you already accept, and the alternative is a day of wiring the same plugins by hand. Leave it when your team needs one shared, versioned UI package, because a template hands every project a copy that no upstream push will ever refresh. Before the first commit, read engines rather than the README floor, delete the dependencies you did not ask for, and confirm which build script your deploy runs. Nothing keeps that copy current afterwards.

## FAQ

### What Node version does vue3-vant-mobile require?

The README says the template needs `Node 22.22.0+`, while `engines` in `package.json` sets the floor at `>=22.23.0` and pins pnpm at `pnpm@11.18.0`. Follow `engines`, since that is the value the package declares for itself.

### How do I mock APIs in vue3-vant-mobile?

The dev script starts Vite with `MOCK_SERVER_PORT=8086`, and `vite-plugin-mock-dev-server` serves fixtures from the `mock/` directory at the repository root. `vite preview` runs without that server in front of it.

### Is vue3-vant-mobile a component library or a project template?

It is a project template, generated from GitHub or cloned with tiged, not a package you install. UI components come from Vant and are resolved on demand by `@vant/auto-import-resolver`.

### How do I rename a vue3-vant-mobile project before publishing it?

The checklist calls for the author name in `LICENSE`, the page title in `index.html`, the hostname in `vite.config.ts` and the favicon in `public`, plus removing routes you do not need.

### Does vue3-vant-mobile support WeChat mini programs?

No. `wechat-h5` appears only as a repository topic, and neither the scripts nor the documented configuration contains a WeChat or mini-program build target.

## Sources

- [License: MIT](https://github.com/vue-zone/vue3-vant-mobile/blob/main/LICENSE)
- [Project website](https://vue3-vant-mobile.netlify.app)
- [README](https://github.com/vue-zone/vue3-vant-mobile/blob/main/README.md)
- [Releases](https://github.com/vue-zone/vue3-vant-mobile/releases)
- [vue-zone/vue3-vant-mobile on GitHub](https://github.com/vue-zone/vue3-vant-mobile)

---

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