nutui-react: a JD-styled React component library that also compiles to mini-programs

What NutUI React is for, and who is already using it

The README describes the project as JD-style mobile UI components based on React that support users to develop H5 and mini-programs, and the package description in package.json says it in Chinese as a lightweight mobile React component library following the JD style, supporting one codebase for H5 and mini-programs.

That dual target is the whole point, and it is worth being concrete about what it means. A mini-program is not a browser. WeChat mini-programs, JD mini-programs and the other Chinese platforms each have their own runtime, their own component model and their own rendering rules, and an ordinary React application cannot run in them. So a library that serves both H5 and mini-programs has to be written against an abstraction that compiles down to both, which in this project is Taro for one path and JDTaro for the other. The README's running instructions have a section for Taro and a separate section for JDTaro, with their own script prefixes.

The visual target is equally specific. The features list says the components are based on the JD APP 11.0 visual specifications, and the project is the React sibling of the NutUI family, with a separate NutUI x Taro line linked from the communication table. The homepage is nutui.jd.com/react/, and the project carries a Chinese-language README alongside the English one.

The audience is therefore a team building a mobile front end for a Chinese market, where the same product ships as a web page and as one or more mini-programs. The name comes from the squirrel in Ice Age who pursues a nut for a lifetime, which the README explains in one line, and the logo is a nut.

The feature list is a normal component library's list: 70+ high quality components, extensive documentation and demos, written in TypeScript, support for tree shaking, support for custom themes, 90%+ unit test coverage, Sketch design resources, and support for SSR, which is marked as experimental. There is a Chinese-language component standard whitepaper in the repository, NutUI-React_组件标准白皮书.md, which is a sign that this is treated as a design system with a written specification rather than a loose collection of widgets.

The three build targets, and why the JDTaro path needs an .npmrc

The running instructions in the README are the clearest statement of the architecture, and there are three paths with different requirements.

The H5 path is the plain Vite development server. Clone, install with pnpm, and run pnpm run dev, which starts Vite with --open and --force and serves the site at http://localhost:3000.

The Taro path adds a platform argument to the dev script. The same clone and install, then pnpm dev:taro with h5 for a Taro-built H5 target, weapp for the WeChat Mini Program, and jd for the JD Mini Program. The README notes that for other platforms you should refer to the scripts in the package.json file in the demo directory, which is a candid way of saying the supported set is not exhaustive.

The JDTaro path is the interesting one, because it has an extra step the others do not. You have to add a.npmrc file in the root directory of the repository with this configuration:

git-branch-lockfile=true

and then install with pnpm install --ignore-pnpmfile. The dev scripts are pnpm dev:jdtaro with h5, weapp or jd, plus a separate pnpm dev:jdtaro:jdharmonycpp for a harmony cpp target.

That.npmrc requirement is worth understanding rather than copying blindly. The lockfile is tied to a branch, and the JDTaro build needs the pnpmfile hook that would otherwise rewrite the lockfile, so the flag disables that rewriting and the lockfile setting keeps the resolution stable across the branch. It is a workaround for pnpm behaviour in a monorepo with multiple build configurations, and it means the JDTaro path is the least frictionless of the three.

The package.json makes the multi-target nature concrete at the script level. There are separate dev scripts for the main project, for jmapp, for daojia and for jrkf, the latter three each setting VITE_APP_PROJECT_ID, and separate ones for dark theme and for RTL, where dev:rtl sets VITE_RTL=rtl. Those are project identifiers and theme variants, not separate components, and they are how the same component set is demonstrated in the different visual configurations the library supports.

The published package: side effects, styles and the es/umd split

The package.json is where the library's design decisions about distribution become visible, and two of them matter a lot in practice.

The first is the sideEffects field, which is not the usual false. It lists the style files: *.scss, dist/es/**/style{,-jmapp,-jrkf}/*, dist/cjs/**/style{,-jmapp,-jrkf}/*, dist/style{,-jmapp,-jrkf}.css, dist/styles/**/* and dist/styles/font{,-jmapp,-jrkf}/*. That list is what makes tree shaking work. The features list advertises tree shaking support, and it can only work if the bundler is told which files are safe to drop. Style files are not safe to drop, because importing a component without importing its style means the component renders unstyled, and a naive sideEffects: false would let a bundler remove the CSS. The same reasoning applies to the font files.

The second is the build format guidance in the README. If you are using an AMD environment or build tools such as Webpack or Vite, it recommends the es version, and if it is a non-module environment such as direct reference through a script tag, it recommends the umd compressed version. The two artefacts are nutui.es.js and nutui.umd.js. The package.json entry points match that: main is dist/nutui.react.umd.js, module is dist/es/packages/nutui.react.build.js, typings is dist/es/packages/nutui.react.build.d.ts, and style is dist/style.css.

The build itself is a multi-config Vite setup. There are vite.config.demo.ts, vite.config.mts, vite.config.site.mts, vite.config.site.taro.mts and vite.config.theme.mts, which is a hint at the fact that the demo site, the library, the documentation site, the Taro variant of the site and the theme tooling are all built separately. The theme.html and index.html and index.taro.html at the top level are the entry points for the demo, the site and the Taro site respectively.

Publishing is public access to the npm registry, and the version field currently reads 4.0.0-beta.8 with the package published as @nutui/nutui-react. The engines field requires pnpm >=10.34.5, which is a specific and recent requirement, and it is pnpm rather than npm, so an npm-based project will need to adjust its tooling.

Three versions in flight, and the branch that is not master

The version situation is the main thing to sort out before using this library, and it is more complicated than the release list first suggests.

The default branch is feat_v4.x, not master or main. The recent releases listed are v3.0.23-cpp on 2026-09-03, v4.0.0-beta.6 on 2026-08-10 and v4.0.0-beta.5 on 2026-07-22, and the package.json in the repository reads 4.0.0-beta.8, so the beta line has moved past the tagged betas in the repository itself.

So there are two live lines. The v3 line is the stable one and it has been getting its own point releases, with the September 2026 v3.0.23-cpp being the most recent. The v4 line is in beta, which means the API may still change between beta tags, and a project that installs 4.0.0-beta.8 is installing a prerelease. The betas have been arriving roughly every three weeks since at least July 2026, so the line is moving, and it is moving under a feature branch rather than under the default branch name most people would clone.

The repository is not archived and the last push was on 2026-10-18, so this is active work rather than a maintained-but-frozen project. The distinction matters for a component library, where a component's markup and props are the API your design system has to wrap.

There is a companion document in the repository root for the design specification, the component standard whitepaper, and the CHANGELOG.md and CONTRIBUTING.md are both present. The i18n work is called out in the contribution guidance as one of the ways to help, along with solving issues, fixing bugs, adding new components, UI customization, and platform and cross-end adaptation.

The practical reading is that a team that wants a stable dependency should use the v3 line, and a team that wants the latest component set and is prepared to track betas should use the v4 line, and in both cases should read the migration notes for the version boundary before switching.

Where nutui-react is the wrong choice

There are three limits, and the first is a licensing one that has to be checked rather than assumed.

First, the licence. No licence is stated for this project, and there is no LICENSE file listed among the top-level entries, even though package.json declares MIT and the publishConfig points at the public npm registry. The MIT declaration inside package.json is what npm shows on the package page, and it is a reasonable basis for use, but the absence of a LICENSE file at the repository root means the full text and any additional terms beyond the field are not visible here. A company with an open source review process should get the actual licence text from the published package or from the vendor before shipping.

Second, the design system coupling. The components are based on the JD APP 11.0 visual specifications, which means the shapes, spacing and metrics are one company's design language rather than a neutral set of primitives. If your product is not JD-branded, you are either accepting the look and adjusting tokens where you can, or you are overriding the styles component by component, which is the maintenance cost that a headless design system would avoid. The theming support and the custom theme tooling help here, but the base specification is still JD's.

Third, the mini-program target is a commitment, not a convenience. Supporting H5 and WeChat and JD mini-programs means the component implementations sit inside an abstraction layer, and abstraction layers leak. The JDTaro path needs a specific pnpm configuration to work, and it has a separate set of scripts and an extra build target for harmony cpp, and the README itself points you at the demo directory's package.json for platforms beyond the three it names. A team shipping only H5 is carrying this complexity for a feature they do not use.

And a fourth, more mundane one. The repo's own tooling is pinned tightly: pnpm >=10.34.5 in the engines field, commitlint, husky, lint-staged, eslint, stylelint and prettier, plus Cypress for end-to-end and Vitest for units with a 90%+ coverage claim. A team that already has a different toolchain will spend time reconciling it.

nutui-react against the alternatives

The comparison that matters depends on whether you actually need the mini-program target, because that is what separates the options.

If you do need to ship to WeChat and JD mini-programs, then the choice is between a library that compiles to those targets and a pair of separate codebases. NutUI React's approach is one React source that compiles down through Taro or JDTaro, so a design change lands in both outputs from a single commit. The cost is that your components are written against a cross-platform abstraction, so anything the abstraction does not model, a native mini-program API, a specific platform gesture, is either unavailable or needs a platform-specific path. The repository's platform scripts and the separate style variants, jmapp, jrkf, daojia, all point at a project with several platform flavours baked into its build, which is the shape of that cost.

If you do not need mini-programs, then the comparison is with a plain React component library, and NutUI React is not obviously better. You would be taking a JD-styled, mobile-focused toolkit with a multi-target build system, and you would be paying for the Taro compatibility in bundle configuration and in the abstractions.

The third option is a company design system. Many teams that need a JD-consistent or brand-consistent mobile interface build their own component library on top of a primitive set, and that gives complete control over the tokens, the accessibility behaviour and the platform coverage. The cost is that you build and maintain it, and NutUI React exists precisely to avoid that, by shipping the components and the specification and the Sketch resources and the whitepaper.

There is a fourth option worth naming, which is a mini-program-specific component library. If your product is a mini-program first and the H5 build is the afterthought, those are the more direct fit.

So the deciding question is: does one codebase have to serve H5 and a mini-program, and does the visual language have to be JD's? If both answers are yes, NutUI React is doing something specific and worth the toolchain. If either is no, a plain React library or your own design system is the cheaper path.

Editorial conclusion

Adopt nutui-react if you are building a Chinese-market mobile front end and need one component set to compile for H5 and for WeChat or JD mini-programs, and you accept a JD-specific visual language. Do not adopt it if you need a platform-neutral design system, since the components are specified against the JD APP 11.0 visual specification, and check the line you install, since the v4 tags are beta while the v3 line has its own releases. Verify first that your pnpm version satisfies the >=10.34.5 engine requirement, that the platform you target has a documented build script, and that the theme and RTL options your design needs exist in the version you pin.

Frequently asked questions

Official sources

1. Issues
2. jdf2e/nutui-react on GitHub
3. Project website
4. README
5. Releases