uni-app

Environment installation

Create uni-app

Custom templates

Special cases in China

更新依赖到指定版本

Run and release uni-app

Run and publish the quick app

Run and publish the quick app (webview)

Run and publish a quick app (webview) - Huawei

Difference between cli creation project and HBuilderX visual interface creation project

Expand All

In addition to the HBuilderX visual interface, you can also use cli scaffolding, and you can create an uni-app project through vue-cli.

# Environment installation

Install vue-cli globally

npm install -g @vue/cli

# Create uni-app

Use the official version (corresponding to the latest official version of HBuilderX)
```
vue create -p dcloudio/uni-preset-vue my-project
```
Use the alpha version (corresponding to the latest alpha version of HBuilderX)
```
vue create -p dcloudio/uni-preset-vue#alpha my-alpha-project
```
Use Vue3/Vite version
- Create a project developed with javascript (if the command line creation fails, please visit gitee to download the template directly)
```
npx degit dcloudio/uni-preset-vue#vite my-vue3-project
```
```
npx degit dcloudio/uni-preset-vue#vite-alpha my-vue3-project
```
- Create a project developed with typescript (if the command line fails to create, please visit gitee directly to download the template)
```
npx degit dcloudio/uni-preset-vue#vite-ts my-vue3-project
```

At this point, you will be prompted to select a project template (the Vue3/Vite version will not prompt, currently only the default template can be created). It is recommended to select the hello uni-app project template for the first experience, as shown below:

Notice

Vue3/Vite版要求 node 版本 18+、20+
If you use HBuilderX (below version 3.6.7) to run the latest cli project created by Vue3/Vite, you need to set the node path at the bottom of the HBuilderX running configuration to your local version node path (note that you need to restart HBuilderX to take effect)
- HBuilderX Mac version menu bar upper left corner HBuilderX->Preferences->Run Configuration->node path
- HBuilderX Windows version menu bar Tools->Settings->Run Configuration->node path

# Custom templates

When choosing a custom template, you need to fill in the uni-app template address, which is actually the address of the repository hosted in the Cloud. Take GitHub as an example, the address format is userName/repositoryName, such as dcloudio/uni-template-picture is to download the image template.

For more supported download methods, please refer to the description of this plug-in: download-git-repo

# Special cases in China

The template project is stored in Github. The download may fail due to network problems in China. To solve this problem, the following measures can be taken:

Change the network and retry, such as using 4g network
Add DNS (e.g.: 8.8.8.8) to the network settings of the device or router
Add fixed hosts (e.g.: 140.82.113.4 github.com) to the equipment

# 更新依赖到指定版本

You can use @dcloudio/uvm to manage the version of the compiler. This tool only automatically adds or updates the main dependencies of the uni-app compiler. For new Compilation commands (scripts) of the command line will not be processed automatically for the time being, and need to be manually configured with reference to the new project.

Update to the latest official version
```
npx @dcloudio/uvm@latest
```
更新到最新 Alpha 版
```
npx @dcloudio/uvm@latest alpha
```

Update to the official version specified version

npx @dcloudio/uvm@latest 3.2.0

或

npx @dcloudio/uvm@latest 3.2.12.20211029

更新到 Alpha 版指定版本

npx @dcloudio/uvm@latest 3.2.0-alpha

或

npx @dcloudio/uvm@latest 3.2.14.20211112-alpha

# Run and release uni-app

npm run dev:%PLATFORM%
npm run build:%PLATFORM%

The possible values of %PLATFORM% are as follows:

Value	Platform
h5	H5
mp-alipay	Alipay Mini Program
mp-baidu	Baidu Mini Program
mp-weixin	微信小程序
mp-toutiao	抖音小程序
mp-lark	Feishu Mini Program
mp-qq	qq applet
mp-360	360 Mini Program
mp-kuaishou	Kaishou Mini Program
mp-jd	JD Mini Program
mp-xhs	Xiaohongshu Mini Program
quickapp-webview	Quick App(webview)
quickapp-webview-union	Quick App Union
quickapp-webview-huawei	Quick App Huawei

You can customize more conditional compilation platforms, such as DingTalk applet, refer to package.json document.

# Run and publish the quick app

There are two development methods for quick apps, both of which are supported by uni-app:

Small program webview rendering method: https://ask.dcloud.net.cn/article/37182
Native rendering method: https://ask.dcloud.net.cn/article/37145

# Run and publish the quick app (webview)

HBuilderX version 2.7.12+ support

# Run and publish a quick app (webview) - Huawei

HBuilderX version 2.7.10+ support

Huawei Quick App Documentation - Mini Program Quick App [https://developer.huawei.com/consumer/cn/doc/development/quickApp-References/quickapp-filestructure](https://developer.huawei.com/consumer/ cn/doc/development/quickApp-References/quickapp-filestructure)

Others:

Currently using npm run build:app-plus will generate app packaging resources under /dist/build/app-plus. To make a wgt package, compress the files in app-plus into zip (note: do not include app-plus directory), and rename it to ${appid}.wgt. appid is the appid in manifest.json file.
The code for each platform compiled in dev mode is stored in the /dist/dev/ directory under the root directory. Open the development tools of each platform and select the corresponding platform directory to preview (the h5 platform will not be in this directory, but will exist in the cache);
The code for each platform compiled in build mode is stored in the /dist/build/ directory under the root directory, and this directory is selected for publishing when publishing;
Differences between dev and build mode:
1. dev mode has SourceMap for easy breakpoint debugging;
2. build mode will compress the code to be smaller and more suitable for releasing as official application;
3. When performing environment judgment, the dev mode process.env. The value of NODE_ENV is development, and the value of process.env.NODE_ENV in build mode is production.

# Difference between cli creation project and HBuilderX visual interface creation project

The project created by cli is the traditional node project structure. The project code is in the src directory, the compiler is in the project, and the compilation result is in the dist directory.
The project created visually by HBuilderX is a node-free development concept. The project code is in the project directory, the compiler is in the HBuilderX directory instead of the project, and the compilation result is in the unpackage directory of the project.

Some developers who are accustomed to cli are not comfortable when using the HBuilderX visualization mode. Explain their differences and why HBuilderX provides multiple ways.

# The project created by cli can also be dragged into HBuilderX for editing

First of all, as a general editor, HBuilderX is compatible with traditional cli development. Not only the cli of uni-app, but also the cli of other frameworks can be dragged into HBuilderX.

That is to say, you can use the visual interface to create projects in HBuilderX, or you can use the cli command line to create projects, which can achieve the purpose of better collaboration with uni-app. Such as pages.json jumps and prompts, manifest visual interface, conditional compilation, rpx and other css units... Many optimizations for uni-app can be used.

These are the characteristics of HBuilderX and have nothing to do with the project structure.

# If you want to develop uni-app with other IDEs, you can only use cli mode

Well understood. Because other IDEs do not have built-in uni-app compilers, other IDEs develop uni-apps and can only install the compiler under the project, which is the project format created by cli.

CLI projects can be developed using a variety of IDEs, but there are differences between IDEs:

HBuilderX has done a lot of optimization for uni-app, other IDEs can also be used with uni-app, but not optimized for uni-app
Other IDEs do not have uni-app apps and uniCloud running and debugging tools. These tools are in HBuilderX. For developing apps and uniCloud, HBuilderX must be used.

# Differences in visualization methods

HBuilderX creates, runs, and publishes projects visually, and the underlying calls are also npm's run, build and other commands. It's just that the compiler is not under the project, but in the directory of HBuilderX.

# Why provide HBuilderX visualization mode

In order to improve ease of use, lower threshold

Many developers are unfamiliar with node and have psychological resistance to the command line. Don't take it for granted that all developers can use node. HBuilder has millions of developers, and less than half of them master node.

Frequent problems with npm and github networks

When using cli to create a project, cli needs to be installed from npm, and the preset project template can be downloaded from github. These are often stuck due to network problems. Visually created projects do not have this problem.

It is too troublesome to have a set of compilers under each uni-app project

An HBuilderX developer has a lot of uni-app projects. If each project decentralizes a set of compilers, there will be many unreasonable: - Creating projects can be very slow - Very disk space intensive (uni-app's compiler has tens of thousands of files) - It is troublesome to upgrade, and there are many compatibility problems. The compiler under the cli project will not be upgraded with the upgrade of HBuilderX, and only the developer can upgrade by typing the npm command. When HBuilderX is upgraded, the compilers of some uni-app projects have not been upgraded, while others have been upgraded. Developers are easily confused when reporting errors, and DCloud is also confused when reporting bugs to DCloud. Keeping the ide version, compiler version, and uni-app runtime version consistent will reduce a lot of problems.

The compiler is built into HBuilderX, developers only need to care about their own business code when creating a project, and the project structure is clean and refreshing.

Every applet also does this. The compiler is in the applet development tool. When creating a project, it will not bring a set of compilers under the project (the applet also needs to compile wxml into js).

Automatic installation of less, scss, ts and other compilers

If you use the cli project, compilers such as less, scss, and ts need to be installed manually by typing the npm command. Since DCloud officially does not do compatibility testing with each version of each precompiler, if you use a lower precompiler version, it may not work properly, you need to check it yourself
If you use HBuilderX to create a project visually, these compilers will be automatically installed on demand, and DCloud has officially tested version compatibility. Developers only need to use these pre-compilation techniques in your code, and HBuilderX will take care of the rest automatically.

Visualization is more efficient

The node-free development provided by HBuilderX is not only easy to use, but also more efficient.

New project: Ctrl+N
Run the project: Ctrl+R
Release item: Ctrl+U

This is much faster than starting the terminal, moving the focus to the terminal window, and typing commands.

In uni-app, the terminal commands are more and longer than traditional web development, and you need to type the platform parameters to choose whether you want to run to the web or an app or a small program.

To sum up,

If you are used to node, you can also accept and manage the way of a set of compilers under each project, and know the above pros and cons, then you can choose cli to create a project.

As for ide, it is definitely more efficient to develop HBuilderX with uni-app.

If you are used to other IDEs and it doesn't matter if developing uni-apps is inefficient, you can use other IDEs too. But note that at least when running the debugging app and uniCloud, you have to open HBuilderX, just like opening the WeChat applet tool for debugging.

Inside DCloud, uni-app and HBuilderX are different teams.

For uni-app, it treats all IDEs equally. It is compatible with node ecology and supports d.ts syntax hints
For HBuilderX, uni-app is a first class citizen. HBuilderX does a lot of optimizations for uni-app

# Other Notes

cli 创建的项目，编译器安装在项目下。并且不会跟随HBuilderX升级。如需升级编译器，可以参考：更新依赖到指定版本。
已经使用cli创建的项目，如果想继续在HBuilderX里使用，可以把工程拖到HBuilderX中。注意如果是把整个项目拖入HBuilderX，则编译时走的是项目下的编译器。如果是把src目录拖入到HBuilderX中，则走的是HBuilderX安装目录下plugin目录下的编译器。
cli创建的项目，内置了d.ts，同其他常规npm库一样，可在vscode、webstorm等支持d.ts的开发工具里正常开发并有语法提示。
使用HBuilderX创建的项目不带d.ts，HBuilderX内置了uni-app语法提示库。如需把HBuilderX创建的项目在其他编辑器打开并且补充d.ts，可以在项目下先执行 npm init，然后npm i @dcloudio/types -D，来补充d.ts。
Projects created by HBuilderX can also use npm, reference: NPM support
Other development tools such as vscode, in the field of vue or uni-app, the development efficiency is not as good as HBuilderX. For details, see: https://ask.dcloud.net.cn/article/35451
You still need to use HBuilderX when publishing your app. Other development tools cannot publish apps, but they can publish H5 and various small programs. If you need to develop an App, you can run it in HBuilderX first, and then modify and save the code in other editors. After the code is modified, it will be automatically synchronized to the mobile phone base.
If you use cli to create a project, the uni-app compiler in the HBuilderX plugin list can not be installed
If you have any questions about the use of cli, please scan the code to join the uni-app WeChat exchange group discussion: