Tencent Cloud

Recent Pages

Sub-package loading

Last updated: 2024-03-04 23:13:36

In certain scenarios, developers may find it necessary to partition the mini program into different sub-packages. During the construction phase, these are bundled into separate packages, which users can then load on an as-needed basis.
When building a mini program with sub-packages, the construction process will yield one or more separate packages. Each mini program using sub-packages will invariably contain a main package. This main package houses the default launch page/TabBar page, along with any common resources/JS scripts required by all sub-packages. The division of sub-packages is determined based on the developer's configuration.
Upon the initiation of the mini program, the main package is downloaded by default and its internal pages are launched. When a user navigates to a page within a sub-package, the client will download the corresponding sub-package. Once the download is complete, the page is then displayed.
The current size limitations for mini program sub-packages are as follows:
The total size of all sub-packages within the mini program must not exceed 24MB.
The size of an individual sub-package or main package must not exceed 2MB.
Sub-packaging a mini program can optimize the initial download time at launch and enhance decoupled collaboration when multiple teams are working together. The following three sub-packaging methods can be considered:
Method 1: Use sub-packages
Configuration Method
Assume the directory structure of a mini program that supports sub-packaging is as follows:
├── app.js
├── app.json
├── app.wxss
├── packageA
│   └── pages
│       ├── cat
│       └── dog
├── packageB
│   └── pages
│       ├── apple
│       └── banana
├── pages
│   ├── index
│   └── logs
└── utils
Developers can declare the project's sub-package structure in the app.json subpackages field (writing it as subPackages is also supported):
{
  "pages": ["pages/index", "pages/logs"],
  "subpackages": [
    {
      "root": "packageA",
      "pages": ["pages/cat", "pages/dog"]
    },
    {
      "root": "packageB",
      "name": "pack2",
      "pages": ["pages/apple", "pages/banana"]
    }
  ]
}
In subpackages, each sub-package configuration includes the following items:
Field
Type
Description
root
String
Sub-package Root Directory
name
StringArray
Sub-package alias, used during sub-package pre-download. If the sub-package is configured into the preloadRule, it must be specified.
pages
StringArray
Sub-package page path, relative to the sub-package root directory.
independent
Boolean
Whether the sub-package is an independent sub-package.
Packaging Principles
Upon declaring subpackages, packaging will be conducted according to the subpackages configuration path. Directories outside the subpackages configuration path will be packaged into the App (main package).
The App (main package) can also have its own pages (that is, the outermost pages field).
The root directory of a subpackage cannot be a subdirectory within another subpackage.
tabBar pages must reside within the app (main package).
Referencing Principles
packageA cannot require packageB JS files, but it can require app and JS files within its own package.
packageA cannot import packageB's template, but it can require app and templates within its own package.
packageA cannot use resources from packageB, but it can use resources from the App or within its own package.
Backward Compatibility
The compatibility with older client versions is managed by QQ's backend compilation, which compiles two sets of code packages. One is the post-subpackage code, and the other is the full-package compatibility code. The new client uses the subpackage, while the old client still uses the full package. The complete package will place the paths from each subpackage into the pages.
Method 2: Independent subpackaging
An independent subpackage is a special type of subpackage within a mini program that can operate independently from the main package and other subpackages. When entering the mini program from a page within an independent subpackage, there is no need to download the main package. The main package will only be downloaded when the user enters a page within a regular subpackage or the main package.
Developers can configure certain pages with independent functionality into independent subpackages as needed. When the mini program is launched from a regular subpackage page, the main package must be downloaded first. However, an independent subpackage can operate without relying on the main package, significantly speeding up the startup of the subpackage page.
A mini program can contain multiple independent subpackages.
Limit
Independent subpackaging is a type of subpackaging. All restrictions applicable to regular subpackaging also apply to independent subpackaging. The handling of plugins and custom components in independent subpackaging is the same as in regular subpackaging.
Additionally, when using independent subpackages, it is important to note:
Independent subpackages cannot rely on the content of the main package or other subpackages, including js files, templates, wxss, custom components, plugins, etc. The app.wxss in the main package is ineffective for independent subpackages, so the use of styles from app.wxss in independent subpackage pages should be avoided.
The App can only be defined within the main package; it cannot be defined within an independent subpackage as this would result in unpredictable behavior.
The use of plugins is currently not supported in independent subpackages.
Configuration Method
Assume the directory structure of the mini program is as follows:
├── app.js
├── app.json
├── app.wxss
├── moduleA
│   └── pages
│       ├── rabbit
│       └── squirrel
├── moduleB
│   └── pages
│       ├── pear
│       └── pineapple
├── pages
│   ├── index
│   └── logs
└── utils
Developers declare the corresponding subpackage as an independent subpackage by defining the independent field in the corresponding subpackage configuration item in the subpackages field of app.json.
{
  "pages": ["pages/index", "pages/logs"],
  "subpackages": [
    {
      "root": "moduleA",
      "pages": ["pages/rabbit", "pages/squirrel"]
    },
    {
      "root": "moduleB",
      "pages": ["pages/pear", "pages/pineapple"],
      "independent": true
    }
  ]
}
Notes
About getApp()
Unlike regular subpackages, when an independent subpackage is running, the App may not necessarily be registered, hence getApp() may not necessarily obtain the App object:
When a user launches the mini program from an independent subpackage page, the main package does not exist, nor does the App, hence calling getApp() at this time will yield undefined. Only when the user enters a page within a regular subpackage or the main package, will the main package be downloaded and the App be registered.
When a user navigates from a page within a regular subpackage or the main package to an independent subpackage page, the main package already exists, hence calling getApp() at this time can get the actual App.
Due to this constraint, developers are unable to implement global variable sharing between the independent subpackage and other parts of the mini program through the App object.
getApp supports the allowDefault parameter, returning a default implementation when the App is undefined. When the main package is loaded and the App is registered, the attributes defined in the default implementation will be overridden and merged into the actual App.
Sample Code
Independent Subpackage:
const app = getApp({allowDefault: true}) // {}
app.data = 456
app.global = {}
Within app.js:
App({
  data: 123,
  other: 'hello'
})
﻿
console.log(getApp()) // {global: {}, data: 456, other: 'hello'}
Regarding the App Lifecycle
When launching the mini program from an independent subpackage, the onLaunch and initial onShow of the App in the main package will be invoked when first entering the main package or other common subpackage pages from the independent subpackage page.
Since an App cannot be defined within an independent subpackage, the monitoring of the mini program lifecycle can be accomplished using wx.onAppShow and wx.onAppHide. Other events on the App can be monitored using wx.onError and wx.onPageNotFound.
Backward Compatibility
Note:
In compatibility mode, the app.wxss in the main package may impact the pages within the independent subpackage. Therefore, it is advisable to avoid using the styles from app.wxss within the pages of the independent subpackage.
Method 3: Subpackage pre-download
Limit
Pages within the same subpackage share a common pre-download size limit of 2MB, which is verified during the packaging process in the tool.
For instance, if pages A and B are both in the same subpackage, and A pre-downloads a total size of 0.5MB of the subpackage, then B can pre-download a maximum total size of 1.5MB of the subpackage.
Configuration Method
The pre-download subpackage behavior is triggered upon entering a certain page, and is controlled by adding a preloadRule configuration in app.json.
{
  "pages": ["pages/index"],
  "subpackages": [
    {
      "root": "important",
      "pages": ["index"]
    },
    {
      "root": "sub1",
      "pages": ["index"]
    },
    {
      "name": "hello",
      "root": "path/to",
      "pages": ["index"]
    },
    {
      "root": "sub3",
      "pages": ["index"]
    },
    {
      "root": "indep",
      "pages": ["index"],
      "independent": true
    }
  ],
  "preloadRule": {
    "pages/index": {
      "network": "all",
      "packages": ["important"]
    },
    "sub1/index": {
      "packages": ["hello", "sub3"]
    },
    "sub3/index": {
      "packages": ["path/to"]
    },
    "indep/index": {
      "packages": ["__APP__"]
    }
  }
}
Within the 
Field
Type
Required
Default value
Description
packages
StringArray
Yes
-
Upon entering the page, pre-download the sub-package's root or name. __APP__ denotes the main package.
network
String
No
wifi
Pre-download under the specified network, the optional values are:
All: Network unrestricted 
Wi-Fi: Pre-download only under Wi-Fi
﻿
﻿

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support

tencent cloud

Recent Pages

Sub-package loading

Method 1: Use sub-packages

Configuration Method

Packaging Principles

Referencing Principles

Backward Compatibility

Method 2: Independent subpackaging

Limit

Configuration Method

Notes

Sample Code

Backward Compatibility

Method 3: Subpackage pre-download

Limit

Configuration Method

Was this page helpful?

Was this page helpful?

Field	Type	Description
root	String	Sub-package Root Directory
name	StringArray	Sub-package alias, used during sub-package pre-download. If the sub-package is configured into the preloadRule, it must be specified.
pages	StringArray	Sub-package page path, relative to the sub-package root directory.
independent	Boolean	Whether the sub-package is an independent sub-package.

Field	Type	Required	Default value	Description
packages	StringArray	Yes	-	Upon entering the page, pre-download the sub-package's root or name. __APP__ denotes the main package.
network	String	No	wifi	Pre-download under the specified network, the optional values are: All: Network unrestricted Wi-Fi: Pre-download only under Wi-Fi

tencent cloud

Sign Up

Log in

Recent Pages

Sub-package loading

Method 1: Use sub-packages

Configuration Method

Packaging Principles

Referencing Principles

Backward Compatibility

Method 2: Independent subpackaging

Limit

Configuration Method

Notes

Sample Code

Backward Compatibility

Method 3: Subpackage pre-download

Limit

Configuration Method

Was this page helpful?

Was this page helpful?