The Taro version upgrade Authority guide

Taro is an open cross-terminal and cross-frame solution launched by JINGdong Concave-Lab, dedicated to solving cross-terminal isomorphism problems of small programs, H5 and React Native, supporting simultaneous development using React and Vue. The purpose of this article is to help Taro developers clarify the relationship between the current versions of Taro, and to answer questions about Taro 3, support for Taro RN, and THE Taro UI.

Since Taro launched version 3.0 in July this year, announcing support for both React and Vue to develop cross-app applications, attention has been raised further. Many developers have begun to upgrade their projects to 3.0 to experience the new features. The Taro community has also started to welcome some new friends. Many Vue developers in the industry have started to turn their attention to Taro when making technology selection.

However, due to the large differences between the major versions of Taro, and the fact that many of the community’s tutorial articles and sample projects about Taro are still in the Taro 1/2 era, many developers have encountered strange problems when trying to use Taro 3.0. Therefore, the Taro team wants to help you understand the relationship between versions of Taro, and help you better complete version migration, so as to avoid some strange problems that are difficult to solve.

Distinguish the Taro version of the fiery eye

There are three major versions of Taro, but if we really divide the ages according to the architectures, Taro 1/2 belongs to the first generation architecture, while Taro 3 belongs to the second generation architecture. The two architectures are so different that they can even be completely considered as two frameworks. Of course, this is only for the kernel of the framework. For developers, the Taro team has made efforts to ensure compatibility between large versions and ease the difficulty of version migration.

Taro 1/2

Taro 1/2 is a compiled architecture. It uses the React code syntactically compiled and converted to generate code that can be run on each end. Lightweight runtime adaptation is implemented and differences are balanced based on standard component libraries and apis to achieve multi-end adaptation.

Taro 1 and Taro 2 are based on this architecture. The main difference between them is that Taro 1 is a self-built build system on the small program side, while Taro 2 uses Webpack to compile all the applications, which can reduce the complexity of Taro’s own compilation system. While allowing developers to customize the build process and results using Webpack’s ecology, Taro 2 can be considered a transitional release between Taro 1 and 3.

Taro 3

Taro 3 can be roughly understood as an interpretable architecture (compared with Taro 1/2). It mainly simulates DOM and BOM APIS on the small program side to make the front-end framework run directly in the small program environment, so as to achieve the unification of small program and H5. As for differences in life cycle, component library, API, routing, etc., we can still smooth them out by defining unified standards and each end is responsible for its own implementation. Taro 3 supports frameworks like React, Vue, and even jQuery. In the near future, we’ll be able to extend support to other frameworks, such as Angular, without having to define them. The overall architecture of Taro 3 is as follows.

Version selection trade-offs

As can be seen from the above, Taro’s two generations of architecture are very different, which leads to their different characteristics. The feature differences between Taro 1/2 and Taro 3 are mainly in development experience and performance.

From the perspective of development experience, Taro 3 is obviously superior to Taro 1/2. Benefiting from the principle of Taro 3 architecture, we can use complete React and Vue syntax features in Taro 3 to develop, thus making multi-terminal development experience infinitely close to Web development. This is very friendly for developers who are deep into the Web and new to applets. Those of you who are familiar with Taro know that there are many limitations to Taro 1/2’s development, especially when it comes to JSX writing. We will always need some means to get around these limitations, which leads to a slight deficiency in the development experience.

In terms of performance, Taro 1/2 is better than Taro 3 in some cases. If your application is very complex, has a lot of page nodes, and has a lot of large-scale update operations, Taro 1/2 is a good choice for performance requirements. We recommend students to visit Taro 1 and 2 first. Of course, according to our tests, the performance difference between Taro 1/2 and Taro 3 is not significant for most applications, and we will provide benchmarks to verify this later. Moreover, for scenarios where Taro 3 itself has a performance disadvantage, The Taro official team has provided corresponding solutions to the problem. For example, to speed up the first render, we can use pre-render; For a list scenario with an infinite scrolling load, we provide a virtual list component.

For developers, development experience and performance are often a trade-off to find a balance. One cannot be without the other. Therefore, at this stage, we recommend Taro 3 to develop multi-application. Taro 3 is currently the focus of the Team’s research and development, and new features will be first introduced in Taro 3. Therefore, in the future, Taro 3 will be more imaginative and have more fun to introduce.

Smooth Upgrade Incomplete guide

Taro 2 and Taro 3 have migration guidelines that can help you avoid most of these problems.

Migration guide for upgrading Taro 1 to Taro 2.

Taro 1/2 Migration guide for upgrading to Taro 3.

Migration guide, of course, all cases cannot cover all problem, we are always in the Taro communication group of daily communication can be observed that some of the migration problem, so in this case, we will comb again migration guide, at the same time, some of the common problem, and then do some supplement, solutions to developers upgrade confusion.

Upgrade Taro 1 to Taro 2

Taro 1 litre Taro 2 does not need to do a lot of work, according to the migration guide, the main thing is to add a @tarojs/mini-runner dependency, as well as the compilation configuration adjustment, and here is a summary of the compilation configuration adjustment.

pluginsConfiguration adjustment, before adjustment is an object, after adjustment is an array, used for configurationTaro plug-in, it is very noteworthy that this configuration is available withbabelIn the configurationpluginsThe latter is used to configure the Babel plug-in, which is a very common configuration error
babel,csso,uglifyEtc configuration from the oldpluginsMoved out of configuration, adjusted to andsourceRoot 和 outputRootConfiguration items at the same level
weappThe configuration item is renamed tomini
postcssThe configuration item dropsmoduleThis level of configuration, the originalmoduleThe following configuration items are directly placed inpostcss 下

Use of async functions

Also, starting with Taro 2, async functions no longer require @tarojs/async-await dependencies. Babel-plugin-transform-runtime is supported by installing the Babel plugin babel-plugin-transform-Runtime in conjunction with babel-Runtime. See the asynchronous programming guide in the documentation for details.

Manually installed configurations are no longer required in Taro 3, and Taro’s official Babel preset, babel-preset- Taro, is already built in.

Upgrade Taro 1/2 to Taro 3

Upgrading from Taro 1/2 to Taro 3 is a lot more difficult, but the migration guide is already quite detailed, so we summarize what needs to be adjusted here.

File to adjust

File adjustment is mainly as follows:

Babel configurationIn the project directorybabel.config.jsConfig file to configure Babel. To do this, remove the compiler configuration (config/index.js)babelThe configuration,See note
Project/page configurationTo add a configuration file with the same name for the project/page*.config.js(or*.config.ts),*Represents the file name of the page/project file,configThe files must be in the same folder as the page/project files,See note

Compile configuration adjustment

Taro 3 is configured with unique configurations (such as React, Nerv, vue, vue3). For details, see the description

Project dependency adjustment

In Taro 3, many old dependencies are no longer needed, such as @tarojs/ taro-appellate, @tarojs/ taro-Alipay, etc., but some new dependencies are also added, such as @tarojs/ Runtime. You can see exactly what dependencies Taro 3 will need by creating an Taro sample project. Here we list the NPM package names that Taro 3 still needs to use and their specific functions.

NPM package	describe
`babel-preset-taro`	Babel Preset for use in the Taro project
`@tarojs/taro`	Taro core API exposed to application developers
`@tarojs/shared`	Taro internal use of utils
`@tarojs/api`	Public API exposed to all ends of @tarojs/taro
`@tarojs/taro-h5`	H5-side API exposed to @tarojs/taro
`@tarojs/router`	Taro H5 routing
`@tarojs/react`	A React renderer for small programs based on the React-Reconciler
`@tarojs/cli`	Taro Development Tools
`@tarojs/extend`	Taro extension, including jQuery API, etc
`@tarojs/helper`	Internally use the helper method set for CLI and Runner
`@tarojs/service`	Taro plug-in kernel
`@tarojs/taro-loader`	Webpack loader exposed to @tarojs/mini-runner and @tarojs/webpack-runner
`@tarojs/runner-utils`	Public utility functions exposed to @tarojs/mini-runner and @tarojs/webpack-runner
`@tarojs/webpack-runner`	Taro H5-end Webpack compiler
`@tarojs/mini-runner`	Taro applet side Webpack compiler
`@tarojs/components`	Taro Standard Component Library, version H5
`@tarojs/taroize`	Taro small program reverse compiler
`@tarojs/with-weapp`	Run time adapter for reverse transformation
`eslint-config-taro`	Taro ESLint rules
`eslint-plugin-taro`	Taro ESLint plug-in

Code adjustment

The main code adjustments are as follows:

API introducedThe React/Nerv/Vue front-end framework has its own API imported directly from the framework, which is consistent with the Web. Only the relevant API provided by Taro is still imported from the framework@tarojs/taroIntroduction,See note
App Code adjustmentFor React/Nerv projects, the render function of the project entry App is fixed to returnthis.props.childrenAs shown in the following

import { Component } from 'react'
import './app.scss'

class App extends Component {
  render() {
    return this.props.children
  }
}
export default App
Copy the code

Routing functions, the use ofgetCurrentInstance().routeralternativethis.$router.getCurrentInstanceAs a new API from@tarojs/taroIntroduction,See note
Life cycle, mainly after using React, the life cycle adjustment, see the description
Use the third-party React library. For redux, Mobx and other React libraries, you can directly use them as Web development. See instructions
Ref & DOM, see instructions
** Scope ∗ is no longer needed, ‘this.scope** is passed to some apis when taro1/2 is called, and’ this.scope∗ ** is passed to some apis when taro1/2 is called. Calling some apis on taro1/2 requires passing in ‘this.scope’, which corresponds to the component’s applet native object, whereas Taro 3 does not, see the instructions
Style adjustmentComponents are directly affected by global styles and do not need to be setaddGlobalClasses.See note

Of course, the migration guide is not limited to version migration. As there are many breaking changes to Taro 3 as opposed to Taro 1/2, it is recommended that developers using Taro 3 read the migration guide before developing.

I have to talk about the proper use of Taro 3 posture

As mentioned above, many developers started learning about Taro from Taro 3. However, many of the Taro related courses and projects in the market are originally designed by Taro 1/2. This can cause considerable confusion for many developers. We want to list some common problems to help developers avoid unnecessary mistakes.

Taro multi-version coexistence problem

Many developers have previously developed projects using older versions of Taro and have installed Taro globally, but what should they do to experience Taro 3 at the same time?

We offer two ideas:

If you need to create an Taro 3 project, you can use NVM to manage node versions and install different versions of the Taro CLI by installing different versions of Nodes
If some existing projects need to be upgraded to Taro 3, you can install the corresponding version of the Taro CLI locallyyarnornpmTo execute the command, you will directly use the Taro CLI, which is installed locallyyarn add @tarojs/cli

Align the Taro CLI version with the Taro related dependencies in the project

Always ensure that the Taro CLI version is consistent with the Taro related dependencies in the project.

Inconsistency between the CLI and project dependencies is a source of many problems. For example, if the Taro CLI version is 3.0.8, the Taro dependency version must also be 3.0.8. The name of the Taro package can be obtained from this list. The specific dependency version can be obtained using the Taro Info command or through package.json.

If inconsistency is found, you can use the Taro update commands Taro update self and Taro update project to upgrade CLI and project dependencies to the specified version respectively. Alternatively, you can manually install the corresponding CLI version, change the package.json dependency version number, and then reinstall the dependency to solve the problem.

Use the routing

The use of routing in Taro 3 is mentioned in the previous section on version migration, and you can learn more about this in the official documentation.

It is important to note that both project input parameters and page input parameters are obtained using getCurrentInstance().router, as shown below.

import { getCurrentInstance } from '@tarojs/taro'
import React, { Component } from 'react'

export default class C extends Component {
  componentDidMount () {
    console.log(getCurrentInstance().router.params)
  }
}
Copy the code

How do I obtain page node information

Due to the design mechanism of Taro 3, it is necessary to call the Taro API during the new onReady lifecycle to correctly retrieve page node information, as is the case for both applets and H5.

At the same time, when the page nodes are nested too deeply in the wechat applet, Taro will switch to the custom components when the page nodes are nested beyond a certain level (the default level is 16, which can be controlled by compiling and configuring baseLevel), and then start a new loop. In this case, to obtain the page node information, Taro will switch to the custom components. The need to use descendant selectors across custom components for selection can be found in the related issue (Taro).

Taro UI will no longer support Taro 3

Taro UI will still be available in Taro 3, and you will need to install the alpha version of Taro UI.

$ yarn add taro-ui@next
Copy the code

Taro UI, as the official UI library of Taro, is still being maintained by the community, and we welcome more community developers to participate in the iteration of Taro UI.

Taro UI has no Vue version

Currently, Taro does not officially launch the Taro UI library in Vue version, but there is a Vue version of the solution in the community. If you use Vue to develop, you can try taro-UI-Vue.

Why are Taro 3 packaged with apps so bulky

Many friends will find that the package size of Taro 3 projects is much larger than the package size of Taro 1/2 during the preview. They will be nervous about whether using Taro 3 will cause their main package to exceed the limit.

Taro 3 uses the React and Vue libraries for debugging purposes, and generates sourceMap at the same time, resulting in a much larger package. However, when packaging production packages (excluding — Watch), the final package will be small and will not have much impact on online. Meanwhile, the Taro team is trying to optimize the size of production packages to further optimize Taro’s performance.

If you want to reduce the package size while previewing, you can set NODE_ENV to production to enable compression, such as compiling wechat applets

# Mac
$ NODE_ENV=production taro build --type weapp --watch

# Windows
$ set NODE_ENV=production && taro build --type weapp --watch
Copy the code

Use applet native pages and components in Taro 3

You can still introduce native pages and components in Taro 3 in much the same way as you do in Taro 1/2, but in some cases there are some subtle differences. For example, you can use slot tags directly in Taro 1/2. In Taro 3, Slot components need to be imported from @tarojs/ Components and then used.

import Taro from '@tarojs/taro'
import React, { Component } from 'react'
import { View, Text, Slot } from '@tarojs/components'

export default class Index extends Component {
  state = {
    show: false.date: ' '
  }
  render () {
    const { show, date } = this.state
    return (
      <View className='index'>
        <van-button type='primary' onClick={this.showCalendar}>According to the calendar</van-button>
        <van-calendar
          show={show}
          showConfirm
          type='range'
          onClose={this.closeCalendar}
          onConfirm={this.onConfirm}
          >
          <Slot name='title'>
            <View>Hello world</View>
          </Slot>
        </van-calendar>
      </View>)}}Copy the code

For details, see tarO3-ant -sample.

What are the official Taro example projects

The Taro 3 community sample project is still in progress. We provide sample component library projects for Reference, including React and Vue. Install the latest version of the Taro CLI, and select the community quality template source to create your project.

Taro also provides a TodoMVC project for reference. The React and Vue samples are available on the React and Vue branches respectively.

Taro which materials in the materials market can be used in Taro 3

Currently, the Taro Materials market has not done a good job of classifying the versions of the materials. We will start this process as soon as possible to label each material with a version label. Currently, the only way to identify which materials can be used in Taro 3 is through their own Taro dependencies.

Let’s talk more about Taro’s recent moves

The Taro community and the official team are currently focusing on the following tasks

Implement custom extensions that support platforms and frameworks

Careful friends should have found that in the Taro 3 era, Taro’s Slogan has changed from “multi-terminal unified development solution” to “Open cross-terminal cross-frame solution”, so what are the differences between the two?

It can be seen that “open cross-end cross-framework solution” contains the features of multi-end unified development, supports cross-framework development, and more importantly, can be an open solution. We hope that developers can develop a plug-in based on the APIS provided by Taro so that they can extend support for more platforms and front-end frameworks. For example, some new platforms will launch small programs in the future, or some people want to use Angular and other front-end frameworks in Their Taro applications. Taro will be able to expand by itself through the open mechanism of Taro, without waiting for official support. Taro will only serve as a platform for cross-fitting, and all possibilities can be freely explored by the community themselves.

Realize small program and Web isomorphism

Under the current Taro design, development using Taro must use components from the Standard Taro component library, rather than directly using the familiar HTML tags. We are working to break down this barrier and seek to support solutions that allow developers to develop applets directly using HTML tags.

In this way, Taro’s development experience will be closer to the Web. At the same time, some Web ecosystem resources can be run directly in the applet, greatly reducing the cost of migrating from the Web to the applet.

Talk about absent Taro 3 RN support

Many of our friends will ask after upgrading to Taro 3: Is RN no longer supported?

Taro 3 does not support RN adaptation, which makes many friends who use Taro to develop RN apps unprepared.

In fact, Taro has not abandoned THE RN. Currently, the adaptation work of Taro 3 RN has been taken over by the “58.cn” development team. Currently, this work is in full swing, and we believe that we will see the return of RN support in Taro 3 in the near future. This collaboration also means that Taro’s core team is growing into a cross-company team that will surely have more inspirations and bring more features to the community in the future.

To summarize

Based on the feedback from the industry and Taro’s own plans, Taro 3 is a version worth trying and waiting for. Many developers have already started to use Taro 3 to develop applications. In the future, we will continue to improve the functions and documentation to bring you a better development experience. Upgrading to Taro 3 May be a bit of a struggle, but please feel free to let us know if you have any questions via our Exchange Groups and GitHub Issues.

We sincerely invite you to communicate with the official Taro team about your usage. Your feedback will drive us forward. Please click here to complete the survey and submit the questionnaire to receive an Taro team bonus. Thank you all the way, Taro have you more wonderful!