Subcontracted load

WeChat client 6.6.0, base library 1.7.3 and above versions are beginning to support. D eveloper tools are available for download here using versions 1.01.1712150 and above.

In some cases, developers need to divide small programs into different subcontracts, package them into different subcontracts at build time, and load them on demand when they use them.

When you build a small program subcontract project, the build outputs one or more subcontracts. E ach subcontracted program must contain a master package. The so-called master package, which places the default launch/TabBar page, and some of the public resources/JS scripts are required for all subcontracts, which are divided according to the developer's configuration.

When the small program starts, the default downloads the main package and starts the in-package page, and when the user enters a page within the subcontract, the client downloads the corresponding subcontract and displays it when the download is complete.

There are currently the following limits on the size of small program subcontracts:

• All subcontract sizes for the entire sub-program do not exceed 16M
• A single subcontract/master package size cannot exceed 2M

Subcontracting a small program optimizes the download time at which the small program starts for the first time, and better decoupling collaboration when developed by multiple teams.

For specific use, please refer to:

1, the use of subcontracts

The configuration method

Suppose the subcontracted gadget directory structure is as follows:

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

Developers declare the project subcontract structure by using the app.json subpackages field:

Writing 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, there are several configurations for each subcontract:

Field	Type	Description
root	String	Subcontract the root
name	String	Subcontracted alias, which can be used for pre-download
pages	StringArray	The subcontracted page path, relative to the subcontracted root
independent	Boolean	Whether the subcontract is a stand-alone subcontract

Packaging principles

• After the subpackages are declared, they are packaged according to the subpackages configuration path, and the directories outside the subpackages configuration path are packaged into the app (main package).
• Apps (main package) can also have their own pages (i.e. the outerst page field)
• The root directory of subpackage cannot be a subdirecte within another subpackage
• The tabBar page must be in the app (main package).

The principle of reference

• PackageA cannot require packageB JS files, but you can require apps, JS files within your own package
• PackageA cannot import the template of packageB, but you can require the app, the template within your own package
• PackageA can't use packageB's resources, but it can use the app, the resources within your own package

The lower version is compatible

Compiled by WeChat background to handle the compatibility of older clients, the background compiles two code packages, one is subcontracted code, the other is the entire package of compatible code. The new client is subcontracted, the old client is still the package, and the full package places the paths inside each subpackage in the pages.

The sample project

Download the sample (subcontracted load) source code for the small program

2, independent subcontract

WeChat Client 6.7.2, Base Library 2.3.0 and above are supported. D eveloper tools are available for download using versions 1.02.1808300 and above.

A stand-alone subcontract is a special type of subcontract in a small program that can run independently of the main package and other subcontracts. W hen you enter a small program from a separate subcontract page, you do not need to download the main package. The main package is downloaded only when the user enters the normal subcontract or the main package page.

Developers can configure some pages that have some functional independence to a separate subcontract on demand. When a small program starts from a normal subcontracted page, you need to download the main package first, while a stand-alone subcontract can run without relying on the main package, which can greatly speed up the startup of the subcontracted page.

There can be multiple separate subcontracts in a small program.

The game does not support stand-alone subcontracting.

The configuration method

Suppose the program directory structure is as follows:

├── app.js
├── app.json
├── app.wxss
├── moduleA
│   └── pages
│       ├── rabbit
│       └── squirrel
├── moduleB
│   └── pages
│       ├── pear
│       └── pineapple
├── pages
│   ├── index
│   └── logs
└── utils

The developer declares the corresponding subcontract as a separate subcontract by defining the independent field in the corresponding subcontract 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
    }
  ]
}

Limit

A stand-alone subcontract is one of the subcontracts. A ll restrictions on normal subcontracts are valid for independent subcontracts. Plug-ins and custom components in a stand-alone subcontract are handled in the same way as normal subcontracts.

Also, when using stand-alone subcontracts, be aware of:

• You cannot rely on the main package and other subcontracts in a stand-alone subcontract, including js files, templates, wxss, custom components, plug-ins, and so on. App.wxss in the main package is not valid for stand-alone subcontracts and styles in app.wxss should be avoided on stand-alone subcontracted pages;
• Apps can only be defined within the main package, and apps cannot be defined in separate subcontracts, resulting in unpredictable behavior;
• The use of plug-ins is not currently supported in stand-alone subcontracts.

Precautions

(1) About getApp()

Unlike regular subcontracts, apps are not necessarily registered at stand-alone subcontract runtimes, so getApp() does not necessarily have access to app objects:

• When the user starts the applet from a stand-alone subcontracted page, the main package does not exist, and the app does not exist, at which point the getApp() is called undefined. The main package is downloaded and the app is registered only when the user enters the normal subcontract or the main package page.
• When a user jumps to a stand-alone subcontract page from a normal subcontract or an in-primary package page, the primary package already exists, and getApp() can be called to get the real app.

Because of this limitation, developers cannot implement separate subcontracts and global variable sharing of other parts of the program through app objects.

To meet this requirement in a stand-alone subcontract, the base library version 2.2.4 starts with getApp support for the "allowDefault" parameter, returning a default implementation when the app is not defined. When the main package is loaded and the app is registered, the properties defined in the default implementation are overwritten and merged into the real app.

Example code:

• In a separate subcontract

const app = getApp({allowDefault: true}) // {}
app.data = 456
app.global = {}

• in .js app

App({
  data: 123,
  other: 'hello'
})

console.log(getApp()) // {global: {}, data: 456, other: 'hello'}

(2) About the app lifecycle

When you start a small program from a stand-alone subcontract, the onLaunch and first-time onShow of the app in the main package are called when they first enter the main package or other normal subcontracted page from the stand-alone subcontracted page.

Because apps cannot be defined in stand-alone subcontracts, listening to the applet lifecycle can be done using wx.onAppShow, wx.onAppHide. Other events on the app can be monitored using wx.onError, wx.onPageNotFound.

The lower version is compatible

When running in WeChat below version 6.7.2, independent subcontracting is considered normal subcontract processing and does not have the characteristics of independent operation.

Note: In compatibility mode, app.wxss in the main package may have an impact on pages in a stand-alone subcontract, so you should avoid using styles in app.wxss on stand-alone subcontracted pages.

3, subcontract pre-download

Base library 2.3.0 starts to support, and low versions need to be compatible. D eveloper tools are available for download using versions 1.02.1808300 and above.

Developers can configure that when entering a page of a small program, the framework automatically pre-downloads the subcontracts that may be required to increase the startup speed when entering subsequent subcontracted pages. For stand-alone subcontracts, you can also pre-download the main package.

Subcontracted pre-downloads are currently only supported by configuration, and are not currently supported through calling the API.

vConsole has log information at the beginning of the preload Subpackages that can be used to verify pre-downloads.

The configuration method

The pre-download subcontract behavior is triggered when you enter a page and is controlled by adding a preloadRule configuration to 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__"]
    }
  }
}

In preloadRule, key is the page path, and value is the pre-download configuration that goes to this page, each with the following:

Field	Type	Required	The default	Description
packages	StringArray	Is	No	When you go to the page, pre-download the root or root the name __APP__ the main package.
network	String	Whether	Wifi	Pre-download under the specified network, with optional values: all : Unlimited network wifi : Pre-download only under wifi

Limit

Pages in the same subcontract have a common pre-download size limit of 2M, which is checked when packaged in the tool.

For example, pages A and B are in the same subcontract, A pre-downloads a subcontract with a total size of 0.5M, and B can only pre-download a subcontract with a total size of 1.5M.