title: Getting Started type: guide group: Overview order: 1.1 version: 2.1
What is Weex?
Weex is a framework for building high-performance mobile applications with a modern web development experience.
Weex enables developers to use a modern web development experience to build Android, iOS, and web apps with a single codebase. In practice, you can use JavaScript and modern front-end frameworks to develop mobile apps after integrating the WeexSDK.
The structure of Weex is decoupled; the render engines are separated from the syntax layer. Weex does not rely on any specific front-end framework, but it does mainly support Vue.js and Rax.
A primary goal of Weex is to keep up with modern development technologies and platform capabilities, both for web and native applications. Productivity and performance can coexist in Weex. Writing Weex pages feels the same as writing web pages. In fact, rendering Weex pages is the same as rendering native pages.
Overview
If you just want to try Weex, you do not need to install anything. There is an online playground for Weex wherein you can write single page examples without any installation or configuration. The source code should be written in Vue.js single file component syntax (also known as *.vue files), and the rendered result from editor pane will be displayed in a mock phone shell.
Here is an example written in Weex and Vue.js:
This example renders the word “Yo” in the center of the screen. If you want to preview the rendered result on a mobile device, either install the Weex playground app or integrate the Weex SDK into your own app, then scan your page's QR code with the app. This will load the URL with the Weex SDK.
Within the <template> node in the source code, you will notice the <div> element—this generic HTML element also serves as the generic “container” element in Weex. The <text> component, however, is provided by Weex and is a block-level text container.
A raw text node can only be placed in a
<text>component. Otherwise, it will be ignored.
Within the <style> tag, you can write CSS to describe the styles of a component. Those styles are scoped forcibly in Weex.
Native Components
In the example above, the <div> and the <text> elements are rendered into corresponding native views on the mobile device. As such, they do not implement the HTMLElement interface.
Weex implements render engines both on iOS and Android. It also provides a group of built-in components for basic usage. You can compose and wrap custom components using these basic components.
Note: Although the components in Weex may look like HTML tags, you are not able to use the full suite of HTML elements; you are restricted to built-in components and your custom components.
Behind the scenes, Weex uses native widgets. Although Weex emphasizes consistency on each mobile platform, we still embrace the platform's own behavior and UI differences. For example, the <switch> component may look different on Android and iOS (the appearance on the web simulates iOS).
If you want to use additional native components, other than the built-in components provided by Weex, you need to implement them on each platform and keep their behaviors consistent. The most practical way is to integrate the existing native components to Weex platform. /_ need explanation _/
Native Modules
For those features that do not rely on the UI, Weex wraps them into modules. You can use weex.requireModule('xxx') to require them. Weex modules provide easy access to native capabilities in JavaScript, such as network, storage, clipboard, and navigator. For example, you can use the stream module to fetch the star count of Vue.js.
Similarly, Weex provides a group of built-in modules for basic usage, and supports the integration of existing native modules into the Weex platform.
Here are some documents about how to extend native components and native modules for Weex:
Write Once, Run Everywhere
Yes, Weex can build for Android, iOS, and Web apps from a single codebase.
Using the same source code across different platforms improves development productivity, simplifies testing, and streamlines building and publishing. Weex combines front-end packaging and testing processes with those of mobile publishing and monitoring, dramatically improving development efficiency.
You can read How it works and Design Principles to know more about the technologies and ideas behind Weex.
Although Weex uses a single codebase, you can still write platform specific code. Weex provides weex.config.env and WXEnvironment (they are strictly equal) to get the current runtime environment. You can use WXEnvironment.platform to determine which platform the code is running on. Apart from the platform, WXEnvironment contains other information pertaining to environment, such as osVersion and deviceModel. Refer to Weex variable for the complete list.
Support For Multiple Front-End Frameworks
Front-end frameworks are the syntax layer of Weex; therefore, they are decoupled from native render engines. Weex does not bind with any specific front-end frameworks. Instead, Weex brings native capabilities to the front-end.
Weex supports Vue.js and Rax as its internal front-end frameworks.
- Vue.js is a progressive front-end framework for building user interfaces.
- Rax is a front-end framework with React-compatible APIs.
Vue.js and Rax are already integrated into Weex SDK, so you don't need to require them manually.
However, Vue and Rax are not the only options. It is entirely possible to integrate your favorite front-end framework into Weex! The document Extend JS Framework describes how to integrate a different front-end framework. The process, however, is still complicated. You need to understand many underlying details about the js-native bridge and native render engines in order to successfully integrate an alternate front-end framework.
Read Front-End Frameworks for more details.
Create Your Own App
The following steps assume basic knowledge of Node.js and npm. If you are not familiar, you can visit https://docs.npmjs.com/ to learn more about npm, and https://nodejs.org/en/docs/ to learn more about Node.js.
Weex provides a command line tool, the weex-toolkit, to help developers get started more easily. The CLI can help you create a starter project, set up iOS and Android development environments, debug, install plugins, and so on.
Currently, weex-toolkit only supports the creation of Vue.js projects. The rax-cli may be helpful if you want to use Rax. Please visit Rax's official website for more details.
Setup
With Node.js installed, install weex-toolkit CLI globally.
npm install weex-toolkit -g
This will add the weex command to your global path, and will allow you to generate new projects with the weex create <project-name> command. Use weex create to create a starter project:
weex create awesome-app
After doing that, a standard Weex + Vue.js project will be generated inside the awesome-app folder in the current path.
Develop
The next step is to navigate into the generated directory, install dependencies, and start:
cd awesome-app npm install npm start
npm start will start a web server on port 8081. Open http://localhost:8081 in your browser of choice to see the rendered result of your Weex app. The source code is located in the src/ directory. You can develop it as a normal Vue.js project.
Additionally, you can open http://localhost:8081/web/preview.html to preview the rendered result on the web in an iframe. You can also scan the QR code generated on the right using the Weex playground app to see the rendered result on a mobile device.
Build and Run
By default, the weex create command doesn't create an iOS or Android project, but you can use weex platform add to add them.
weex platform add ios # for iOS weex platform add android # for Android
Depending on your network environment, it may take a while to add them. Please be patient.
In order to develop the app on your local machine, you need to set up a mobile development environment. For iOS, you should install Xcode. For Android, you should install Android Studio. When the development environment is ready, run the commands below to launch your app on the simulator or on the device.
weex run ios
weex run android
weex run web
Debug
weex-toolkit can also be used to debug your mobile apps. Just run:
weex debug
Running weex debug will start a debug server and open a web page in Chrome (only supports the V8 engine). For technical details on weex-toolkit, please refer to the toolkit document.
Next Steps
At this point, you should have a general understanding of Weex. The next step is to explore and try the advanced features of Weex.
If you want to use Weex right now:
If you want to know more about the technologies and ideas behind Weex:
After getting acquainted with Weex, if you want to contribute to make it even better:
Considering that Weex is a cross-stack technology, fundamental knowledge of front-end development, Vue.js, iOS, and Android will be especially helpful when contributing.