Native Mobile Apps with Vue.js and Weex: Getting Started

Joshua Bemenderfer

When it comes to developing native mobile apps with JS frameworks, React has React Native, Angular has NativeScript, but what does Vue have? Well, it has weex. (Technically NativeScript has early support for Vue as well.) Okay, so what’s weex? It’s similar to React Native, but with a more DOM-like API and flexible render backends. (It’s able to render to websites as well.) Primarily spearheaded and used by Alibaba, arguably the largest internet company in China, it has plenty of commercial backing, and recently has become an Apache Incubator project as well.

Sounds pretty great, right? Well, almost. Weex is still under heavy development, with some components being far more mature than others. The English documentation could also use some serious help. The vast majority of developers and users are Chinese. But once you get past the initial bugs and tricky grammar, it works surprisingly well.

Getting Set Up

Weex can be used for web development (yes, really!), but most users will be looking to develop native apps on Android and / or iOS. In order to develop for those platforms, you’ll need all the necessary dependencies first.

If you just want to test weex out, there's a web-based playground available here. There are also quite a few examples.

Worried you might mess something up? Try the NativeScript quick setup scripts. Yes, they’re for NativeScript, but really all they do is automatically prepare your Android and iOS development environments.


  • Install Java JDK 8.
  • Install Android Studio or android-sdk and/or the command-line tools. Make sure to set JAVA_HOME and ANDROID_HOME! If you don’t have an Android device, you’ll also want an emulator.



Weex comes with an incredibly convenient (if somewhat buggy) command-line tool that will automatically create and configure weex projects for you.

To install it, run npm install -g weex-toolkit

If the instructions here aren't working, check the official docs, as weex-toolkit and much of the related tooling is work-in-progress.

Creating an App

Here’s where the fun beings.

To create an app, run weex create my-app-name. After answering a few questions, you should have a fresh example weex project created in the my-app-name folder. (Change to that directory now.)

To enable iOS support (on macOS) run weex platform add ios. And to enable Android support (any platform) run weex platform add android. Assuming everything is configured properly, those commands should work fine and you’ll be completely set up!

You’ll find your app’s source code in the src directory, platform-specific data in the platforms directory, and you’ll see some platform-specific *.config.json files sitting around in the root.


QR Code + Playground

The simplest way to test and preview your (Android or iOS) app (with live-reload) on a real device is with the Weex Playground App. To do so, run npm start. This will start webpack and open the web version of your app in a browser, along with a QR code you can scan with the playground app. As long as your computer and mobile device are on the same network and reachable, you should be able to use that to test your native app.

Android phone

If the playground isn’t an option, you can test on a real Android device connected via USB. (Make sure you have [adb] installed first, and USB Debugging enabled on your phone.) Once that’s ready, connect your phone to your computer with a compatible USB cable and run npm run android.

It will take awhile to install all the dependencies and set up gradle, but eventually you will be rewarded for your efforts when your brand-new app opens on your phone. Note: The app will have a header allowing you to refresh and scan a QR code for testing. To remove this, take a look in the troubleshooting section below.

iOS simulator

Building an iOS app? You can test it in a simulator using npm run ios. It will take quite awhile for the app to build and the simulator start, but once it’s ready, you’ll be greeted by a fresh new native app built with Vue.js.

This is more of an advanced project than usual, but you’ll still want your typical webpack-simple setup to work with.

Once you’ve got that, go ahead and replace the contents of your App.vue component with this. (I won’t bother explaining it for now, as it’s not the focus of this article. This is just the app template and updates the chart values randomly.)

All methods have support for live reload and should render identically. (If not, report a bug.)

An app written with Weex running on Android.

Go ahead and hack on your app just like you would for any Vue.js project! Even Vuex and vue-router are supported!



To build your app for Android, run npm run pack:android. In a few minutes there should be a completed weex-app.apk file sitting in release/android. You can transfer it to your phone and install it, or get it signed and uploaded to Google Play or a similar app store.


Building an app for iOS is (naturally) a bit more involved. You’ll need to get your developer profile and code signing credentials all set up. If you’re not sure how to do this, then now’s the time to go learn how. It’s too involved for me to explain here. Once you’ve got that prepared, paste the path to your code signing certificate in ios.config.json’s CodeSign field, and the path to your provisioning profile key in Profile. Don’t forget to change your AppId as well!

Once that’s all set up (hopefully), run npm run pack:ios.


  • My app has an annoying header thingy on Android! How do I get rid of it?
    • Weex “helpfully” provides that during development. To remove it, edit platforms/android/app/src/main/AndroidManifest.xml and add an android:theme key to the element:
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android=""
            <!-- You can remove this as well -->
    • For Android apps, you’ll be spending a lot of time in the platforms/android/app/src/main directory editing icons and resources and such, just like normal apps. Once you get a handle on it, you can pull out most of the dependencies related to the QR code scanner and loader.
  • My app has an annoying splash screen on Android!
    • To get rid of or customize it, try editing platforms/android/app/src/main/java/com/weex/app/ It’s fairly easy to understand.
  • I can’t create a project or add a platform on Linux!
    • Right now weex-pack (the tool uesd to generate projects) has several bugs related to case-sensitive filesystems that affect project creation and platform addition. Hopefully those will be resolved soon, but in the meantime you can just rename the offending files. Keep in mind that Chinese doesn’t have uppercase and lowercase, so such mistakes are more common and missed since Windows and macOS having case-insensitive filesystems.
  • What other alternatives are there for building native apps with Vue?
    • nativescript-vue NativeScript… but using Vue! It’s not quite as far along as weex, and I had some trouble getting it set up properly, but it’s a viable competitor.
    • react-vue Fun fact. You can compile Vue components to run on React Native! Not really worth much outside of experimental usage, but it’s a neat idea.

For more information, consult the official Weex documentation. It’s still a bit early to use in production, but the future looks promising!

  Tweet It

🕵 Search Results

🔎 Searching...