Subpackage loading allows mini-program developers to segment the mini-program resources into a main package and multiple subpackages. This segmentation enables IAPMiniProgram SDK to load only the main package when the user enters the mini program, whereas the subpackages are loaded on demand when the user accesses relevant resources. It is recommended to utilize subpackage loading for the following scenarios:

• Your mini program launches slowly due to a large package size.
• You are developing the mini program across teams.

This guide offers step-by-step instructions on how to enable subpackage loading in your mini program.

Prerequisites

To enable subpackage loading, you need to meet the following requirements:

• Your Mini Program Studio (IDE) needs to be version 3.2.1032 or later. You can download the latest version on the Mini Program Platform portal.
• Your mini-program core library (also known as Appx or Lib) needs to be version 2.0 or later. You can contact your Solution Architect for the update instructions.
• The super app where your mini program runs needs to integrate IAPMiniProgram SDK version 2.47.0 or later.
  

Procedures

Mini-program developers can complete the following two steps to enable subpackage loading in the mini program:

• Step 1: Declare a subpackage structure
• Step 2: Initiate a package build

Step 1: Declare a subpackage structure

To specify the directories that belong to each subpackage, you need to complete the following three steps to declare a subpackage structure.

1. Open your mini-program project.
2. Locate and open the app.json file.
3. In the app.json file, declare the subpackage structure by defining the subPackages parameter. The following sample code shows how to define this parameter:

{
  "pages": ["pages/index", "pages/common"],
  "subPackages": [
    {
      "root": "packageA",
      "pages": ["pages/page1", "pages/page2"]
    },
    {
      "root": "packageB",
      "pages": ["pages/page3", "pages/page4"]
    }
  ]
}

The above sample code is based on the following file structure:

├── app.acss
├── app.js
├── app.json
├── packageA
│   └── pages
│       ├── page1
│       └── page2
├── packageB
│   └── pages
│       ├── page3
│       └── page4
└── pages
    ├── common
    └── index

As you can see from the sample code, the value of the subPackages parameter is an array of objects. Each object represents a subpackage. Refer to the following table for the details of the object:

When declaring the subpackage structure, you also need to learn the following packaging and reference rules:

• Mini Program Platform packages any directories that are specified outside the subPackages parameter into the main package by default.
• You must place the startup page and the tab bar pages in the main package. It is also recommended to include other frequently used core resources in this package.
• Subpackages can reference only the resources (e.g., images and JS scripts) that are contained in their own package and the main package. This means that subpackages cannot reference resources belonging to other subpackages.
• Mini Program Platform packages the main package and each subpackage separately. Therefore, the same JS module can exist both in the main package and the subpackages.

Step 2: Initiate a package build

You need to initiate a package build to run your mini program with the above-specified subpackage structure applied. To initiate the build, click any of the following three buttons in Mini Program Studio:

• Preview
• Debug
• Upload Version

Further actions

After enabling the subpackage loading, you can choose to set preload rules for the subpackages and view the package sizes for optimal performance.

Set preload rules for subpackages

You can set subpackage preload rules to enable the SDK to preload specific subpackages when the user accesses a particular page. This can improve the page transition speed and is recommended for subpackages that contain frequently visited pages.

To set the preload rules, you can specify the preloadRule parameter in the app.json file with the following sample code:

{
  "pages": ["pages/index"],
  "subPackages": [
    {
      "root": "sub1",
      "pages": ["page1"]
    },
    {
      "root": "sub2",
      "pages": ["page2"]
    },
    {
      "root": "sub3",
      "pages": ["page3"]
    },
    {
      "root": "path/sub4",
      "pages": ["page4"]
    }
  ],
  "preloadRule": {
    "pages/index": {
      "network": "all",
      "packages": ["sub1"]
    },
    "sub1/page1": {
      "packages": ["sub2", "sub3"]
    },
    "sub3/page3": {
      "network": "wifi",
      "packages": ["path/sub4"]
    }
  }
}

The value of the preloadRule parameter is specified with key-value pairs. For each key-value pair, the key is the path of the page that the user enters, and the value is an object that indicates the subpackage preload configuration on that page. Refer to the following table for how to specify the configuration:

View package sizes

To enhance the loading experience and avoid potential app crashes, it is recommended to keep the size of the main package or each subpackage within 2 MB. After the declaration, you can view the package sizes by clicking Details in Mini Program Studio. The following image shows a sample detail page:

FAQs

What if the SDK version is earlier than the required one?

Mini Program Platform can handle backward compatibility by compiling and building the source code into the following two types of packages:

• A complete source code package for the SDKs that do not support subpackage loading.
• A subpackaged source code package for the SDKs that support subpackage loading.

What should I do if the package size is too large?

It is recommended to keep the size of the main package or each subpackage within 2 MB. If your package size exceeds the limit, you can reduce it by storing some resources (such as images) on the server. If the package size is still an issue, you can segment the resources further with more subpackages.