unibest: a uni-app template that has already done the setup work

Starting from `pnpm create unibest` instead of opening HBuilderX

The README's quick start is three commands, and the point of the third one is that you never open the IDE to run the project.

pnpm create unibest
pnpm i
pnpm dev

This is the difference that matters most when you compare unibest to the older uni-app starters. The template is built on uni-app plus Vue 3 plus TypeScript plus Vite 5 plus UnoCSS, with wot-ui for components and z-paging for list pagination, and the README is explicit that HBuilderX is not required. You develop in VS Code, with WebStorm named as the alternative. Anything you need to change happens in files you can read, not in a GUI project wizard.

The environment requirements are stated twice and the two statements are not identical, which is worth knowing before you hit a version error. The README asks for node 18 or newer and pnpm 7.30 or newer, while `package.json` declares `"node": ">=20"` and `"pnpm": ">=9"` under `engines`, and pins `[email protected]` through `packageManager`. The stricter manifest is what you will actually hit, so read that file rather than the badge at the top of the README.

The template also refuses to be installed with npm. The `preinstall` script runs `npx only-allow pnpm`, so an `npm install` fails on purpose instead of producing a lockfile mismatch later.

What the template wires up before you write a single page

Most starter repositories give you a build pipeline. unibest gives you the application conventions a real project needs on day one, and the repository tree is a fair map of them: `pages.config.ts` and `manifest.config.ts` hold the app and page configuration, `uno.config.ts` drives utility classes, `vite-plugins/` holds the build-time plugins, `openapi-ts-request.config.ts` configures API code generation, and `src/` is where the pages themselves go.

The features listed in the README are concrete rather than aspirational. Conventional routing means a file in the page directory becomes a route, so there is no separate route table to keep in sync. There is a layout system, a wrapped request function, request interception, and login interception, which is the part that stops every team from inventing its own token-refresh loop. UnoCSS is configured already, and i18n is included as an opt-in rather than something you bolt on later.

Two details in the repository show how seriously the maintainer takes upgrade pain. Every `dev` script has a `predev` hook that runs `node ./scripts/create-base-files.js`, so the files that uni-app expects but that git does not track are regenerated on every run instead of being committed and drifting. And `package.json` carries a `unibest-version` field plus a `unibest-update-time` field, with `bump-version.js` and `postupgrade.js` scripts and a `uvm` script that calls `npx @dcloudio/uvm@latest`. That is a template with a migration story, which is unusual and is the main reason to prefer it over assembling the same pieces yourself.

Running the same code on H5, WeChat and the app container

The platform table in the README lists H5, iOS, Android, and the WeChat, ByteDance, Kuaishou, Alipay, DingTalk and Baidu mini program targets, with a caveat that each UI framework supports a different subset. The scripts map onto those targets by passing a platform flag to the `uni` binary, so the dev commands differ only in that argument.

pnpm dev:h5
pnpm dev:mp
pnpm dev:app

`pnpm dev:h5` serves on port 9000. `pnpm dev:mp` builds to `dist/dev/mp-weixin`, which you then open with the WeChat developer tools by importing that folder. `pnpm dev:app` produces `dist/dev/app`, which is imported into HBuilderX for running against a simulator or a native base. For Android and HarmonyOS the README describes the opposite direction: import the whole unibest project into HBuilderX and run from its menu.

The release path mirrors the dev path, and the output location changes but the command does not:

pnpm build:h5
pnpm build:mp

Web builds land in `dist/build/h5` and the README notes that if you serve them from a subdirectory rather than the root, you change `h5.router.base` in `manifest.config.ts`. WeChat builds land in `dist/build/mp-weixin` and are uploaded through the developer tools. App builds land in `dist/build/app` for cloud packaging.

There is also a Dockerfile, and it is worth reading because it shows what the maintainer considers the production path. It builds with `pnpm install --frozen-lockfile`, runs the base file generator, calls `pnpm run build:h5:prod`, then copies `dist/build/h5` into an `nginx:1.22-alpine` image on port 8080 alongside the repository's `nginx.conf`. The Dockerfile is H5 only. There is no container path to a mini program, which is expected, but it does mean the container story covers exactly one of the platforms on that table.

Branch layout that decides which variant you actually get

The README documents four branches and the relationships between them, which is unusual to find stated so plainly in a starter template. `main` and `base` are the same branch. `base` feeds `base-i18n`, and `base-login` feeds `base-login-i18n`. In other words, internationalisation is a branch rather than a feature flag, and login handling is a separate variant you opt into by choosing which branch you generated from.

That choice has consequences after generation. If you take the internationalisation branch you inherit `vue-i18n`, which the v4.1.0 release notes list as an added dependency, and you accept that i18n is now part of your build. If you take the login branch you inherit the login interception and the routing guard work. Both are reasonable defaults, but they are defaults chosen once at project creation rather than added later, and merging between branches is not something the repository documents.

A second thing the branch model implies is that the generated project is a snapshot. The `pnpm create unibest` flow produces a copy of a template at whatever version the generator resolves, and the version markers in `package.json` are what you compare against later. The release history shows the template moving fast enough that the distinctions matter: v3.20.0 in November 2025 added the `toLoginPage` utility with debounce handling, extracted the tabbar types into `types.ts`, and added a WotResolver component resolver. v4.2.0, published on 2025-12-31, made a reactive timestamp for token expiry checks, added route interception for plugin page paths, and merged the custom tabbar strategies, removing `CUSTOM_TABBAR_WITHOUT_CACHE`. That last change is the kind of detail that breaks a project which hand-rolled around the old constant.

OpenAPI generation feeding a wrapped request layer

The `openapi-ts-request.config.ts` file and the `openapi` script in `package.json` mean the project expects its API types to be generated rather than written. The README lists this under unified configuration alongside code hints, formatting and snippets. In practice the pattern is: describe the API, run the generator, and let the typed client flow into the request wrapper that `src/` already has.

The history of that integration is instructive. v3.20.0 bumped `openapi-ts-request` from 1.6.7 to 1.10.0 and then fixed the option types in the generated output. That is the normal cost of a codegen dependency: the generator improves, and your generated file changes shape underneath you. Pinning the generator version and reading the diff on upgrade is not optional here.

The release notes also show the interception layer being tightened. v3.20.0 fixed a case where a route guard and an HTTP response interceptor could both trigger and send the user to the login page twice, and changed the HTTP request function to return `responseData.data` rather than the wrapper object. If you take the template and then change the shape of the request return value, you are editing something the template depends on, not adding to it. `vitest.config.ts` is present in the tree, so there is a place to put tests, but the README does not describe what is covered.

Where unibest costs you more than it saves

The honest answer is that this is a template with opinions, and the opinions are all in one direction: Vue 3, Vite, pnpm, TypeScript. If your organisation has standardised on npm, or on Vue 2, or on HBuilderX GUI workflows for reasons of team familiarity, then the value of the template drops sharply, because what you have adopted is a toolchain as much as a set of files. The version mismatch between the README's stated requirements and the `engines` field is a small example of that cost.

It is also uni-app specific. The code compiles to mini program targets through the uni-app layer, which means the runtime is the uni-app runtime rather than a browser or React Native. Anything that needs a native module has to come from a uni-app plugin marketplace, and the template itself contains nothing native. For a team shipping only to the web, the multi-platform table is decoration.

The maintenance picture is mixed in a way worth reading carefully. The repository is not archived and the last push was on 2026-09-15, while `package.json` reports version 4.4.1 with an `unibest-update-time` of 2026-05-22. The newest tagged release is v4.2.0, published on 2025-12-31. So the `base` branch is moving ahead of the release tags, which is normal for a template but means `pnpm create unibest` and a pinned release can give you different code. Decide which one you want before you start, because `bump-version.js` and the branch layout make migration a deliberate act rather than a diff.

The migration path away is also worth naming. The `uvm` script exists to move the underlying uni-app version, and `postupgrade.js` runs afterwards to remove dependencies that are no longer needed. That is a maintained escape hatch from the one framework underneath, which is a better position than most templates offer.

Editorial conclusion

unibest is a good fit when the target is a WeChat or ByteDance mini program and the team agrees on Vue 3 and Vite, because the conventional routing, the generated base files and the tabbar handling are the parts you would otherwise rewrite. It is the wrong choice for a native-only app, for a team standardised on HBuilderX, or for a product that needs native plugins, since the template is opinionated about the toolchain and carries no native layer of its own. The repository's last push was on 2026-09-15 and the newest tagged release is v4.2.0 from 2025-12-31, so check whether the base branch has moved past the release before pinning a version. Start by generating a project with `pnpm create unibest` and running `pnpm dev:mp-weixin`, then read `pages.config.ts` and `vite-plugins/` before adding anything.

Frequently asked questions

Official sources

1. feige996/unibest on GitHub
2. License: MIT
3. Project website
4. README
5. Releases