How to Build a Multi‑Platform Page with Taro 3 for H5 and Mini‑Programs

Project Motivation

The goal was to create a page that runs unchanged on both mini‑program platforms and H5, while preserving each platform’s existing logic. Taro 3 was chosen for its stability, React/Vue‑like development experience, high configurability, and active plugin ecosystem.

Key Challenges

Maintain code compatibility for H5 and multiple mini‑programs without duplicating logic.

Integrate a unified page into native mini‑program projects that already have separate codebases.

Build a reusable framework to accelerate future multi‑platform development.

Taro Architecture Overview

Taro 1/2 (re‑compilation) : Source code is compiled into platform‑specific bundles, then a lightweight runtime smooths differences using Taro’s component library and APIs.

Taro 3 (re‑runtime) : Executes code in a browser‑like environment, abstracting DOM/BOM APIs ( createElement, appendChild, removeChild) so any front‑end framework (React, Vue, jQuery) can run unchanged in mini‑programs. Unified standards for lifecycle, component library, API, and routing are defined, while each platform provides an adapter.

Open‑Plugin Architecture (v3.1) : Core supports six official platforms (WeChat, Alipay, Baidu, Toutiao, QQ, JD). Additional platforms are added via plugins, avoiding core modifications.

Project Setup

Install CLI yarn global add @tarojs/cli Initialize Project Run taro init (wizard omitted).

Directory Comparison Native mini‑program and Taro structures are similar, simplifying migration.

Configure Scripts Typical package.json entries:

"build:weapp": "taro build --type weapp",
"build:swan": "taro build --type swan",
"build:alipay": "taro build --type alipay",
"build:tt": "taro build --type tt",
"build:h5": "taro build --type h5",
"build:rn": "taro build --type rn",
"build:qq": "taro build --type qq",
"build:jd": "taro build --type jd",
"build:quickapp": "taro build --type quickapp"

dev mode (add --watch) watches file changes.

build mode (omit --watch) creates compressed bundles; set NODE_ENV=production for minification.

Extend to Other Mini‑Programs (e.g., Enterprise WeChat)

yarn add @tarojs/plugin-platform-weapp-qy

// config/index.js
module.exports = {
  plugins: ["@tarojs/plugin-platform-weapp-qy"]
}

Run npm run build:qywx.

Development Details

Routing

Access route parameters via getCurrentInstance().router:

import Taro, { getCurrentInstance } from "@tarojs/taro";
import React, { Component } from "react";
export default class Index extends Component {
  componentDidMount() {
    console.log(getCurrentInstance().router.params);
  }
}

Versioned H5 Builds

In config/prod.js, set publicPath and output.path using package.json version to generate versioned directories.

Network Requests

Use Taro’s request API with async/await:

const options = {
  method: requestType,
  url,
  data: param,
  credentials: "include",
  timeout: 1000 * 30,
  header: h,
};
const res = await Taro.request(options);

In mini‑program environments, request URLs must use HTTPS.

Environment Detection

const Utils = {
  isH5() { return process.env.TARO_ENV === "h5"; },
  isWeapp() { return process.env.TARO_ENV === "weapp"; }
};
export default Utils;

Blended Build (Mixed Development)

Run taro build --type weapp --blended to generate a taroApp object in app.js for native mini‑program integration. This works for main‑package pages; sub‑packages need additional handling.

Sub‑Package Handling

Install @tarojs/plugin-indie and add it to plugins in config/index.js.

The plugin adjusts module source‑map paths so sub‑package JS chunks load first.

Optionally create a custom plugin ( plugin/index.js) to copy the compiled dist folder into the native mini‑program’s pages/taroMini directory after a blended build:

export default (ctx, options) => {
  ctx.onBuildFinish(() => {
    if (!ctx.runOpts.blended) return;
    const rootPath = path.resolve(__dirname, "../..");
    const miniappPath = path.join(rootPath, "jdc_wx_ecard");
    const outputPath = path.resolve(__dirname, "../dist");
    const destPath = path.join(miniappPath, "./pages/taroMini");
    if (fs.existsSync(destPath)) fs.removeSync(destPath);
    fs.copySync(outputPath, destPath);
    console.log("Copy finished!");
  });
};

Native Mini‑Program Integration

Define sub‑package paths in app.json:

{
  "subPackages": [{
    "root": "pages/taroMini/pages/riskControlAnswer",
    "pages": ["index"]
  }]
}

Navigate back to native pages with Taro.redirectTo({ url }), encoding return URLs as needed.

Summary

By leveraging Taro 3’s open‑plugin architecture, blended build mode, and custom plugins, a single codebase was built that runs on H5 and multiple mini‑program platforms. Automated scripts copy compiled assets into the native mini‑program project, enabling seamless mixed development.

References

Taro Official Documentation : https://nervjs.github.io/taro/docs/

JD Aotu Lab – Juejin : https://juejin.cn/team/6930527975943176199

JD Shopping Mini‑Program | Taro3 Sub‑Package Practice: https://mp.weixin.qq.com/s?__biz=MzIxMzExMjYwOQ==∣=2651896934&idx=1&sn=619aea0f571e3694cacb590f5e3600f0&scene=21#wechat_redirect

GMTC – Cross‑Framework Mini‑Program Development Talk: https://mp.weixin.qq.com/s?__biz=MzU3NDkzMTI3MA==∣=2247483770&idx=1&sn=ba2cdea5256e1c4e7bb513aa4c837834&scene=21#wechat_redirect