We will develop a simple V2EX forum client in this tutorial and you will learn the basics, concepts and some optimization techniques of Taro in this section. Learning this knowledge does not require prior knowledge of Taro, mini program development or multi-site development. Once you have this knowledge, you should be able to develop multi-applications quickly and efficiently.
This tutorial is for developers who like to learn as they go or have no prior knowledge of mini program development at all, if you prefer to learn step by step, please include the entire contents of documentation in its entirety. When you finish reading the documentation you will see that this tutorial is an asymptotic index of the documentation.
This tutorial will be divided into four chapters.
- [Environment preparation](#Environment preparation): what needs to be installed when we use Taro.
- [Basic tutorial](#Basic tutorial): basic concepts and development guidelines for Taro.
- [Project Progression and Optimization](#Project Progression and Optimization): what should be done to maintain or improve the maintainability and performance of the application as the project gets bigger and slower.
- [Multi-Ended Development](#Multi-Ended Development): How to quickly expand to a multi-ended application when you have already developed one end of the application using Taro.
(If you're browsing on a large screen) The title directory to the right of this tutorial contains subdirectories for all the chapters, so you can view or navigate to the chapter you're interested in.
Our code implementation also uses some ES6 syntax, which you can see or learn about at ES6 Getting Started Tutorial
Currently Taro offers only one development method: installing the Taro command line tool (Taro CLI) for development.
The Taro CLI relies on the Node.js environment, so it must be installed on your machine. There are various ways to install the Node.js environment, if you don't know Node.js at all you can visit the Node.js official website to download an executable to install it. We recommend installing the LTS version of Node.js (currently LTS version is v12).
When your machine already has a Node.js environment, you can install the Taro CLI by entering the command
npm i -g @tarojs/cli in the terminal. Once installed, enter the command
taro in the terminal and if something like this appears, the installation was successful.
When you use VSCode, it is recommended to install the ESLint plugin, and if you use TypeScript, don't forget to configure
eslint.probe parameter if you use TypeScript. If you use Vue, it is recommended to install the Vetur plugin.
If you are willing to spend money and are lazy you can choose WebStorm (or any other Jetbrains IDE that supports web development), which requires basically no configuration.
Whether you use VSCode or WebStrom, you can use Taro for auto-completion and live code inspection (linting) after installing the above plugin.
What tool is used by the terminal emulator on *nix systems (Terminal/iTerm2/Konsole/Hyper/etc...) It doesn't matter, but for running the Taro CLI shell we recommend
On Windows we recommend using the built-in
PowerShell. If available, we recommend installing WSL and running the Taro CLI from a terminal in the Linux distribution. Windows extremes may not have been taken into account, resulting in bugs.
When you encounter a problem during development, you can scan the code to join Taro Community and ask a question. When you're sure there's a bug in Taro, feel free to ask your question to the Taro GitHub Issue.and ask a question, or go to
After installing the Taro CLI you can create a brand new project with the
taro init command, you can fill in the options according to your project needs, a minimal version of a Taro project will include the following files.
We will explain what each file does later, but for now, let's focus on the
src folder, which is the source directory.
Every Taro project has an entry component and an entry configuration where we can set the global state/global lifecycle, a minimized entry component would look like this.
Each entry component (e.g.
app.js) is always accompanied by a global configuration file (e.g.
app.config.js) in which we can set the path, global window, routing, etc. of the page component. A minimal global configuration is as follows
You may notice that the global configuration is the same for both React and Vue. This is in the configuration file, Taro doesn't care about the framework difference, the Taro CLI will execute the globally configured code directly in the Node.js environment at compile time and serialize the
export default exported object to a JSON file. Next we'll talk about [page configuration](# page components) which also executes the same logic.
Therefore, we must ensure that the configuration file is executable in the Node.js environment, and not use some package or code that can only run in the H5 environment or mini program environment, otherwise the compilation will fail.
Page components are the pages that will be rendered by each route. Taro's pages are placed in
src/pages by default, and every Taro project has at least one page component. In our generated project, there is a page component:
src/pages/index/index, and if you are careful, you can see that this path happens to correspond to the
pages of our global configuration in the
pages field. A simple page component would look like this.
Isn't this the familiar React and Vue components! But there are two subtle differences.
onReadylifecycle function. Taro injects most of the mini program specification page lifecycle into the page component at runtime, while the lifecycle of React or Vue is also fully functional.
Viewcomponent. This is a cross-platform component from
@tarojs/components. As opposed to the familiar
spanelements, in Taro we are going to use all such cross-platform components for development.
Like the portal component, each page component (e.g.
index.vue) will also have a page configuration (e.g.
index.config.js), where we can set the page's navigation bar, background color, and other parameters.
If you've made it this far, you have to be congratulated for understanding the most complex concepts in Taro: entry components and page components, and how they interact (via configuration files). The next part, if you are already familiar with React or Vue and web development, is too simple.
Let's start by writing the front page, which has a simple logic: display the latest forum posts.
You may notice that sending requests in a Taro app is done by
Like page configuration and global configuration, Taro's API specification is based on the WeChat mini program and is unified for the whole platform.
You can find it in the API documentation to find all the APIs.
In our home page component, there is also a reference to a
ThreadList component, which we will now implement.
Here you can see that we have split the forum post rendering logic into two components and placed them in the
src/components file, as these components are used many times in other pages.
The strength of the split is entirely up to the developer, and Taro does not specify that components must be placed in the
components folder, nor that pages must be placed in the
Another point worth noting is that we don't use HTML components like
span, but rather cross-platform components like
The cross-platform component library of the Taro documentation contains all component parameters and usage. However, the parameters and component names in the component library documentation are currently specific to React (except for React's click event, which is
For Vue, component names and component parameters are named in a short horizontal line style (kebab-case), for example:
<picker-view indicator-class="myclass" />
src/components/thread component, we pass the
Jump to post details, but this page is still not implemented, now we go to the entry file to configure a new page:
Then in the path
src/pages/thread_detail/thread_detail to implement the post details page, the route can be jumped, and our whole process is running up to.
So far, we have implemented all the logic of this application, except for the "node list" page (we will discuss this page component in the advanced guide), and the rest of the pages can be abstracted quickly with the components or pages we have already explained. According to our plan, this application will have five pages, which are
- Home page, showing the latest posts (completed)
- Node list
- Top posts (can be multiplexed by component)
- node posts (can be multiplexed by component)
- post details (completed)
The first three of these pages can be planned in
tabBar, which is Taro's built-in navigation bar that can be configured in
app.config.js, and the page in the
tabBar position will display a navigation bar after configuration. Our final
app.config.js will look like this.
In our implementation of the post component (
src/components/thread), an event is raised via Taro's built-in
eventCenter to inject the current post's data into a global
GlobalState, and then the current post's data is fetched from the
GlobalState on the post details page - a simple publish/subscribe pattern that is very efficient and clear when dealing with simple logic.
Once our business logic becomes complex, a simple publish-subscribe mechanism tied to a global
state may cause our data flow to become difficult to track. The good thing is that there are good solutions to this problem in both the React and Vue communities. We'll use the two most popular state management tools in the community:
Vuex to solve this problem.
context into our application using the
react-redux in the entry file.
Then in the post component we can set the current post via
In the post details component we get the data of the current post via
store in the entry file.
Then in the post component we can set the current post with
Get the data of the current post via
computed in the post details component.
This tutorial demonstrates minimalist usage of
Vuex, not best practices. Please visit the Vuex documentation for details.
In principle, Taro can support any React- or Vue-compatible state management tool, and using such tools usually requires that the
context be injected into the entry component, and in Taro the entry file cannot render the UI. Just be aware of this.
In the Vue ecosystem we recommend using
Vuex. The React ecosystem has a wide variety of state management tools, and given that many developers using Taro compile their applications into mini programs, we recommend a few state management tools that have performance or size advantages.
mobx-react: Responsive state management tools like Vuex
- unstaged: Minimalist state management tool based on React Hooks, with a compressed size of 200 bytes
- Recoil: Facebook's React Hooks-based state management tool
In Taro, we can freely use CSS pre-processors and post-processors, and it's as simple as adding the relevant plug-ins to the build configuration.
In the post details component (
ThreadDetail), we use the built-in component
RichText to render HTML, but this component is not compatible and does not work properly on all ends, and some specific HTML elements cannot be rendered.
Fortunately, Taro has built-in HTML rendering, and the usage is not much different from React/Vue for web development.
Taro's built-in HTML rendering features can be used not only in a web development manner, but also support advanced features such as custom styles, custom rendering, and custom events. You can visit the HTML rendering documentation to learn more.
In the post list component (
ThreadList), we render the data directly from the remote. This is not a problem, but if we have very large data, or if the list renders an unusually complex DOM structure, this can create performance issues.
To solve this problem, Taro has a built-in
VirtualList feature that renders only the view of the current visible viewport, rather than rendering all the list data in full.
In the documentation virtual-list you can find some advanced uses of virtual lists, such as: infinite scrolling, scroll offsets, scroll events, etc.
Now let's implement the last page: the node list page. This page essentially renders a huge list that exists locally:
This time our whole application is finished. However, if you put this app in a real mini program, especially in some real machines with low performance, it may take longer to switch to this page and there will be a white screen time.
This is due to Taro's rendering mechanism: during page initialization, native mini program can fetch data directly from local rendering, but Taro renders the initial data into a DOM tree via React/Vue, then serializes the DOM tree and gives it to the mini program to render. This means that Taro spends one more time calling the
setData function on page initialization than native mini programs do - and most mini program performance problems are caused by oversized
To solve this problem, Taro has introduced a technology called Prerender, which, like server-side rendering, converts the pages to be rendered directly into
wxml strings in the Taro CLI, resulting in the same or even faster speeds than native mini program.
Using prerender is also very simple, we just need to do a simple configuration:
The configuration of prerender supports conditional rendering pages, conditional rendering logic, custom rendering functions, etc. For details, visit the pre-rendering documentation.
By default using production mode packaging, Taro will optimize the packaging volume for you. However, it is worth noting that Taro's default packaging configuration is designed to work for most projects and requirements, and is not optimal for any project. So you can build on top of the Taro configuration and optimize it for your own project.
In Taro applications, all Java(Type)Script is configured via
babel.config.js, specifically using the
babel-prest-taro Babel plugin is compiled.
By default Taro is compatible with all syntaxes supported by
@babel/preset-env and is compatible with
iOS 9 and
Android 5, but if you don't need that high compatibility or don't need If you don't need that much compatibility or don't need some ES2015+ syntax support, you can configure
babel.config.js yourself to reduce the package size.
For example, we can upgrade the compatibility to
You can visit the Babel documentation for more information on customizing your configuration.
Taro uses Webpack as its internal packaging system, and sometimes Webpack doesn't give us the
tree-shaking effect when our business code uses the
require syntax or the
import default syntax. . In such cases we use
webpack-bundle-analyzer to analyze our dependency packaging volume, and this plugin opens a visual graphical page in our browser telling us reference the volume of each package.
First install the
And then addd the following configuration to the mini.webpackChain：
After running the compile command you can see the file dependencies and volumes.
You can visit the webpack-bundle-analyzer documentation for detailed usage.
In some cases, we want our pages to be loaded on demand only when they are used. This is called subpackaging in the Taro application, and it is very simple to use, just by configuring the entry file
Suppose we need to subpackage all the node pages that we have just implemented for pre-rendering.
In specific cases where Taro's own compilation system does not meet our compilation needs, Taro offers two options for extending the compilation.
In [package volume analysis](#package volume analysis) we added a Webpack plugin to mini.webpackChain and added a Webpack plugin to mini.webpackChain to achieve the effect of packing volume/dependency analysis.
In fact with the
mini.webpackChain configuration we can use almost any plugin and
loader from the Webpack ecosystem, for example if we want to use
CoffeeScript for development.
CSS Modules that we mentioned before can be extended with support in the form of Webpack. For more information, visit the webpack-chain documentation for details on how to use it.
At [CSS Tools](#CSS Tools) we have used a plugin called
@tarojs/plugin-sass to implement support for
Sass. Instead of using Webpack extensions to compile, Taro's plugin functionality eliminates the need to configure Webpack on each end and just uses the plugin.
In addition, Taro's plugin functionality extends the Taro CLI compilation commands, the compilation process, and the compilation platform, and you can visit the plug-in functionality documentation for more information on custom configuration.
to learn more
In addition to the above two methods, Taro also offers a number of compile-related options, which you can learn more about by visiting the compile configuration details documentation to learn more.
In some cases, the performance or business logic of different platforms is qualitatively different. In such cases, there is no way for us to do "one set of code for all".
For example, if we are implementing a V2EX forum application, the current API has no way to be called across domains in the browser, so we need to use another copy of the API on the H5 side, which we can solve by using the built-in environment variables.
Taro also provides unified interface for multi-terminal files，Finding dependencies by different nomenclature, in such cases we can keep.
statement as is, modify our file structure by adding the name of the platform between the file name and the suffix name:
In addition to the "built-in environment variables" and "unified interface for multiple files", Taro also offers other cross-platform development solutions, which you can learn more about by visiting the documentation cross-platform development to learn more.
By default, Taro puts all the packaged files on each side in the
dist directory. If you want to synchronize debugging on multiple ends, the files compiled first will be overwritten by the files compiled later.
However, we can synchronize debugging by modifying the
outputRoot of the compilation configuration.
Under this configuration, the compiled directory of Wechat mini programs will be
dist/weapp and the compiled directory of H5 will be
In some cases we need to reuse the existing ecology of the mini program, and the components/libraries of the mini program are usually written for the specific mini program and can't be used directly on Taro, requiring some additional operations.
For example, in our forum application, the post details may be returned in MarkDown format on the server side, so we need
towxml to render our posts.
First we need to reference
towxml in the configuration file of the post details page:
Then using the
towxml component, it's important to remember that whether it's React or Vue, the native mini program component declaration needs to be lowercase
Finally, just follow the towxml document to call it.
Once the native mini program component is used, the Taro app loses its cross-over capabilities.
Taro also supports the use of mini program plugins, for details visit the documentation Using native third-party components and plugins for mini programs.