tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Tencent Cloud Mini Program Platform
    Documentation
    Download PDF

    Subpackage Loading

    Last updated: 2024-07-12 18:33:47
    Download PDF

      1. Using Subpackage

      1.1 Configuration

      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.
      {
        "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 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

      1.2 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).

      1.3 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.

      2. Independent Subpackage

      An independent subpackage is a special type of subpackage in Mini Programs. It can run independently of the main package and other subpackages. When a user enters a Mini Program from a page of an independent subpackage, the main package will not be downloaded, unless the user enters a page of an ordinary subpackage or a main package.
      Developers can add some functionally independent pages to an independent subpackage as needed. When a Mini Program is launched from a page of an ordinary subpackage, the main package should be downloaded first. However, an independent subpackage can run independently of the main package. Therefore, subpackages greatly improve the startup speed of Mini Programs.
      A Mini Program can have multiple independent subpackages.

      2.1 Configuration

      Assume that the directory structure of a Mini Program is as follows:
      ├── app.js
      ├── app.json
      ├── app.wxss
      ├── moduleA
      │   └── pages
      │       ├── rabbit
      │       └── squirrel
      ├── moduleB
      │   └── pages
      │       ├── pear
      │       └── pineapple
      ├── pages
      │   ├── index
      │   └── logs
      └── utils
      The developer declares a subpackage as an independent subpackage by defining the independent field in the 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
          }
        ]
      }

      2.2 Limits

      The independent subpackage is a type of subpackage. All limits on ordinary subpackages are applicable to independent subpackages. Plug-ins and custom components in an independent subpackage are processed in the same way as with those in an ordinary subpackage:
      Also note the following when using independent subpackages:
      The content of an independent subpackage must be independent of the main package and other subpackages, including JS files, template, wxss, custom components, and plug-ins. app.wxss in the main package does not take effect for independent subpackages. Therefore, the styles in app.wxss should be avoided on pages of independent subpackages;
      App can be defined only in the main package. Defining App in independent subpackages will cause unexpected behaviors;
      Plug-ins are not supported in independent subpackages.

      2.3 Notes

      2.3.1 About getApp()

      Unlike ordinary sub-packages, when an independent subpackage is running, App is not necessarily registered. Therefore, an App object can not necessarily be obtained via getApp():
      When a user starts a Mini Program from a page of an independent subpackage, neither main package nor App exists. In this case, undefined is obtained when getApp() is called. The main package is downloaded and App can be registered only when the user opens a page of an ordinary subpackage or a main package.
      When a user is redirected to a page of an independent subpackage from a page of an ordinary subpackage or the main package, the main package already exists, and the actual App can be obtained by calling getApp().
      Because of this restriction, developers can not share global variables between independent subpackages and other parts of a Mini Program by using the App object.
      To satisfy this requirement in a standalone sub-package, getApp supports the [allowDefault] parameter, which returns a default implementation when the App is undefined. When the main package is loaded and the App is registered, the properties defined in the default implementation will be overridden and merged into the real App.
      Sample code:
      In the independent subpackage
      const app = getApp({allowDefault: true}) // {}
      app.data = 456
      app.global = {}
      In the app.js file
      App({
        data: 123,
        other: 'hello'
      })
      
      console.log(getApp()) // {global: {}, data: 456, other: 'hello'}

      2.3.2 About the lifecycle of App

      If the Mini Program is launched from a page of an independent subpackage, onLaunch and first-time onShow of App in the main package are called when the user is redirected from the page of the independent subpackage to a page of the main package or an ordinary subpackage for the first time.
      Because App cannot be defined in an independent subpackage, the lifecycle of a Mini Program can be listened via wx.onAppShow and wx.onAppHide. Other events on App can be listened via wx.onError and wx.onPageNotFound.

      3. Subpackage Preload

      Developers can configure the framework to automatically preload required subpackages when a user enters a Mini Program page, to speed up the subsequent startup of subSubcontracting Asynchronisationpackaged pages. For Independent Subpackages, the main package can also be preloaded.
      Subpackages can be preloaded only via configuration.
      Log prefixed with preloadSubpackages is available in vConsole to verify the preload status

      3.1 Configuration

      Subpackage preload is triggered when a user enters a specific page, and is controlled by adding preloadRule configuration items via 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 preload configuration for entering the page. Each configuration includes the following items:
      Field
      Type
      Required
      Default
      Description
      packages
      StringArray
      Yes
      No
      Indicates root or name of a subpackage preloaded after a user enters a page. __APP__ indicates the main package.
      network
      String
      No
      wifi
      Indicates a specified network over which a subpackage is preloaded. Values: all: Any network wifi: Wi-Fi only

      3.2 Limits

      Pages of the same subpackage share the same maximum preload size of 2 MB, which is verified when the pages are packaged via the DevTools.
      For example, Page A and Page B are in the same subpackage. If a subpackage with a total size of 0.5 MB is preloaded on Page A, a maximum of 1.5 MB subpackages can be preloaded on Page B.

      4. Subcontracting Asynchronisation

      In mini programs, different sub-packages correspond to different download units; therefore, except for non-independent sub-packages that can rely on the main package, sub-packages cannot use custom components or require each other. the "sub-package asynchronisation" feature will allow this limitation to be solved to a certain extent by allowing, through some configurations and new interfaces, some cross-sub-packages to wait for the download and then use the content asynchronously.

      4.1 Cross-subcontract custom component references

      When a sub-package uses a custom component from another sub-package, the other sub-package's component is in an unavailable state because the other sub-package has not yet downloaded or injected it. By setting a placeholder component for the custom component of the other sub-package, we can render the placeholder component as a replacement first, and then replace it after the sub-package has finished downloading. Example:
      // subPackageA/pages/index.json
      {
        "usingComponents": {
          "button": "../../commonPackage/components/button",
          "list": "../../subPackageB/components/full-list",
          "simple-list": "../components/simple-list",
          "plugin-comp": "plugin://pluginInSubPackageB/comp"
        },
        "componentPlaceholder": {
          "button": "view",
          "list": "simple-list",
          "plugin-comp": "view"
        }
      }
      In this configuration, the button and list custom components are cross-package references, where the button is rendered using the built-in component view as a replacement, and the list is rendered using the current sub-package's custom component simple-list as a replacement; after these two sub-packages have been downloaded, the placeholder component is replaced with the corresponding cross-package component After both packages are downloaded, the placeholder component is replaced with the corresponding cross-package component.

      4.2 Cross-Subpackage JS Code References

      When code in a sub-package references code in another sub-package, we need to asynchronously get the result of the reference in order to prevent the download from blocking the code. For example:
      // subPackageA/index.js
      // Use a callback function style call
      require('../subPackageB/utils.js', utils => {
        console.log(utils.whoami) // Wechat MiniProgram
      }, ({mod, errMsg}) => {
        console.error(`path: ${mod}, ${errMsg}`)
      })
      // Or use a Promise-style call
      require.async('../commonPackage/index.js').then(pkg => {
        pkg.getPackageName() // 'common'
      }).catch(({mod, errMsg}) => {
        console.error(`path: ${mod}, ${errMsg}`)
      })
      See the Modularity - require section for more details.
      Contact Us

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

      Contact Us
      Technical Support

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

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy