# Independent Subpackage

This feature is supported from Weixin 6.7.2 and base library 2.3.0 onwards. Download a Weixin DevTools as of version 1.02.1808300.

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.

Mini Games do not support independent subpackages.

# 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
    }
  ]
}

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

# Notes

# (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 meet this requirement in an independent subpackage, getApp starts to support the [allowDefault] parameter as of base library {% version ('2.2.4')%}, and returns a default implementation when App is undefined. In this case, when a main package is loaded and App is registered, the property defined in the default implementation is overwritten and merged into the actual 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) 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.

# Compatibility with Lower Versions

When running in the Weixin earlier than 6.7.2, an independent subpackage is processed as an ordinary subpackage, and therefore cannot run independently.

Note: In the compatibility mode, app.wxss in the main package may affect the pages of an independent subpackage. Therefore, the styles in app.wxss should be avoided on pages of independent subpackages.