Automated Upgrade of Taro Mini‑Program from 1.x to 3.x Using AST

The original music‑person mini‑program was launched in August 2019 and was built with Taro 1.3.4 because the framework supported both mini‑program and H5 targets and offered a React‑like syntax.

Since Taro’s major version has moved to 3.x, the 1.x/2.x series is no longer maintained. The old version suffers from several drawbacks: it follows the Nerv implementation that diverges from standard JSX, many new React 18 features are unavailable, some official mini‑program APIs are unsupported, the whole Taro stack has hard‑to‑upgrade dependencies, and its custom build tool is slow and opaque.

Upgrading to Taro 3.x is expected to bring clear benefits: full support for React 18 syntax reduces cognitive load, compilation time and hot‑reload speed improve dramatically, page performance and load speed are enhanced, and the richer ecosystem and active issue handling increase maintainability.

Two upgrade paths are compared. The manual approach requires developers to enumerate all version differences, modify each file individually, and is prone to omissions, merge conflicts, and high labor cost. The automated approach uses an abstract syntax tree (AST) to systematically transform the code base, ensuring comprehensive coverage and allowing the process to be repeated with minimal manual effort.

Key migration areas and their handling strategies include:

npm dependencies: a script reads package.json , compares current and target versions, and adds, updates, or removes entries accordingly.

Library and module changes: Taro‑specific imports are replaced with their React equivalents (e.g., useEffect , useState , etc.), and @tarojs/redux is switched to react-redux . AST visitors replace MemberExpression , ImportDeclaration , and TSQualifiedName nodes.

Project file structure: Component config files are extracted, Component options are removed, and related AST nodes are transformed into separate configuration files.

Styling: The original mini‑program style isolation is removed; all styles are consolidated into app.wxss and className attributes are converted to CSS‑module imports via AST manipulation.

Built‑in APIs: Deprecated APIs such as this.$router , this.$scope , and lifecycle hooks like componentDidShow are replaced with appropriate React patterns.

Build configuration: Adjustments to webpack, Babel, SCSS, and React settings are applied manually because they are one‑off changes.

The AST‑based tool works by parsing source files with @babel/parser , traversing the generated AST, and applying a set of atomic transformation units, each responsible for a specific migration task. The tool also logs processing details and generates an HTML preview page for developers to verify the conversion results.

In conclusion, the automated AST migration offers significant advantages over a purely manual process. The command‑line tool can be contributed back to the Taro community as a generic solution for similar upgrade scenarios. Ongoing work explores using AST analysis to map code changes to business impact, enabling automated impact reports in future releases.