Hippy: the Android build that tells you not to update the toolchain

Two LTS lines, and a main branch ahead of every tag

The three most recent releases are all labelled LTS in their titles: 2.17.6 and 2.15.10 both dated 2026-03-30, and 2.15.9 dated 2026-01-19. That is two separate LTS lines two minor versions apart, released on the same day, which tells you the project maintains a current line and a previous one rather than a single trunk.

The gap between tags and commits is the part worth noticing. The repository is not archived and its last commit is dated 2026-10-28, roughly seven months after the newest tag. So the two states are genuinely different: a build pinned to the newest published tag misses seven months of later commits, and the recent commits exist on the main branch with no release tag covering them.

What that costs you is a decision that has to be made deliberately. Track the 2.17 line for current fixes and the 2.15 line for stability, or build from main and accept that nothing is released. Whichever you pick, the pin belongs in your dependency declaration and in your CI image, because a build that resolves the newest tag each week will drift without anyone changing a line of code. The project also keeps CHANGELOG.md and PUBLISH.md at the repository root.

The X5 engine rules out the x86 Android emulator

For Android the project tells you to use a real cellphone rather than a simulator, and gives the reason: Hippy uses the X5 JS engine, which cannot support the x86 simulator, while the ARM simulator has low performance. That is a hardware constraint, not a preference, and it shapes the whole development loop.

The documented flow assumes the handset in front of you. Open the Hippy Project at the repository root with Android Studio, connect the phone with a USB cable, make sure USB debugging is enabled, check the connection with `adb devices` on the computer terminal, then run and install the apk from Android Studio. There is no emulator step in that sequence.

The consequence for a team is that the inner loop lives on physical devices. Every change to a JS component means build, deploy, install and look at a phone, so cycle time is set by hardware rather than by a fast emulator, and parallel device testing means owning devices. Continuous integration inherits the same limit: a runner without an attached handset cannot exercise the X5 path, so the part of your pipeline that actually runs the framework code is the part that is hardest to automate. The X5 engine site is linked from the repository.

DO NOT update the build toolchain

Before building for Android, the project says to make sure the SDK and NDK are installed, and then, in capitals, to not update the build toolchain. That instruction is short and it is the one most likely to be ignored, because Android Studio updates components on its own and because almost every other project wants the newest NDK.

The failure it prevents has a recognisable error message:

> No toolchains found in the NDK toolchains folder for ABI with prefix: mips64el-linux-android

Read that message carefully before acting on it, because the ABI it names, mips64el-linux-android, is not one any current phone uses. The repository links a discussion about the same error as the fix.

Two consequences for anyone adopting this. First, the toolchain state becomes part of your build contract: pin it, record the NDK and Studio versions you validated, and say so in your contributor documentation, because the failure mode is a native build error that looks like a missing dependency. Second, expect setup instructions to age badly. The Android build steps do not name the versions that satisfy this chain, so the first thing to do on a new machine is establish a working combination and freeze it, rather than assuming the newest release of each tool works.

Debug mode links packages to dist, not node_modules

After the app is built, the demo debugging flow runs two commands from `driver/js/`.

npm run init:example [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]
npm run debugexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo] dev

You can also `cd` into `driver/js/examples/hippy-react-demo`, `driver/js/examples/hippy-vue-demo` or `driver/js/examples/hippy-vue-next-demo` and run `npm run hippy:dev` instead.

The detail that costs people an afternoon sits in the note below those steps. In example debug mode, npm packages such as @hippy/react, @hippy/vue and @hippy/vue-next are linked to `driver/js/packages` and then to the dist directory of the relevant package, not to node_modules. The consequence: if you change JS package source code and expect it to take effect in the target example, you must call `npm run build` again. Editing the framework's own JavaScript and seeing no change in the demo is not a bug in your component and not a stale build of the app, it is a link pointing at built output. The debugging documentation is linked from the repository for the rest of the workflow.

Windows can build Android, never iOS

The platform prerequisites are split in a way that decides who can ship what. macOS developers need Xcode with the iOS SDK to build the iOS app, Android Studio with the NDK to build the Android app, and Node.js to run the build scripts, with homebrew recommended for installing dependencies. Windows developers need Android Studio with the NDK and Node.js. In both cases git and npm are prerequisites, and git-lfs has to be installed before the first clone.

The line in the docs that decides the team topology is that Windows cannot run the iOS development environment so far. A Windows-only team can produce Android builds and nothing else from this project.

That has two consequences. Your release pipeline needs a macOS runner for the iOS side, whatever the rest of your infrastructure looks like, and cross-platform parity for a release depends on someone with both toolchains installed. On the iOS side the extra steps are CocoaPods and cmake through homebrew followed by `pod install` in `framework/examples/ios-demo`, which creates the `HippyDemo.xcworkspace` files that Xcode then opens. Building straight onto a physical iPhone instead of the simulator is possible by changing the Xcode configuration, but the project recommends the simulator for a first attempt.

git-lfs and Lerna sit between you and the first build

The first steps are unglamorous and each one can stop the build. Clone the repository and run `npm install` at the project root.

git clone https://github.com/Tencent/Hippy.git

The repository applies git-lfs to manage its so, gz and otf files, so git-lfs has to be installed before cloning or the checkout is incomplete in a way that only shows up later as a native build error. Node 16.0.0 is the floor, declared in the root package.json engines field.

From there the work happens in `driver/js/`, and `npm run init` is three commands in one.

npm run init

It runs `npm install && npx lerna bootstrap && npm run build`: the first installs the build script dependencies, the second installs dependencies for each npm package, and the third builds each front-end sdk package. Hippy uses Lerna to manage multiple JS packages, and if the lerna command is not found you are told to run `npm install lerna -g` first. You then pick a demo with `npm run buildexample [hippy-react-demo|hippy-vue-demo|hippy-vue-next-demo]`.

Two things to know about the failure paths, both documented. If `npm run init` errors, you can `cd` into the demo under `driver/js/examples` and run `npm install` there first. And note what the root package.json is: it is marked private, its only scripts are markdownlint, a docsify server and a husky install, so `npm install` at the root builds nothing. The JavaScript build lives entirely under driver/js, and the native build lives under framework.

Flex is the layout engine you are committing to

The layout story is narrow and specific: Flex layout is described as fully supported, with the engine itself living in a separate repository, Tencent/taitank. Alongside it sit same APIs across platforms, communication through JS engine binding, a built-in recyclable component, and a smooth path to running the result in a web browser.

Those four claims are the whole value proposition, and each one has a consequence. Same APIs across platforms means your component tree cannot assume browser-only behaviour, so code lifted from a web project needs a pass for anything the framework does not implement. JS engine binding communication means the bridge between JavaScript and native is part of the design rather than something layered on later.

What the repository does not give you is a wider layout story. Flex is named as fully supported and linked to its own engine, so if your design depends on CSS features outside Flex, check support before you commit a screen to this framework. The stated ability to migrate smoothly to a web browser cuts both ways: it makes the web your fallback destination, and it also means the code you write is expected to run in a browser that has the full CSS model.

Commit conventions and doc linting are enforced locally, not in CI

The root package.json is worth reading as a map of how work is policed. Its scripts are `markdownlint --config .markdownlintrc.json` over the README files and everything under `docs/`, `docsify serve docs` for local documentation, and a prepare hook that runs `is-ci || husky install`. That last one installs the git hooks on any machine that is not a CI environment, so the checks land before code leaves your laptop rather than after a pull request.

Commit messages are policed by commitlint, wired through `commitlint.config.js` and a commitlint-plugin-function-rules plugin, with the conventional config among the dev dependencies. The practical effect is that your commit history has to match the convention the plugin enforces, and a message that violates it can be stopped by a hook rather than by a reviewer.

Two smaller signals in the same file. The devDependencies are documentation and lint tooling rather than runtime code, which reinforces that the JavaScript build system lives under driver/js and not at the root. And the repository keeps its native build entries visible at the top level: hippy.podspec for CocoaPods, xcodeinitscript.sh for the Xcode build, gradlew and gradlew.bat alongside build.gradle and settings.gradle for Android, oh-package.json5, build-profile.json5 and hvigorfile.ts, plus PrivacyInfo.xcprivacy and PUBLISH.md. If your build system does not speak one of those, you are integrating at the edges rather than importing a package.

Editorial conclusion

Hippy makes sense for a team that already ships React or Vue and wants the same component code on iOS, Android and the web, and that can afford the native toolchain the build assumes. It does not make sense for a Windows-only team, for anyone who wants to iterate on an Android emulator, or for a project that expects a current published tag to reflect the repository's latest commits. Before committing, confirm which of the two LTS lines you are tracking, install git-lfs before the first clone, keep the Android build toolchain where the project expects it, and remember that a JS source edit needs `npm run build` before it shows up in a demo.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. Tencent/Hippy on GitHub