# airyland/vux: Vue 2 mobile components built on WeUI

> Vux is a component library for Vue 2 mobile web apps that follows WeUI's visual language, distributed as the npm package vux and installed through the airyland/vux2 webpack template. It is a settled project, not a fast-moving one, and the README's requirements section is the first thing to read.

**airyland/vux** — Mobile UI Components based on Vue & WeUI

- Repository: https://github.com/airyland/vux
- Website: https://vux.li
- Stars: 17,456 · Forks: 3,619
- Language: Vue
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/airyland-vux

## What vux solves for Vue 2 mobile web apps

Building a mobile web interface in Vue 2 means writing a lot of small, unglamorous pieces: a cell list that behaves on touch, a picker that scrolls correctly, form controls that validate, a popup that does not fight the page scroll. Vux collects those pieces. Its own description in the README is blunt about the scope: "Mobile UI Components based on Vue & WeUI." The visual language is WeUI's, which is the design system WeChat uses for its in-app web views, so the components look native-ish inside WeChat's browser without you restyling anything.

The audience is narrow and specific. The README's requirements block asks for vue@^2.3.0, webpack@^2.0 and node@^7.6 for development. That is a Vue 2 project with a webpack build, not a Vite project and not a Vue 3 project. If your codebase matches, vux is a drop-in dependency; if it does not, the requirements are a wall rather than a suggestion.

The dependency list in package.json shows how much the library absorbs for you: axios for requests, async-validator for form validation, fastclick for touch handling, exif-js for image orientation, big.js for decimal arithmetic, countup.js for animated numbers, @antv/f2 for charts. Those are real transitive costs, and they are the reason a single npm install gets you a fairly wide surface of behaviour instead of a thin wrapper around CSS.

## How the components and the build are organised

The repository is a monorepo-shaped package, not a flat src folder. Top-level entries include packages/, src/, build/, docs/, ssr/, test/ and config/. The package.json scripts read as a map of that layout. build-components, build-styles and build-main are separate steps, and xbuild chains the first two: "npm run build-styles && npm run build-components". That split matters if you ever need to rebuild from source, because components and styles are produced by different scripts and you cannot assume one implies the other.

The published entry point is index.js, declared as main in package.json, with the package name vux and version 2.11.1. The default branch is v2, and the repository also carries an ssr/ directory, which indicates server-side rendering was at least considered in the layout. The README does not document what ssr/ contains or how to use it, so treat that directory as something to inspect in the source rather than something the documentation promises.

The build scripts also show a CDN variant: build:cdn runs the same build with a --cdn flag. The README does not explain what that flag changes, so the only reliable source for its effect is build/build.js in the repository.

## Installing vux through the vux2 template

The README does not give a bare npm install vux instruction. It points at a scaffold instead: the vux2 template, which the README says is "directly modified from Vue official webpack template". The install sequence is three commands.

```bash
npm install vue-cli -g
vue init airyland/vux2 projectPath

cd projectPath
npm install // or yarn
npm run dev // or yarn dev
```

The first command installs the Vue CLI globally. The second scaffolds a project from the airyland/vux2 template into a directory you name. The third block changes into it, installs dependencies with npm or yarn, and starts the dev server with npm run dev or yarn dev. What you should see after that is a running development server serving the scaffolded app, with vux already wired into the template's build configuration.

Because the template is the documented path, adding vux to an existing project is not covered by the README. The package is on npm under the name vux, and package.json declares main as index.js, but the README gives no manual registration snippet, no per-component import example and no plugin installation line. If you are not starting from the template, the repository's src/ and docs/ directories are where you would have to work out the wiring yourself.

A live demo is linked from the README at https://vux.li/demos/v2?x-page=github, and the Chinese documentation is at https://vux.li/. The README labels the English documentation as "English(working)", which is worth reading literally: the English docs are incomplete, and the Chinese docs are the fuller source.

## Where vux stops being the right tool

The requirements block is the honest limit. vue@^2.3.0 is required, and the README explains why in parentheses: the .sync modifier. Vue 2.3 is where .sync was reintroduced, so components that rely on it cannot work on earlier Vue 2 releases. If your app is pinned below 2.3, vux is not a candidate until you upgrade Vue.

webpack@^2.0 is the second constraint, and it is the one that ages worst. A project on webpack 5 or on Vite is outside what the README describes. Nothing in the README says the library fails on a newer bundler, but nothing says it works either, and the documented development path assumes webpack 2. Treat that as unverified ground.

The third limit is release cadence. The newest release in the list is v2.11.1 from 2021-09-17. There is a v2.9.6 from 2021-07-18 and a v2.9.4 from 2019-04-16. The package.json version is 2.11.1, matching the newest tag. The repository's last push is 2026-07-17, which is more than six months before today, so the v2 branch has not been pushed to recently. Commits without a matching release tag are a normal pattern, but it means the npm package and the branch can differ, and you should check which one you are actually depending on.

Finally, this is a mobile component set. There is no desktop layout story here, and WeUI's design language is a deliberate choice, not a neutral default. If your product does not want to look like a WeChat web view, you are fighting the library rather than using it.

## vux against Ant Design Mobile and WeUI directly

The README's credits list names the influences directly, including WeUI, FrozenUI, Ant Design, Ant Design Mobile, XScroll, Ionic, SUI Mobile, PhotoSwipe and WePayUI. That list is useful because it tells you what the alternatives actually are.

Ant Design Mobile is the closest comparison and the one with the clearest difference in approach. Ant Design Mobile implements Ant Design's visual language for mobile, while vux implements WeUI's. The two are not interchangeable skins over the same components; they carry different spacing, different control shapes and different assumptions about where the app runs. If your users are inside WeChat's browser, WeUI's conventions are the ones they already recognise, and that is vux's argument. If your app is a standalone mobile site with its own brand, Ant Design Mobile's system is the more common starting point.

Using WeUI directly is the other option, and it is a real one. WeUI is a CSS and markup system, not a Vue component library. Taking WeUI directly means you write the Vue wrappers yourself: the state, the events, the two-way binding, the picker behaviour. Vux's contribution is that wrapper layer, plus the auxiliary dependencies (async-validator, fastclick, big.js) that the wrappers pull in. If your component needs are small, the wrapper layer may not be worth the dependency surface; if you need pickers, popups and validated forms, writing them yourself is the larger cost.

## Licence and the cost of staying on vux

Vux is MIT licensed. The LICENSE file sits at the top level of the repository, the README links to it on the v2 branch, and package.json declares "license": "MIT". MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The repository also credits bundled or adapted work from other projects, and the README marks at least one of them explicitly, autosize, as MIT. That does not remove the obligation to check the licences of the transitive dependencies in package.json if you redistribute a built bundle, but it does mean the library itself carries no copyleft condition. This is a description of what the files say, not legal advice.

Upgrade cost is the part the README is silent on. There is no migration guide, no changelog section and no rollback documentation in the README. The release list jumps from v2.9.6 in 2021 to v2.11.1 in 2021 with nothing in between, and the only earlier entry is v2.9.4 from 2019. If you need to move between those versions, the release notes are the only record, and the README does not tell you what breaks.

The practical upgrade question is not vux's version number but Vue's. Because the library targets vue@^2.3.0 and the .sync modifier, a Vue 2 to Vue 3 migration is a rewrite of your component usage, not a version bump. Vux has no Vue 3 counterpart in the repository. Budget for that before you build a large surface on it.

## Conclusion

Adopt vux when you are already maintaining a Vue 2 mobile web app that needs WeUI-styled components and you want a single npm dependency rather than a hand-rolled component set. Do not adopt it for a new Vue 3 project, for a desktop layout, or anywhere you need a library whose release cadence tracks current Vue. Before committing, verify three things against your own codebase: that your Vue version satisfies vue@^2.3.0, that your bundler is webpack@^2.0 or that you have a plan for a newer one, and whether you need any component the repository's src directory does not contain. The last push was on 2026-07-17, while the newest release listed is v2.11.1 from 2021-09-17, so check the v2 branch itself rather than the release list if you need a fix that landed after that tag.

## FAQ

### Which Vue and webpack versions does vux require?

The README's requirements block lists vue@^2.3.0, webpack@^2.0 and node@^7.6 for development. The Vue floor exists because vux uses the .sync modifier, which the README ties to that version.

### How do I install vux in a new project?

The README documents the vux2 template rather than a direct npm install: install vue-cli globally, run vue init airyland/vux2 projectPath, then npm install and npm run dev inside the created directory. The template is described as directly modified from Vue's official webpack template.

### Is vux still maintained?

The repository is not archived, and its last push was on 2026-07-17. The most recent release in the list is v2.11.1 from 2021-09-17, so the npm package and the v2 branch may not be at the same point.

### Is vux free to use in a commercial product?

Yes. Vux is MIT licensed, declared in package.json and linked from the README, which permits commercial use and modification as long as the copyright and permission notices are kept. The licences of the dependencies listed in package.json are a separate question if you redistribute a built bundle.

## Sources

- [airyland/vux on GitHub](https://github.com/airyland/vux)
- [License: MIT](https://github.com/airyland/vux/blob/v2/LICENSE)
- [Project website](https://vux.li)
- [README](https://github.com/airyland/vux/blob/v2/README.md)
- [Releases](https://github.com/airyland/vux/releases)

---

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