How to Shrink Taro Mini‑Program Bundles Below 2 MB with Smart Splitting

Introduction

When developing relatively large Taro mini‑programs, the main package often exceeds the 2 MB limit imposed by WeChat, preventing release. This article introduces four optimization techniques to keep the main bundle under the limit.

Optimization Methods

Page Sub‑Package

The main package size limit is 2 MB. Only the default launch page and TabBar pages should stay in the main package; other pages are moved to sub‑packages.

Common Module Sub‑Package

By default, modules referenced by multiple pages are bundled into the main package. Using the MiniSplitChunksPlugin, common modules such as common.js, common.wxss, and vendors.js can be identified and moved to sub‑packages, reducing main‑package size.

common.js

contains shared components, utilities, hooks, etc. common.wxss contains shared component styles and global styles. vendors.js contains third‑party dependencies.

Solution

Identify which pages use which common modules; if a module is used only by sub‑packages, move it to the corresponding sub‑package.

Technical Implementation

Documentation: https://docs.taro.zone/docs/config-detail#minioptimizemainpackage

Enable mini.optimizeMainPackage in the Taro configuration. The plugin analyses module‑chunk relationships, extracts modules not referenced by the main chunk, and adds them to sub‑packages.

const PLUGIN_NAME = 'MiniSplitChunkPlugin';
export default class MiniSplitChunksPlugin extends SplitChunksPlugin {
  // sub‑package configuration
  subPackages: SubPackage[];
  subRoots: string[];
  subRootRegExps: RegExp[];
  // ... (omitted)
  apply(compiler: any) {
    // collect sub‑package entry data
    // ... (omitted)
  }
}

Further steps involve collecting sub‑package entry chunks, building subCommonDeps, generating new cacheGroups for SplitChunksPlugin, and finally emitting assets that reference the relocated modules.

export default class MiniSplitChunksPlugin extends SplitChunksPlugin {
  subCommonDeps: Map<string, DepInfo>;
  chunkSubCommons: Map<string, Set<string>>;
  subPackagesVendors: Map<string, webpack.compilation.Chunk>;
  // ... (omitted)
  apply(compiler: any) {
    // ... (omitted)
    compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
      compilation.hooks.optimizeChunks.tap(PLUGIN_NAME, (chunks) => {
        // generate new cacheGroups based on subCommonDeps
      });
    });
  }
}

Import Path Refactoring

Using a Babel plugin (e.g., babel-plugin-import) to rewrite imports from @/components to explicit component paths ( @/components/component‑path) prevents the whole component directory from being bundled into the main package.

module.exports = {
  plugins: [
    ['import', {
      libraryName: '@/components',
      libraryDirectory: '',
      transformToDefaultImport: false,
    }],
  ],
};

Image Asset Optimization

Large image assets (e.g., 22 MB in a sample project) can be uploaded to a CDN and referenced by URL, removing them from the bundle. A Taro plugin can upload images during the build, cache the URLs, and a Babel or PostCSS plugin can replace local imports with the CDN URLs.

module.exports = (ctx, pluginOpts) => {
  ctx.onBuildStart(async () => {
    const { fileDir, upload } = pluginOpts;
    const filePathList = travelFiles(path.join(ctx.paths.sourcePath, fileDir));
    const { results: fileUrlList } = await PromisePool.withConcurrency(2)
      .for(filePathList)
      .process(async (filePath) => {
        const fileUrl = await upload(filePath, generateFileUniqueKey(filePath));
        return { filePath, fileUrl };
      });
    // write cache file...
  });
};

Conclusion

The article covered page sub‑packaging, common module sub‑packaging, import path rewriting, and image asset offloading to keep a Taro mini‑program under the 2 MB limit, and suggests further strategies such as enum compilation optimization, asynchronous sub‑packages, and atomic style components.