# Global Configuration
The app.json file in the Mini-Program root directory is used for global configuration of the Mini-Program. The file content is a JSON object.
Extended Functionality
You can create an app.ext.json file. This file will be merged with app.json, prioritizing configurations from app.ext.json (same applies for pages and components).
# 1. Configuration Items
| Property | Type | Required | Description | Minimum Version |
|---|---|---|---|---|
| entryPagePath | string | No | Default startup homepage for the Mini-Program | |
| pages | string[] | Yes | List of page paths | |
| window | Object | No | Global default window behavior | |
| tabBar | Object | No | Bottom tab bar behavior | |
| debug | boolean | No | Whether to enable debug mode, deprecated | |
| subpackages | Object[] | No | Subpackage structure configuration | 2.10.1 |
| plugins | Object | No | Plugins used | 2.11.1 |
| preloadRule | Object | No | Subpackage preload rules | 2.11.1 |
| resizable | boolean | No | Whether PC Mini-Program supports users arbitrarily resizing the window (including maximizing the window); Whether iPad Mini-Program supports screen rotation. Default is off. | 2.3.0 |
| usingComponents | Object | No | Global custom component configuration | |
| style | string | No | Specify using the upgraded WeUI styles | 2.11.1 |
| useExtendedLib | Object | No | Specify the extended libraries to be referenced | 2.12.2 |
| darkmode | boolean | No | Mini-Program supports DarkMode | 2.11.8 |
| themeLocation | string | No | Specifies the location of theme.json, required when darkmode is true | 2.11.8 |
| networkTimeout | Object | No | Network timeout durations | |
| requiredBackgroundModes | Object | No | Capabilities required for background use, such as "Music Playback" | |
| referer | string | No | After configuration, some components or APIs within the Mini-Program will carry this referer value when initiating HTTP resource requests. The concatenation rule is {referer}/{appid}/{version}/view.html | |
| permission | Object | No | Mini-Program API permission related settings. Refer to the description below for configuration details. | |
| lazyCodeLoading | string | No | Only supports the value requiredComponents, indicating enabling the "Lazy Code Loading" feature for the Mini-Program. |
Please Note
The following configuration items are not currently supported.
| Name | Function Description |
|---|---|
| entranceDeclare | Open Mini-Program via WeChat messages |
| functionalPages | Whether to enable plugin functional pages, default is off |
| sitemapLocation | Specifies the location of sitemap.json |
| workers | Directory for placing Worker code |
| singlePage | Single-page mode related configuration |
| supportedMaterials | Chat material Mini-Program opening related configuration |
| serviceProviderTicket | Customized service provider ticket |
| embeddedAppIdList | Half-screen Mini-Program appId list |
| halfPage | Video Channel live stream half-screen scenario settings |
# entryPagePath
Specifies the default startup path (homepage) for the Mini-Program. If left blank, it defaults to the first item in the pages list. Does not support path parameters.
# pages
Used to specify which pages constitute the Mini-Program. Each item corresponds to the path (including filename) information of a page. The file suffix should not be written; the framework will automatically search for the corresponding .json, .js, .fxml, and .ftss files in the location for processing.
When entryPagePath is not specified, the first item in the array represents the initial page (homepage) of the Mini-Program.
Adding or removing pages in the Mini-Program requires modifying the pages array.
For example, with a development directory structure of:
├── app.js
├── app.json
├── app.ftss
├── pages
│ │── index
│ │ ├── index.fxml
│ │ ├── index.js
│ │ ├── index.json
│ │ └── index.ftss
│ └── logs
│ ├── logs.fxml
│ └── logs.js
└── utils
You need to write the following in app.json:
{
"pages": ["pages/index/index", "pages/logs/logs"]
}
# window
Used to set the status bar, navigation bar, title, and window background color for the Mini-Program.
| Property | Type | Default Value | Description | Minimum Version |
|---|---|---|---|---|
| homeButton | boolean | false | Displays the home button in the navigation bar on pages that are not the homepage, not the bottom of the page stack, or not within a tabbar page. | Supported from iOS and Android 2.41.13 |
| navigationBarBackgroundColor | HexColor | #000000 | Navigation bar background color, e.g., #000000 | |
| navigationBarTextStyle | string | white | Navigation bar title color, only supports black / white | |
| navigationBarTitleText | string | Navigation bar title text content | ||
| navigationStyle | string | default | Navigation bar style, only supports the following values: 1. default (default style), 2. custom (custom navigation bar, only retains the top-right capsule button, invalid for web-view component), 3.customV2 (custom navigation bar, only retains the top-right capsule button), 4.hide (hides navigation bar and top-right capsule button) | |
| navigationBarHideCloseButton | Boolean | false | Hide the capsule close button | |
| navigationBarHideMoreButton | Boolean | false | Hide the capsule menu button | |
| backgroundColor | HexColor | #ffffff | Window background color | |
| backgroundColorContent | HexColor | Page container background color | Supported from iOS and Android 2.46.13, HarmonyOS 1.1.5 | |
| backgroundTextStyle | string | dark | Pull-down loading style, only supports dark / light | |
| backgroundColorTop | string | #ffffff | Top window background color, only supported on iOS | |
| backgroundColorBottom | string | #ffffff | Bottom window background color, only supported on iOS | |
| enablePullDownRefresh | boolean | false | Whether to enable global pull-down refresh. See Page.onPullDownRefresh for details. | |
| pageOrientation | string | portrait | Screen rotation settings, supports auto / portrait / landscape | |
| initialRenderingCache | string | Page initial rendering cache configuration, supports static / dynamic | ||
| onReachBottomDistance | The distance from the bottom of the page when the page's reach bottom event is triggered, in px. See Page.onReachBottom for details. | 2.12.8 | ||
| disableBackForwardGesture | boolean | false | Used to control whether the swipe-back gesture for Mini-Program pages is enabled. | Supported from iOS and Android 2.45.3; HarmonyOS 1.1.2; |
| handleWebviewPreload | string | No | Controls the timing for preloading the next page. Supports static / manual, default value static. | Supported from SDK 2.43.11 |
Please Note
The following configuration items are not currently supported.
| Name | Function Description |
|---|---|
| restartStrategy | Restart strategy configuration |
| visualEffectInBackground | When switching to the system background, hide page content to protect user privacy. Supports hidden / none |
# tabBar
tabBar is used to configure the style of the bottom or top tab navigation bar in the Mini-Program, as well as the pages to navigate to.
Detailed configuration items are as follows:
| Property | Type | Required | Default Value | Description |
|---|---|---|---|---|
| color | HexColor | Yes | Default text color on tabs | |
| selectedColor | HexColor | Yes | Text color on tabs when selected | |
| backgroundColor | HexColor | Yes | Background color of the tab bar | |
| borderStyle | String | No | black | Color of the top border of the tabbar, only supports black, white |
| list | Array | Yes | List of tabs, see list property description for details, supports 2-5 tab options | |
| position | String | No | bottom | Position of the tabBar, only supports two values: bottom, top |
The list is an array type and can only be configured with a minimum of 2 and a maximum of 5 tabs.
Tabs are sorted according to the array order. Each item is an independent object with the following configurable values:
| Property | Type | Required | Description |
|---|---|---|---|
| pagePath | String | Yes | Page path, must be defined first in the pages array |
| text | String | Yes | Button text on the tab |
| iconPath | String | No | Image path, icon size limit is 40kb, recommended size is 81px * 81px, network images are not supported. When position is top, icon is not displayed. |
| selectedIconPath | String | No | Image path when selected, requirements same as iconPath |
# networkTimeout
Timeout durations for various network requests, all in milliseconds.
| Property | Type | Required | Default Value | Description |
|---|---|---|---|---|
| request | number | No | 60000 | Timeout for wx.request, unit: milliseconds. |
| connectSocket | number | No | 60000 | Timeout for wx.connectSocket, unit: milliseconds. |
| uploadFile | number | No | 60000 | Timeout for wx.uploadFile, unit: milliseconds. |
| downloadFile | number | No | 60000 | Timeout for wx.downloadFile, unit: milliseconds. |
# debug
Boolean type. When configured as true, a vconsole info viewing button is added to the Mini-Program after scanning the QR code, facilitating developers to view logs (deprecated).
Can be enabled via:
Calling the Mini-Program API (
ft.setEnableDebug) to enable Debug mode.For non-production versions (e.g., Trial, Audit, Development, Preview versions), Debug mode can be enabled via [Open Debugging] in the More menu.
# subpackages
Declares the project's subpackage structure when分包加载 is enabled.
# plugins
Declares the plugins required by the Mini-Program.
# preloadRule
Declares the rules for分包预下载.
# resizable
Mini-Programs running on iPad can be set to support screen rotation.
For Mini-Programs running on PC, users can drag the window to any proportion, or maximize the window via the Mini-Program menu.
# usingComponents
Custom components declared in app.json are considered global custom components and can be used directly within pages or custom components of the Mini-Program without redeclaration.
Note: Globally declared custom components are considered dependencies of all pages, are initialized when all pages start, and occupy主包 size. Custom components referenced only by individual pages or subpackages should preferably be declared in the page configuration.
# style
Starting from WeChat client version 7.0, the UI underwent a major redesign. Mini-Programs also upgraded the styles of their basic components. Configuring "style": "v2" in app.json indicates enabling component styles compatible with the new WeChat version.
Components affected by this change include:
- button
- icon
- radio
- checkbox
- switch
- slider
# useExtendedLib
Specifies the extended libraries to be referenced. Currently supports the following items:
After specification, it is equivalent to importing the latest version npm packages related to the corresponding extended library, and it also does not occupy the Mini-Program's package size. Usage is as follows:
{
"useExtendedLib": {
"kbone": true,
"weui": true
}
}
# darkmode
SDK version 2.35.1 officially supports DarkMode. Configuring "darkmode": true indicates that the current Mini-Program can adapt to DarkMode. All basic components will display different default styles based on the system theme, and the navigation bar and tab bar will also automatically switch based on the developer's configuration.
After configuration, complete the adaptation work beyond the basic styles yourself.
Currently, Android implementation is via color inversion. Please conduct thorough testing before use.
Specific performance: In dark mode, the styles of some basic library components differ from iOS, WXSS cannot use prefers-color-scheme, other functions are normal.
# themeLocation
Custom path for theme.json. When "darkmode":true is configured, this configuration file is required.
# referer
If referer is configured
Components video, image (Android only) and APIs request, download & uploadFile, loadFontFace, previewImage, previewMedia, getImageInfo will carry the configured referer when requesting http resources.
# permission
Mini-Program API permission related settings. The field type is Object, with the structure:
| Property | Type | Required | Default Value | Description |
|---|---|---|---|---|
| scope.userLocation | Object | No | Location-related permission declaration |
Supported scopes include:
- scope.userLocation
- scope.userLocationBackground
- scope.record
- scope.camera
- scope.bluetooth
- scope.writePhotosAlbum
- scope.addPhoneContact
- scope.addPhoneCalendar
- scope.userInfo
- scope.getPhoneNumber
Object Structure
| Property | Type | Required | Default Value | Description |
|---|---|---|---|---|
| desc | string | Yes | Description of the API's purpose displayed when the Mini-Program requests permission |
{
"permission": {
"scope.userLocation": {
"desc": "Location information will be used to display the effects of the Mini-Program's location interface"
}
}
}
# 2. Configuration Example
{
"pages": ["pages/index/index", "pages/logs/index"],
"window": {
"navigationBarTitleText": "Demo"
},
"tabBar": {
"list": [
{
"pagePath": "pages/index/index",
"text": "Home"
},
{
"pagePath": "pages/logs/logs",
"text": "Logs"
}
]
},
"debug": true,
}