uniapp-vue3-template: a uni-app starter shaped by team conventions

A project skeleton with house rules, not a component library

uniapp-vue3-template is described as a rapid development template for team collaboration, built on uni-app, Vite, Vue 3, TypeScript, uview-plus and UnoCSS. The target audience is explicit: a group of people who will edit the same repository over several months and need the layout, the lint setup and the request layer to stop drifting. The project ships opinionated defaults in its table of technologies. The framework and build side are Uni-app, Vue 3, Vite and TypeScript. uview-plus is the default UI library, UnoCSS handles styling, Pinia handles state, and the request layer is a wrapped luch-request implementation with TypeScript types and token refresh. ESLint, StyleLint, EditorConfig and git hooks check commit formatting. What you inherit is a set of decisions, and the interesting question is which of them live in the default branch and which live elsewhere.

pnpm is enforced, and the engine floor is Node 20

The manifest is the first place a new contributor looks, and it settles two arguments in advance. The package is named uniapp-vue3-project, declared as an ES module at version 1.6.0, and licensed MIT. A preinstall hook exists that will refuse an install run through another package manager, and the engines block states the minimum versions.

  "engines": {
    "node": ">=20.19.0",
    "pnpm": ">=8"
  },

The manifest version is 1.6.0, so the version number in package.json is the only place to look for the current state of the template, since the repository publishes no GitHub releases.

Build scripts are organised around dev, test and prod modes

Every script in package.json is a thin wrapper over the uni CLI, and the naming pattern makes the matrix easy to read. The H5 side has dev:h5, dev:h5:ssr, dev:h5-test and dev:h5-pro, with matching build:h5 entries that add the build command. The WeChat mini program side mirrors it with dev:mp-weixin, dev:mp-weixin-test and dev:mp-weixin-prod, plus the matching build:mp-weixin scripts. There are app targets too, for dev:app, dev:app-android and dev:app-ios. Modes are selected with the uni mode flag, so test and production builds differ from development builds by configuration rather than by separate scripts. The README recommends pnpm throughout, and it is the package manager the preinstall hook insists on. The first run of a fresh clone is short.

pnpm install
pnpm dev:h5
pnpm dev:mp-weixin

Install the dependencies, then start the H5 target or the WeChat mini program target. From the same scripts list, the app targets and the automated mini program jobs look like this.

    "dev:app": "uni -p app",
    "dev:app-android": "uni -p app-android",
    "dev:app-ios": "uni -p app-ios",
    "build:h5": "uni build",
    "preview": "node ./scripts/mini-ci.js preview",
    "upload": "node ./scripts/mini-ci.js upload",

The preview and upload entries are the WeChat mini program automation, and they are what a release pipeline would call.

The build/plugins folder does the repetitive file work

Configuration is concentrated under build/, with build/config holding the Vite entry file and the cross origin proxy setup, and build/plugins holding one file per plugin. The plugin list is the clearest statement of what this template automates: autoImport.ts for automatic API imports, component.ts for automatic component imports, cleanImage.ts for removing local image files, replaceUrl.ts for swapping local image addresses for CDN addresses, unocss.ts for the UnoCSS setup, visualizer.ts for the package size view, and an index.ts entry point. The image pipeline is the most opinionated piece. At build time it deletes local images and replaces local paths with online CDN paths, and the README marks that step as needing configuration. A team without a CDN, or one that wants images in version control, has to turn that plugin off, and the README does not spell out how.

Login checks are declared per page, and TabBar pages need onShow

Access control is handled by page configuration rather than by a router table. In pages.json you set needLogin: true in the configuration object of the target page, and the navigation interceptor picks that up. The documented exception is the WeChat mini program TabBar. Clicking a TabBar entry does not trigger uni.switchTab, so the usual interception never runs, and the fix is to perform the permission check inside the onShow lifecycle of the TabBar page itself. The project points at pages/tab/user/index.vue as the reference implementation. This is the kind of platform quirk the template absorbs, and it is also the kind of detail a team will otherwise rediscover on the wrong day.

Directory layout splits pages, hooks, api and store by module

The source tree is the second piece of house style. Under src/, api/ holds requests divided by module with type definitions beside them, components/ holds shared components, hooks/ holds reusable hooks such as use-clipboard, use-loading, use-modal, use-permission and use-share, locale/ holds internationalisation resources, pages/ holds the main package and the sub packages, plugins/ initialises uni-app plugins, router/ handles routing, static/ holds images and fonts, store/ holds Pinia modules split by app and user state, and utils/ holds request, auth and modal helpers. Outside src, build/ holds the Vite configuration, env/ holds environment variables, scripts/ holds automation such as the commit check and the mini program CI/CD scripts, and types/ holds global TypeScript types. The api, hooks and store folders all follow the same shape of an index.ts plus per-module folders, which is what makes the codebase predictable after the first month.

Upstream sync, commit prompts and uni-app upgrades are scripted

Because teams are expected to fork this template and keep their own application code on top, the upstream flow is written out step by step. You add the upstream remote, fetch it, switch to your local main branch and merge upstream/main, resolving conflicts by hand.

git remote add upstream https://github.com/oyjt/uniapp-vue3-template
git fetch upstream
git checkout main
git merge upstream/main

The commit step uses cz-git through a single interactive command, and the mini program targets have automated preview and upload entries pointing at a script in the scripts directory. Upgrading the uni-app itself is handled by a version manager run through pnpm, with a second command that removes redundant dependencies left behind after an upgrade to keep the package small.

pnpm cz
pnpm uvm
pnpm uvm-rm

The project has no GitHub releases, so the upgrade path is the only way to move forward, and the last push was on 2026-10-14.

Alternatives live in branches, not in the default tree

Several of the choices most teams argue about are not in the main branch. A branch called feature/wot-design-uni carries wot-ui instead of uview-plus, feature/shadcn-ui carries shadcn-ui, and separate branches carry axios or alova instead of the default luch-request wrapper. There is also a base-js branch for projects that do not want TypeScript, which the README describes as the no TypeScript version. That is a reasonable way to publish opinions without forking, and it is also the weakness: adopting wot-ui or axios means switching branches rather than changing one dependency, so the two choices are coupled to a git operation rather than a configuration value. Two smaller points: the image to CDN replacement needs setup, and the template describes AI oriented rules files alongside editor configuration, which tells you the toolchain expects an assistant in the loop.

Editorial conclusion

Adopt uniapp-vue3-template if your team already writes uni-app and wants one agreed set of lint rules, auth interception and build scripts from day one. Skip it if you need a published release cadence, a TypeScript-free variant on the default branch, or uview-plus replaced by wot-ui, shadcn-ui, axios or alova without changing branches. Before you start, run pnpm install and pnpm dev:mp-weixin on one target, confirm the needLogin flag in pages.json does what your login flow expects, and read the merge steps for the upstream remote because the repository has no GitHub releases to fall back on.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. oyjt/uniapp-vue3-template on GitHub
4. Project website
5. README