Reduce WeChat Mini Program Main Package by 25% with Split‑Package Async

Background

Huolala's WeChat mini‑program has grown to a main package close to 2 MB; adding new features may exceed the upload limit.

This article applies to mini‑programs built with third‑party frameworks such as Uniapp or Taro. Native WeChat syntax can follow the same ideas and the official documentation. The focus is on optimizing the main package size; sub‑packages are unlikely to exceed 2 MB.

Theory

WeChat's official performance guide suggests four directions for code‑size optimization:

Use split packages wisely – non‑main resources go to sub‑packages; enable pre‑download for important sub‑packages.

Avoid unnecessary global custom components and plugins – move single‑page components to sub‑packages; use “split‑package async” for cross‑package usage.

Control resource files in the package – serve images and fonts via CDN.

Clean unused code and resources – delete dead code.

Analysis

Dependency analysis of version 4318 shows most pages and components have been split; remaining items are hard to split.

Key findings:

Image resources can be moved to CDN, saving about 178 KB. vendor.js is large, containing global libraries.

Need to keep tim-wx.js (Tencent IMSDK) in the main package; it cannot be split.

Solution

Two key constraints:

IMSDK must be initialized in the main package.

IMSDK size is 420 KB and cannot be tree‑shaken.

Option 1: Split‑Package Async

In a mini‑program, each sub‑package is a separate download unit; cross‑package require is not allowed. “Split‑package async” lets certain cross‑package code be loaded asynchronously after download.

Works with native syntax; not feasible with Uniapp/Taro due to lack of support.

Demo:

// subPackageA/index.js
import TIM from 'tim-wx-sdk';
export default TIM;

// utils/im.js
let TIM = {};
require.async('subPackageA/index')
  .then(mod => { TIM = mod; })
  .catch(({mod, errMsg}) => {
    console.error(`subPackageA path: ${mod}, ${errMsg}`);
  });
export { TIM };

// app.js
import { TIM } from '@/utils/im';
setTimeout(() => {
  TIM.login({ userID: 'xxxxx', userSig: 'userSig' });
}, 3000);

Running this results in errors because module.exports and require are CommonJS, which the mini‑program environment does not support.

Option 2: Split‑Package Plugin Async

WeChat mini‑programs support plugins via requirePlugin , which is not processed by Webpack.

Steps:

Create a plugin that simply imports and exports the IMSDK.

Register the plugin in the mini‑program configuration.

Load the plugin with requirePlugin.async and expose the SDK.

// xxx-plugin/index.js
import TIM from 'tim-wx-sdk';
module.exports = { TIM };

// utils/im.js
let TIM = null;
requirePlugin.async('xxx-plugin')
  .then(({ TIM: modTIM }) => { TIM = modTIM; })
  .catch(({ mod, errMsg }) => {
    console.error(`direct-service-plugin path: ${mod}, ${errMsg}`);
  });
export { TIM };

After loading the plugin once, subsequent calls reuse the same Promise.

// app.js
import { TIM, TIMSdk } from '@/utils/im';
await TIMSdk; // ensure SDK is loaded
const tim = TIM.create({ SDKAppID: config.SDKAppID });

Top‑level await is not yet usable in the current environment.

Compatibility

“Split‑package async” requires base library 2.11.2 or higher. If the current production version is lower, assess the impact before raising the minimum version.

Conclusion

After applying the optimizations, the main package size decreased from 1.83 MB to 1.36 MB (≈25 % reduction). Key measures include moving static assets to CDN, extracting splittable pages/components, and using split‑package async or plugin async for large SDKs like IMSDK.

Remember to set the minimum base library to 2.11.2 when using split‑package async.