NutUI: JD's Vue 3 mobile component library for H5 and Taro mini programs

What NutUI is for, and who it fits

NutUI is a Vue component library aimed at mobile interfaces. The README describes it as a lightweight Vue component library in JD's visual style, supporting mobile H5 and mini program development, and the package description names Vue 2 and Vue 3 with mini program support. The v4 branch and the npm package at version 4.3.15 are the current line.

The audience is narrow but well defined. If you are writing a Vue 3 mobile web app and want components that already look like a Chinese e-commerce app, NutUI ships that styling by default rather than asking you to build it. If you are writing a Taro project that must compile to WeChat, Alipay and JD mini programs from one codebase, the companion package @nutui/nutui-taro is the relevant artifact, and the README points at a separate documentation site for it.

The README lists the feature set plainly: 80+ components covering mainstream mobile scenarios, one codebase for H5 plus multi-platform mini programs, the JD APP 10.0 visual specification, on-demand imports, TypeScript support, server-side rendering marked as being in a testing phase, component-level theming with more than 700 built-in variables, internationalization for English, Indonesian and Traditional Chinese, unit test coverage above 80%, and Sketch design resources.

Two of those claims deserve attention. Server-side rendering is explicitly labelled as a testing phase, so treat it as unfinished rather than supported. And the coverage number is a project claim, not a guarantee about the components you happen to use.

Two packages, one component set: how the H5 and Taro builds relate

The architecture is split at the package level rather than the component level. @nutui/nutui is the mobile H5 build. @nutui/nutui-taro is the build for Taro multi-platform mini programs and Taro-H5 projects. The README links each to its own documentation path under nutui.jd.com, one under /h5/vue/4x/ and one under /taro/vue/4x/.

That split is the central design decision, and it has consequences. A component you rely on in H5 may not exist in the Taro build, or may behave differently, because the Taro package has to compile down to mini program primitives that do not include the DOM. The README does not publish a per-component parity table between the two packages, so the only reliable way to check is against the Taro documentation site for the component in question.

The repository layout matches the split. The root holds src/, packages/, publish/, scripts/, and a set of separate Vite configs: vite.config.build.ts, vite.config.build.disperse.ts, vite.config.build.css.ts, vite.config.build.locale.ts, vite.config.build.resolver.ts, plus taro-specific variants such as vite.config.build.taro.vue.ts and vite.config.build.taro.vue.disperse.ts. The build script chains these configs in sequence, then runs a dts step and a resolver step. Disperse builds exist because on-demand importing is a first-class concern: the package ships a resolver for unplugin-auto-import, published as @nutui/auto-import-resolver, so component imports and styles can be generated rather than written by hand.

There is also @nutui/touch-emulator, an auxiliary library for using NutUI on desktop, and @nutui/icons-vue and @nutui/icons-vue-taro as the icon packages for the two builds. Icons are not bundled into the component packages.

Installing NutUI and rendering a first component

The README does not include a copy-paste install block. What it does give is the set of published package names and the official ecosystem table, so the commands below use only those names: @nutui/nutui for the mobile H5 version and @nutui/nutui-taro for the Taro multi-platform version, both published to the public npm registry per publishConfig.

Install the H5 package:

npm install @nutui/nutui

The package exposes a main UMD build at dist/nutui.umd.js, a module build at dist/nutui.es.js, a stylesheet at dist/style.css, and types at dist/types/index.d.ts. Those paths come from the package.json fields, and they are what you point your bundler at:

{
  "main": "dist/nutui.umd.js",
  "module": "dist/nutui.es.js",
  "style": "dist/style.css",
  "typings": "dist/types/index.d.ts"
}

For a Taro project, install the Taro package instead and follow the Taro documentation path linked from the README:

npm install @nutui/nutui-taro

The README's on-demand import claim is served by @nutui/auto-import-resolver, which the ecosystem table describes as the resolver configuration for the unplugin-auto-import plugin. The README does not show the resolver setup code, so go to the H5 or Taro documentation site for the wiring. What you should see once the H5 package is registered is NutUI-styled components rendering with no additional CSS work; if styles are missing, the stylesheet entry is the first thing to check.

Theming through 700+ variables, and what that costs you

Theming is component-level, not global-only. The README states there are more than 700 built-in variables, and the build pipeline contains a dedicated CSS build config plus a generate:themes step, which is consistent with the variables being compiled into per-component stylesheets rather than one monolithic theme file.

That is the right structure for a design system that has to match a specific brand, and it is why the JD APP 10.0 visual specification is listed as a feature rather than a footnote. You can restyle a Button without restyling a Dialog.

The cost is that 700+ variables is a large surface. There is no documented list in the README of which variables are stable across minor versions and which are internal. If you override variables broadly, a minor release can move a value you depended on. The safer pattern is to override the smallest set that produces the change you need, and to check the release notes for theme-related changes before upgrading. The README points at the releases page as the changelog, and the repository also carries a CHANGELOG.md.

Release cadence is the real limitation

The published releases tell an uneven story. v4.3.13 was released on 2024-09-14. v4.3.14 followed on 2025-07-25, with a beta.3 of the same version earlier that day. The package.json version is 4.3.15, which does not appear in the release list above it. The last push to the repository was on 2026-04-02.

So the tags do not map cleanly onto the published package, and there is a gap of roughly ten months between 4.3.13 and 4.3.14. Anyone planning around NutUI should read the release notes rather than assume a monthly cadence, and should pin versions in the lockfile. The preinstall script enforces pnpm with npx only-allow pnpm, so if your team uses npm or yarn you will hit a hard stop when working inside the repository itself, though not when consuming the published package.

The server-side rendering support is the second limitation. It is described as being in a testing phase, which means you should not build an SSR-dependent product on it without verifying your specific components first. And the H5/Taro package split means cross-platform code sharing is at the component level, not the code level: your page components still need to respect what the Taro build supports.

NutUI against Vant and Taroify

The two libraries people most often weigh against NutUI are Vant and Taroify, both of which appear in the related searches for this project.

The difference is scope. Vant is a mobile component library for Vue with its own visual language, and it is not built around the H5-plus-mini-program split that defines NutUI's packaging. If your project is H5 only and you have no opinion about matching JD's visual specification, Vant's single-package model is simpler to reason about: one install, one set of components, no parity question between two builds.

Taroify is the closer comparison, because it targets Taro. The distinction is that NutUI ships both an H5 package and a Taro package from the same repository and the same component set, so a team building an H5 app that later needs a mini program version has a documented migration path inside one project. Taroify's scope is the Taro side. If you are Taro-only from day one, that narrower scope is not a disadvantage.

The honest framing: NutUI's advantage is the dual target plus JD's design defaults. Its disadvantage is that the dual target doubles the surface you have to verify, and the README does not give you the parity table to do that verification quickly.

Licence and the cost of upgrading

NutUI is MIT licensed, and the LICENSE file sits at the repository root on the v4 branch. MIT is permissive: you can use it in commercial and closed-source products, and you can modify it, provided the copyright notice and permission notice are retained. This is a description of the licence text, not legal advice; if your organization has a policy on third-party licences, route it through whoever owns that policy.

The upgrade cost is mostly about the theme variables and the version pinning. Because the release tags and the package.json version do not line up (4.3.15 in the manifest, no matching tag in the release list), you cannot infer what changed from the version number alone. Read the release notes for the version you are moving to. If you override theme variables, check whether the variables you set still exist in the new build. And if you use the auto-import resolver, verify that the resolver package version still matches the component package version, since they are published separately.

Editorial conclusion

Adopt NutUI if you are building a Vue 3 mobile H5 app or a Taro mini program and want one component set across both, with per-component theme variables and TypeScript types. Do not adopt it if you need React, or if you want a component library whose release cadence you can predict from the tags. Before committing, install @nutui/nutui and @nutui/nutui-taro in a scratch project, run the auto-import resolver against a single component, and check that the mini-program build target you need is covered by the Taro package's documented platform list.

Frequently asked questions

Official sources

1. jd-opensource/nutui on GitHub
2. License: MIT
3. Project website
4. README
5. Releases