Why Taro 2.0 Rewrites the CLI with Webpack: Migration Guide and New Features

Background

Taro 1.x has been in use since September of the previous year, growing rapidly and becoming a mature multi‑platform development framework. However, its core architecture remained largely unchanged, leading to maintenance difficulties and limited extensibility for teams seeking deeper innovation.

Why Replace the Custom CLI Build System

Maintenance is hard: adding features such as Markdown parsing requires direct changes to the CLI.

Collaboration is difficult: the complex, branching‑heavy codebase discourages external contributors.

Low extensibility: the original self‑built system was not designed for future extensions.

Adopting Webpack in Taro 2.0

The new CLI becomes lightweight, delegating most compilation work to Webpack. Platform‑specific runners handle code transformation, while AST manipulation is moved into Webpack plugins and loaders.

Migration Steps

Adjust Compilation Configuration

The new system is fully compatible with 1.x projects, but some configuration fields need updating. Below is a typical config object for a Taro project using Webpack.

const config = {
  projectName: 'taro-framework',
  date: '2019-11-2',
  designWidth: 750,
  deviceRatio: {640: 2.34/2, 750: 1, 828: 1.81/2},
  sourceRoot: 'src',
  outputRoot: 'dist',
  // Babel, mini, h5 configurations omitted for brevity
};

module.exports = function (merge) {
  if (process.env.NODE_ENV === 'development') {
    return merge({}, config, require('./dev'))
  }
  return merge({}, config, require('./prod'))
}

Refer to the official compilation configuration documentation for full details.

Enable Async Functions

Taro 2.0 supports async functions via Babel plugins, eliminating the need for @tarojs/async‑await. Install the runtime packages:

$ yarn add babel-plugin-transform-runtime --dev
$ yarn add babel-runtime

Then add babel-plugin-transform-runtime to the Babel plugins list.

babel: {
  sourceMap: true,
  presets: [['env', {modules: false}]],
  plugins: [
    'transform-decorators-legacy',
    'transform-class-properties',
    'transform-object-rest-spread',
    ['transform-runtime', {helpers: false, polyfill: false, regenerator: true, moduleName: 'babel-runtime'}]
  ]
}

Adding Loaders for Mini‑Program Builds

To import Markdown files in a mini‑program, configure a custom loader via mini.webpackChain:

const config = {
  mini: {
    webpackChain(chain) {
      chain.merge({
        module: {
          rule: {
            myloader: {
              test: /\.md$/,
              use: [{loader: 'raw-loader', options: {}}]
            }
          }
        }
      })
    }
  }
}

Analyzing Bundle Size

Integrate webpack-bundle-analyzer to visualize the size of each output file:

const config = {
  mini: {
    webpackChain(chain, webpack) {
      chain.plugin('analyzer')
        .use(require('webpack-bundle-analyzer').BundleAnalyzerPlugin, [])
    }
  }
}

React Native Dependency Upgrade

Taro RN now uses React 16.8.0 (first version with Hooks) and React Native 0.59.9 to satisfy Google Play’s 64‑bit requirement. The upgrade is seamless for existing code; projects using taro-native-shell can switch to the 0.59.9 branch.

New Features in Taro 2.0

Compilation Hooks

The CLI’s main compilation flow is now built on Tapable, exposing beforeBuild and afterBuild hooks. Users can create plugins that tap into these hooks:

class BuildPlugin {
  apply(builder) {
    builder.hooks.beforeBuild.tap('BuildPlugin', config => {
      console.log(config)
    })
    builder.hooks.afterBuild.tap('BuildPlugin', stats => {
      console.log(stats)
    })
  }
}

const config = {
  // ...
  plugins: [new BuildPlugin()]
}

Other Enhancements

Unified compilation across platforms thanks to Webpack.

Improved stability and reduced obscure errors.

Greater extensibility via custom loaders and plugins.

Future Outlook

Taro 2.0 is only the beginning. The team previewed “Taro Next” at the GMTC conference, promising a radically different architecture for the next decade of front‑end development.