Skip to main content
Version: 3.x

H5

This article will introduce H5 development related content, including compatibility, considerations, etc.

Compatibility​

ES5​

By default, the target of @babel/preset-env is configured as follows

targets = {
  ios: '9',
  android: '5'
}

If you need to be compatible with lower versions of the system, change the configuration of babel-preset-taro in babel.config.js in the project root directory. (The parameters exposed by babel-preset-taro are not documented at the moment, please refer to source for detailed configuration, welcome to contribute documentation ~)

babel-loader​

To improve compilation speed, Taro sets the external attribute to babel-loader. Dependencies in node_modules (except for those named with taro) are not compiled by babel. See Github for the babel-loader configuration.

Therefore the following issues need to be noted.

  • @tarojs/components is not compiled by Babel by default, but ES5 packages were not compiled before 3.2.10, please update to 3.2.10 and above.
  • Dependencies in node_modules are not compiled by default, if you have compatibility needs, please modify the external property of babel-loader manually using WebpackChain.

Android 4.4​

Android 4.4 compatible Please make sure you have done the following.

  • Taro is using v3.2.15+ version.
  • Use the compatibility component library (only React is supported for now).
  • Properly configure babel-preset-taro and install corejs3.
  • If you still have problems with Promise undefined, you can manually introduce a Promise polyfill in index.html.

React compatibility component library​

note

Taro 3.2.4 started to support

Taro3 H5-side component library is based on Web Components and was developed using the Stencil framework.

Stencil Compatibility Status

However, there are still some problems with mobile support for Web Components, the main issues are as follows.

  • Android 4.4 white screen
  • Multi-line text truncation failure
  • Some Android machines (OPPO, VIVO mostly), the style visibility switch fails to cause the page white screen

Therefore, developers with strong compatibility requirements can use the React Compatibility Component Library instead of the default Web Components component library. It is completely based on React and has good compatibility, but currently only a few commonly used components have been adapted, so developers should choose carefully to use it.

Usage​

  1. Installing the Compatibility Component Library
$ yarn add @tarojs/components-react
  1. Set the compilation configuration h5.useHtmlComponents
config/index.js
module.exports = {
  h5: {
    useHtmlComponents: true
  }
}
  1. Start Compile
$ taro build --type h5 --watch

贡献流程​

Due to manpower issues, the Taro team is still focusing on the Web Components component library for iteration. Developers are also welcome to add to the React-compatible component library by converting components developed in Stencil syntax to React syntax (Stencil supports JSX, so it's not a lot of work). See the development process at @tarojs/component-react

React​

Some issues to keep in mind when developing H5 with React.

fast refresh​

React has the fast refresh feature enabled by default in H5 Dev compile mode.

However, when custom environment variable is used, the following error is reported.

or when Webpack devServer is configured to turn off hot updates: hot: false, the following error will be reported.

danger

Uncaught ReferenceError: $RefreshSig$ is not defined

This is all because in dev environments, Taro does two things by default.

  • Use the Babel plugin with fast-refresh
  • Setting devServer.hot in the Webpack configuration to true will add the fast refresh loader.

And the fast refresh Babel plugin and the loader must be enabled or disabled at the same time.

So when you get the above error, or if you don't want to enable fast refresh, you can disable it by configuring both Babel and Webpack.

config/index.js
const config = {
  // ...
  h5: {
    devServer: {
      hot: false
    }
  }
}
babel.config.js
module.exports = {
  presets: [
    ['taro', {
      framework: 'react',
      hot: false
    }]
  ]
}