Subpackage Loading

This feature is supported from Weixin client version 6.6.7 and base library version 2.1.0. Please upgrade to the latest client version and use Weixin DevTools version 1.02.1806120 or later. Click here to download

As Mini Game gameplay grows richer, developers require ever-larger packages. This is why we introduced the subpackage loading feature. Subpackage loading splits the content of a Mini Game into several packages based on specific rules. The first time a user launches the Mini Game, only the necessary package is downloaded. We call this necessary package the “Main Package”. In the main package, developers can trigger the download of subpackages so that the total download time is dispersed throughout the playing time.

Subpackage Loading Size Restrictions

The sizes of Mini Game subpackages are restricted as follows:

  • The total size of all subpackages of a Mini Game cannot exceed 8 MB.
  • A single subpackage or main package cannot exceed 4 MB.


1. Subpackage Configuration

First, you must configure subpackage information in game.json.

Assume the game directory structure is as follows:

├── game.js
├── game.json
├── images
│   ├── a.png
│   ├── b.png
├── stage1
│   └── game.js
│   └── images
│       ├── 1.png
│       ├── 2.png
└── stage2.js

The configuration in game.json is as follows:

  "subpackages": [
      "name": "stage1",
      "root": "stage1/" // can specify a directory. The game.js file in the root directory of this directory is the entry file, and all the resources in the directory are packaged together.
    }, {
      "name": "stage2",
      "root": "stage2.js" // can also specify a JS file.

When this option is configured, the directories or JS files in the subpackages field are packaged into “subpackages”. When the option is not configured, the directories and JS files in subpackages are packaged in the main package.

Note: Open data domain directories (i.e. openDataContext configuration directories) cannot be set as subpackages or placed in a subpackage.

2. Subpackage Loading

We provide the wx.loadSubpackage() API to trigger subpackage downloads. You can call wx.loadSubpackage to trigger subpackage download and loading. After the subpackage is loaded, the success callback of the wx.loadSubpackage notifies the Mini Game that loading is complete.

At the same time, wx.loadSubpackage returns a LoadSubpackageTask, which gets the current download progress from LoadSubpackageTask.

Sample code:

const loadTask = wx.loadSubpackage({
  name: 'stage1', // name can be name or root.
  success: function(res) {
    // The success callback implemented after a subpackage is loaded.
  fail: function(res) {
    // The fail callback implemented when a subpackage fails to load.

loadTask.onProgressUpdate(res => {
  console.log('Download progress', res.progress)
  console.log('The length of downloaded data ', res.totalBytesWritten)
  console.log('The length of data expected to be downloaded ', res.totalBytesExpectedToWrite)

Compatibility with Older Versions

Compatibility with older client versions is handled by the compiler in the Weixin backend, which compiles two code packages. One is the subpackaged code and the other is a complete package with compatible code. The complete package is downloaded and run by older client versions.

Developers using base library version 2.1.0 or lower do not have to call wx.loadSubpackage to trigger loading. The wx.loadSubpackage method does not exist in these versions.

In older versions, developers must call require to trigger the loading of the subpackage entry file. For example:


In Weixin client version 6.6.7 and below, because developer versions/test versions have compatibility issues, subpackaged Mini Games cannot be opened. However, official release versions are not affected. If compatibility with older versions is not required, developers can use the MP backend configuration to block users with base library versions of 2.1.0 or below.