---
title: app.json Global Configuration
---
# app.json Global Configuration
The `app.json` file in the root directory is used to perform a global configuration of the miniapp. This file determines the path of the page file and the window performance, sets up the network timeout and multiple tabs, and many more.
The following code snippet shows a basic configuration example:
```json
{
"themeLocation": "theme.json",
"pages": ["pages/page1/index", "pages/page2/index"],
"window": {
"navigationBarBackgroundColor": "#ffffff"
}
}
```
The table lists all the configuration items:
| Property | Type | Required | Description | Base Library |
| --------------- | -------------------------------------- | -------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| entryPagePath | string | No | The default splash page of a specified miniapp. | |
| pages | Array | Yes | Set the path of a specified page. | |
| window | Object | No | Set the window performance of a specified miniapp. | |
| darkmode | boolean \| 'auto' \| 'dark' \| 'light' | No | Theme configuration, default value: true | Boolean configuration supported since 2.14.0, string configuration supported since 2.22.0 |
| themeLocation | string | No | Relative path to the theme configuration file. | |
| tabBar | Object | No | Set the performance of the bottom `tabBar`. | |
| usingComponents | Object | No | Define a global custom component. | |
| usingPlugins | Array | No | Define global plug-ins. | 2.18.0 |
### entryPagePath
Specify the default startup path (homepage) of the miniapp, which must be one of the items in `pages`. If left empty, it will default to the first item in the list of `pages`. A page path parameter is unsupported.
### pages
Specify the pages that compose a miniapp. Each item corresponds to the path (excluding file suffix) information of a page. The framework will automatically load files with the same name, including `.json`, `.js`, `.tyml`, and `.tyss`. Undeclared page files will not be packaged into the miniapp application.
When `entryPagePath` is not specified, the first item of the array represents the initial page (homepage) of the miniapp.
To add or remove pages, you need to modify the `pages` array.
For example, the development directory looks like this:
```
├── pages
│ ├──index
│ │ ├── index.json
│ │ ├── index.js
│ │ ├── index.tyml
│ │ └── index.tyss
│ └──logs
│ ├── logs.json
│ ├── logs.js
│ └── logs.tyml
├── app.json
├── app.js
└── app.tyss
```
`app.json` should be configured as follows:
```json
{
"pages": ["pages/index/index", "pages/logs/logs"]
}
```
> The path in the configuration does not need to be prefixed with `/`. The default path is based on the directory where the current configuration file (`app.json`) is located.
### window
Set the status bar, navigation bar, title, and window background color of the miniapp.
| Property | Type | Default value | Description |
| ---------------------------- | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| backgroundColor | HexColor | #ffffff | The background color of a specified window. |
| backgroundColorBottom | string | #ffffff | The background color of the bottom window, only available on iOS. |
| backgroundColorTop | string | #ffffff | The background color of the top window, only available on iOS. |
| backgroundTextStyle | string | dark | The style of drop-down loading. Valid values: `dark` and `light`. |
| custom | Boolean | false | The custom navigation bar. Only keep the pill button in the top right corner. |
| enablePullDownRefresh | boolean | false | Specifies whether to enable global drop-down refresh. |
| navigationBarBackgroundColor | HexColor | #ffffff | The background color of the navigation bar. For example, #000000. |
| navigationBarTextStyle | string | black | The color of the navigation bar title. Valid values: `black` and `white`. |
| navigationBarTitleText | string | | The text content of the navigation bar title. |
| navigationStyle | string | default | `default`: the default style.
`custom`: the custom navigation bar. Only keep the pill button in the top right corner. |
| hideMenuButton | boolean | false | Whether to hide the upper right capsule button |
| onReachBottomDistance | number | 50 | The distance from the bottom of the page when the page is pulled up and reaches the bottom, in px. |
| boardMenus | array[] | | The custom menu configuration. The container version is v2.3.0 or later. |
| pageOrientation | string | portrait | The screen orientation. Valid values:
`portrait`: portrait screen. Default value.
`landscape`: landscape screen.
`auto`: automatic rotation. |
You can configure the theme variables by using `navigationBarBackgroundColor`, `navigationBarTextStyle`, `backgroundColor`, `backgroundTextStyle`, `backgroundColorTop`, and `backgroundColorBottom`. After the theme configuration file `themeLocation` is set, you can use the variables declared in the file.
Example:
```json
{
"window": {
"navigationBarBackgroundColor": "#ffffff",
"navigationBarTextStyle": "black",
"navigationBarTitleText": "API function demonstration",
"backgroundColor": "@bgColor",
"backgroundTextStyle": "light",
"disableScroll": true
}
}
```
#### boardMenus
Customize the menu items.
- `key`: The unique key value of a menu item.
- `text`: The title of the menu item. M.ultilingual settings are supported.
- `iconPath`: The icon path of the menu item. Network images are unsupported. You can configure the theme variables.
```json
{
"window": {
"boardMenus": [
{
"key": "home",
"iconPath": "@iconPath1",
"text": "v1"
},
{
"key": "share",
"iconPath": "@selectedIconPath1",
"text": "tab1"
},
{
"key": "share",
"iconPath": "/assets/images/tab/component_selected.png",
"text": "@I18n.t('tab2')"
}
]
}
}
```
### tabBar
For a miniapp with multiple tabs, you can navigate between the pages by using a tab bar at the bottom or top of the client window. In this case, you can use the `tabBar` configuration item to specify the performance of the tab bar and the page displayed during navigation.
| Property | Type | Required | Description | Description |
| --------------- | -------- | -------- | ----------- | ------------------------------------------------------------------------------------------ |
| color | HexColor | Yes | | The default color of text on tabs. Only hexadecimal colors are supported. |
| selectedColor | HexColor | Yes | | The text color on an active tab. Only hexadecimal colors are supported. |
| backgroundColor | HexColor | Yes | | The background color of a tab. Only hexadecimal colors are supported. |
| borderStyle | string | No | black | The border color of a tabbar . Valid values: `black` and `white`. |
| list | Array | Yes | | The list of 2 to 5 tabs. For more information, see the description of the list properties. |
| custom | Boolean | No | false | use custom tab |
You can configure the theme variables by using `color`, `selectedColor`, `backgroundColor`, and `borderStyle`. After the theme configuration file `themeLocation` is set, you can use the variables declared in the file.
The list can be an array of 2 to 5 tabs. The tabs are sorted in the order of the array, and each item is an object with the following property values:
| Property | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| pagePath | string | Yes | The page path, which must be defined first in the pages. |
| text | string | Yes | The button text on a tab. |
| iconPath | string | No | The path of an image. The icon size is limited to 40 KB, and the recommended dimensions are `81×81` pixels. Network images are not supported. |
| selectedIconPath | string | No | The path of a selected image. The icon size is limited to 40 KB, and the recommended dimensions are `81×81` pixels. Network images are not supported. |
You can configure the theme variables by using `selectedIconPath` and `iconPath`. After the theme configuration file `themeLocation` is set, you can use the variables declared in the file.
### darkmode
> If there are no special requirements, it is recommended to follow the app theme color to implement the light and dark modes of the miniapp, rather than controlling the theme through `darkmode`.
Whether to support dark mode. The default value is `true`. When set to `false`, the mini-program does not support dark mode and will not trigger the `onThemeChange` event.
Starting from **MiniApp Base Library 2.22.0** and **App Baseline 6.0.0**, three modes `auto`, `dark`, and `light` are supported:
- In `auto` mode, the MiniApp will automatically switch themes based on system settings, which is equivalent to the previous `true` configuration.
- In `light` mode, the MiniApp will forcibly use the light mode, meaning the MiniApp's own capsule and the obtained App theme color variables such as `--app-B1` will always use the App's light color scheme.
- In `dark` mode, the MiniApp will forcibly use the dark mode, meaning the MiniApp's own capsule and the obtained App theme color variables such as `--app-B1` will always use the App's dark color scheme.
The CSS selector `@media (prefers-color-scheme: dark)` is not affected and will still take effect.
The `:root[theme='dark']` selector only takes effect when `darkmode` is set to `true`, `dark`, or `auto`.
### themeLocation
After the `themeLocation` is set, the theme configuration is supported automatically. Use relative paths to `app.json` and define the theme variables such as `light` and `dark`. It can be used in fields supported by `window` and `tabBar`.
```json
{
"themeLocation": "./theme.json"
}
```
Format:
```json
{
"light": {
"bgColor": "#ffffff"
},
"dark": {
"bgColor": "#1f1f1f"
}
}
```
After a theme field variable is declared, it can be applied to the `app.json` configuration by splicing the `@` symbol.
### usingComponents
Declare a global custom component. When a component is referenced by multiple pages, you can use a global declaration to avoid repeated declarations in the configuration of each page. The supported component path is as follows:
1. An absolute path, starting with `/`, indicating the source code directory of the miniapp.
2. A relative path, starting with `.` , based on the directory where the current JSON file is located.
3. npm third-party packages.
```json
{
"usingComponents": {
"foo": "/absolute/foo/index", // Absolute path
"foo": "./relative/foo/index", // Relative path
"foo": "package/es/foo/index" // npm package
}
}
```
`Note`: The path address must be accurate to the file name, and the default index cannot be omitted.
### usingPlugins
```json
{
"usingPlugins": ["rjs://echarts"]
}
```
Declare global plug-ins. For details, please see [Plugin System](/en/miniapp/develop/miniapp/framework/plugin/intro)
### subPackages
Configure mini program subpackage loading. For detailed information, see [Subpackage Loading](/en/miniapp/develop/miniapp/guide/ability/sub-packages).