tencent cloud

Subpackage Loading
Download PDF
Last updated: 2025-05-26 15:27:37
Subpackage Loading
Last updated: 2025-05-26 15:27:37
Download PDF
As mini games become more complex, developers increasingly need larger package sizes. To address this, we have introduced the subpackage loading feature. Subpackage loading allows you to split game content into several packages according to certain rules. During the initial launch, only the necessary package, called the "main package" is downloaded. Developers can then trigger the download of other subpackages from within the main package, spreading the download time across the game's runtime.
Developers can use the framework's built-in subpackage loading capabilities or configure subpackages directly in game.json without using the framework. Details are described below.

Subpackage size limits

Currently, the size limits for mini game subpackages are as follows:
The total size of all main and subpackages must not exceed 20 MB.
The main package must not exceed 4 MB.
There is no size limit for individual regular subpackages.
Individual independent subpackages must not exceed 4 MB.

Use subpackages

Configuration method

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
└── utils
Configuration in game.json 
{
  ...
  "subpackages": [
    {
      "name": "stage1",
      "root": "stage1/" // Specify a directory; the game.js in the root directory will be the entry file, and all resources in the directory will be packaged together
    }, {
      "name": "stage2",
      "root": "stage2.js" // You can also specify a JS file
    }
  ]
  ...
}
Each subpackage configuration in subpackages includes the following fields:
Field
Type
Description
root
String
Root directory of the subpackage.
name
String
Alias of the subpackage, used for Subpackage Loading.
independent
Boolean
Whether the subpackage is independent

Packaging principles

After declaring subpackages , the paths specified in subpackages will be packaged accordingly. Directories outside the subpackages configuration paths will be packaged into the main package. The root directory of a subpackage cannot be a subpackage of another subpackage.

Referencing principles

packageA cannot require JS files from packageB , but can require JS files from the main package or within packageA .
packageA cannot use resources from packageB , but can use resources from the main package or within packageA .

Independent subpackages

Independent subpackages are a special type of subpackage that can run independently of the main package and other subpackages. When starting a mini game with the path of an independent subpackage, the client will only download the independent subpackage and start the game, without downloading the main package. This allows for faster game startup in certain scenarios. Developers can configure certain functionally independent pages into independent subpackages to significantly improve page load speed.
After starting an independent subpackage, developers can use the wx.loadSubpackage to pre-download the main package or other subpackages and execute the downloaded code package logic at an appropriate time (e.g. when the user taps "Start Game").

Configuration method

Assume the mini game directory structure is as follows:
.
├── game.js
├── game.json
├── moduleA
│ └── game.js
├── moduleB
│ └── game.js
└── utils
Developers can declare a subpackage as independent by defining the independent field in the corresponding subpackage configuration item in the subpackages field ofgame.json.
{
  "subPackages": [
    {
      "name": "moduleA",
      "root": "/moduleA/", // Regular subpackage
    },
    {
      "independent": true, // Independent subpackage, specify a directory; the game.js in the root directory will be the entry file, and all resources in the directory will be packaged together
      "name": "moduleB",
      "root": "/moduleB/",
    }
  ]
}
Sharing a specific independent subpackage page within the game:
// Share with friends or groups
wx.shareAppMessage({
  title: 'Share the title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
Share on Moments
wx.onShareTimeline({
  title: 'Share the title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
// Add to Favorites
wx.addToFavorites({
  title: 'Favorite title',
  imageUrl: 'xx.jpg',
  query: 'a=1&b=2',
  path: '/moduleB/' // path corresponds to the root of the independent subpackage as configured in game.json
})
Download other subpackages within an independent subpackage
const loadTask = wx.loadSubpackage({
  name: '/moduleA/', // Download another subpackage
  success(res) {
    console.log('load moduleA success', res)
  },
  fail(err) {
    console.error('load moduleA fail', err)
  }
})

Notes

A mini game can have multiple independent subpackages.
Independent subpackage startup is only effective for cold starts.
Independent subpackages are a type of subpackage. All restrictions on regular subpackages apply to independent subpackages as well.
Independent subpackages cannot depend on content from the main package or other subpackages,including JS files and resource files.
The path parameter in wx.shareAppMessage or the return parameter in wx.onShareAppMessage must be the root field of the independent subpackage as defined in game.json.

Subpackage loading

We provide the wx.loadSubpackage() API to trigger the download of subpackages. When wx.loadSubpackage is called, it triggers the download and loading of the subpackage. Once the loading is complete, the success callback of wx.loadSubpackage will notify you of the completion.
Additionally, wx.loadSubpackage returns a LoadSubpackageTask, which can be used to get the current download progress.
Example:
const loadTask = wx.loadSubpackage({
  name: 'stage1', // name can be either the name or the root
  success: function(res) {
    // Callback for successful subpackage loading
  },
  fail: function(res) {
    // Callback for failed subpackage loading
  }
})

loadTask.onProgressUpdate(res => {
  console.log('Download progress', res.progress)
  console.log('Downloaded data length', res.totalBytesWritten)
  console.log('Expected total data length', res.totalBytesExpectedToWrite)
})

Subpackage preloading

We provide the wx.preDownloadSubpackage() API to trigger the pre-download of subpackages. When wx.preDownloadSubpackage is called, it triggers the download and loading of the subpackage. Once the loading is complete, the success callback of wx.preDownloadSubpackage will notify you of the completion. After preloading, you need to use wx.loadSubpackage to execute the subpackage code.
The difference between wx.preDownloadSubpackage() and wx.loadSubpackage() is that wx.preDownloadSubpackage only downloads the code package without automatically executing the code, whereas wx.loadSubpackage downloads and then automatically executes the code.
Example:
// Preload
const loadTask = wx.preDownloadSubpackage({
  name: 'stage1',
  success: function(res) {
    // Callback for successful subpackage preloading
  },
  fail: function(res) {
    // Callback for failed subpackage preloading
  }
})

loadTask.onProgressUpdate(res => {
  console.log('Download progress', res.progress)
  console.log('Downloaded data length', res.totalBytesWritten)
  console.log('Expected total data length', res.totalBytesExpectedToWrite)
})

// Execute subpackage code logic at an appropriate time
wx.loadSubpackage({
  name: 'stage1'
})


Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback