tencent cloud

Tencent Cloud Super App as a Service

Release Notes and Announcements
Announcement: Tencent Cloud Mini Program Platform Renamed to Tencent Cloud Super App as a Service on January 2, 2025
Console Updates
Android SDK Updates
iOS SDK Updates
Flutter SDK Updates
IDE Updates
Base Library Updates
Product Introduction
Overview
Strengths
Use Cases
Purchase Guide
Billing Overview
Pay-As-You-Go Billing
Renewal Guide
Service Suspension Instructions
Getting Started
Plan Management
Overview
Console Account Management
Storage Configuration
Acceleration Configuration
Branding Configurations
Platform Features
Console Login
Users and Permission System
Mini Program Management
Mini Game Management
Superapp Management
Commercialization
Platform Management
User Management
Team Management
Operations Management
Security Center
Code Integration Guide
Getting Demo and SDK
Android
iOS
Flutter
Superapp Server
GUID Generation Rules
Mini Program Development Guide
Mini Program Introduction and Development Environment
Mini Program Code Composition
Guide
Framework
Components
API
Server Backend
JS SDK
Base Library
IDE Operation Instructions
Mini Game Development Guide
Guide
API
Server Backend
Practice Tutorial
Mini Program Login Practical Tutorial
Mini Program Subscription Message Practical Tutorial
Payment Practical Tutorial
Ad Integration Practical Tutorial
Mini Game Subscription Message Practical Tutorial
API Documentation
History
Introduction
API Category
Making API Requests
Operation Management APIs
User Management APIs
Team Management APIs
Sensitive API-Related APIs
Role Management APIs
Platform Management APIs
Other Console APIs
Mini Program or Mini Game APIs
Management-Sensitive APIs
Global Domain Management APIs
Superapp APIs
Data Types
Agreements
Service Level Agreement
Data Processing and Security Agreement
SDK Privacy Policy Module
SDK Data Processing and Security Agreement Module

Subpackage Loading

PDF
Focus Mode
Font Size
Last updated: 2025-05-26 15:27:37
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'
})



Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback