Using Subpackage


Assume that the directory structure of a Mini Program supporting subpackages is as follows:

├── app.js
├── app.json
├── app.wxss
├── packageA
│   └── pages
│       ├── cat
│       └── dog
├── packageB
│   └── pages
│       ├── apple
│       └── banana
├── pages
│   ├── index
│   └── logs
└── utils

The developer declares the subpackage structure of a project in the subpackages field via app.json:

The field can also be written as subPackages.

  "subpackages": [
      "root": "packageA",
      "pages": [
    }, {
      "root": "packageB",
      "name": "pack2",
      "pages": [

In subpackages, each subpackage are configured with the following fields:

Field Type Description
root String Root directory of subpackage
name String Alias of subpackage, which can be used in Subpackage Preload
pages StringArray Subpackage page path, which is relative to the root directory of the subpackage
independent Boolean Indicates whether a subpackage is an Independent Subpackage

Packaging Rules

  • After subpackages is declared, files are packaged based on the paths configured in subpackages, and files in the directories outside the paths in subpackages are packaged into the app (main package).
  • The app (main package) can also have its own pages (i.e. the outermost pages field).
  • The root directory of subpackage cannot be a subdirectory configured in another subpackage. The tabBar page must be in the app (main package).

Referencing Rules

  • packageA cannot require JS files in packageB, but can require JS files in app and packageA.
  • packageA cannot import templates in packageB, but can import templates in app and packageA.
  • packageA cannot use resources in packageB, but can use resources in app and packageA.

Compatibility with Lower Versions

The compatibility with earlier versions of Weixin is handled by compiling two code packages on the Weixin backend: one is code obtained after pages are subpackaged, and the other is the compatible code of the whole package. The subpackages are used in new versions, and the whole package is still used in earlier versions. In the whole package, the path in each subpackage is put into pages.

Sample Project

Download the source code of a Mini Program sample (for subpackage preload)