Tencent Hippy: a cross-platform framework for React and Vue developers

What Hippy is for, and who ends up using it

Hippy targets a specific kind of team: one that already writes React or Vue for the browser and now needs the same screens inside a native app. The README states the goal plainly, that developers write once and run on iOS, Android and the web, and that the framework is friendly to people familiar with React or Vue. That is a narrower promise than a general cross-platform toolkit. It assumes a JavaScript codebase exists and that the hard part is getting it onto a phone without rewriting it in Swift and Kotlin.

The README also lists where Hippy runs in production: Mobile QQ, Mobile QQ Browser, Tencent Video, QQ Music and Tencent News. Those are large consumer apps with their own native engineering teams, which tells you the intended scale. A solo developer building a two-screen utility is not the audience. Neither is a team that wants to avoid touching Xcode or Gradle, because the setup path goes straight through both.

How the JavaScript layer and the native renderer fit together

The repository is split into directories that map to the architecture: driver, framework, renderer, dom and modules. The JavaScript side lives under driver/js, where Lerna manages multiple npm packages. The README names the front-end SDK packages as @hippy/react, @hippy/vue and @hippy/vue-next, which is why the same component code can target three different authoring styles. The renderer and dom directories hold the part that turns component trees into native views, and the README points at Tencent's taitank project as the Flex layout engine underneath.

Communication between JavaScript and native code is described in the README as JS engine binding communication. On Android the README says Hippy uses the X5 JS engine. That detail has a practical consequence the README spells out: X5 cannot run on an x86 emulator, and an ARM emulator performs poorly, so Android development is expected on a real phone over USB. The build-in recyclable component mentioned in the advantages list is the other performance lever, aimed at long lists where view recycling matters more than raw render speed.

Building the iOS demo: npm run init, buildexample, pod install

The README's getting-started path starts at the repository root with git and npm, and it warns that the repository uses git-lfs for so, gz and otf files, so git-lfs must be installed before cloning or the native artifacts will be pointers instead of binaries. After cloning, npm install runs at the root. The root package.json sets engines.node to >=16.0.0, which is stricter than the >=10.0.0 badge shown in the README, so trust the package.json when choosing a Node version.

From there the iOS route goes through driver/js. The init script is a composition of three commands, and the README explains each one: npm install for build-script dependencies, npx lerna bootstrap for the per-package dependencies, and npm run build for the front-end SDK packages.

cd driver/js
npm run init
npm run buildexample hippy-react-demo

The buildexample script takes one of hippy-react-demo, hippy-vue-demo or hippy-vue-next-demo. If lerna is missing, the README says to run npm install lerna -g first. The last two steps are macOS-only: install CocoaPods and cmake with Homebrew, then run pod install inside framework/examples/ios-demo, which produces HippyDemo.xcworkspace. Opening that workspace in Xcode is what builds the simulator app.

brew install cocoapods
brew install cmake
cd framework/examples/ios-demo
pod install

For Android the front half is identical, but the second half happens in Android Studio: open the project at the repository root, connect a phone with USB debugging enabled, check it with adb devices, and run. The README adds a blunt instruction not to update the build toolchain, which is the kind of warning that usually means a Gradle or NDK upgrade has broken the build before.

Debugging the demo against the local SDK packages

Once an app is on a device or simulator, the debug loop is separate from the build loop. The README describes a two-step sequence: run npm run init:example with one of the three demo names, then run npm run debugexample with the same name plus the argument dev.

cd driver/js
npm run init:example hippy-react-demo
npm run debugexample hippy-react-demo dev

The README notes that cd-ing into driver/js/examples/hippy-react-demo and running npm run hippy:dev is an equivalent route. The detail that matters for anyone modifying the SDK itself is the linking behavior: in debug mode, packages such as @hippy/react, @hippy/vue and @hippy/vue-next resolve to driver/js/packages/[package]/dist rather than to node_modules. Editing package source therefore requires a rebuild of that package before the change appears in the demo. That is a normal monorepo arrangement, but it catches people who expect a hot reload of library code.

Where Hippy gets in the way

The first limitation is the toolchain surface. Building Hippy means Node, npm, Lerna, git-lfs, Xcode with the iOS SDK, Android Studio with the NDK, CocoaPods, cmake and a shell that can run all of it. The README explicitly says Windows cannot run the iOS development environment, so a Windows-only team cannot produce an iOS build from this repository. That is a hard boundary, not a preference.

The second is the pinned toolchain. The instruction not to update the build toolchain, together with the linked workaround for the mips64el-linux-android NDK toolchain error, suggests the build is sensitive to Android Studio and NDK versions. Teams that keep their Android tooling current will spend time reconciling that with Hippy's expectations.

The third is documentation placement. The README links iOS and Android integration guides at doc.openhippy.com, and the homepage is framework.tds.qq.com, so the repository README is a starting point rather than a reference. The README does not document rollback, version pinning strategy or a migration path between the LTS lines, and the release list shows three LTS releases (2.17.6, 2.15.10 and 2.15.9) maintained in parallel, which implies a choice the README does not help you make. Hippy is also the wrong tool if your app is mostly native screens with a few dynamic ones, or if you need the same code to run on desktop.

How Hippy differs from React Native and Flutter

React Native is the closest comparison and the most useful one. Both let React developers target iOS and Android, and both bridge JavaScript to native views. The difference visible in this repository is the multi-framework surface: Hippy ships @hippy/vue and @hippy/vue-next alongside @hippy/react, so a Vue team is a first-class audience rather than an afterthought. Hippy also names its own layout engine, taitank, where React Native relies on Yoga, and it uses the X5 JS engine on Android, which is a Tencent component with its own device and emulator constraints.

Flutter differs at a more basic level. It renders its own widgets rather than mapping component trees onto platform views, and it uses Dart rather than JavaScript. That means a Flutter team does not reuse existing React or Vue code at all. If your codebase is already React or Vue, Hippy's premise applies to you and Flutter's does not. If your team has no JavaScript investment and wants one rendering model across platforms, the calculus reverses.

Editorial conclusion

Adopt Hippy if you already ship React or Vue on the web and need the same component code inside a native app whose build you control, and if your team can absorb a Lerna monorepo, git-lfs, CocoaPods and a pinned NDK toolchain. Do not adopt it for a small app, for a Windows-only team that needs iOS, or if you expect a one-command scaffold. Verify first that the demo builds on your own machines: run npm run init in driver/js, install the three demos with npm run buildexample, and confirm that pod install succeeds in framework/examples/ios-demo before you plan any product work around it.

Frequently asked questions

Official sources

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