Global Configuration

Last updated:2025-12-31 18:53:21

Global Configuration

Last updated: 2025-12-31 18:53:21

The app.json file in the root directory of the mini program is used for global configuration of the mini program. The file content is a JSON object with the following properties:
Configuration items
Property
Type
‍Required
Description
﻿entryPagePath﻿
string
False
The default startup page of the mini program.
﻿pages﻿
string[]
True
List of page paths.
﻿window﻿
Object
False
Default global window appearance.
﻿tabBar﻿
Object
False
Tab bar appearance.
﻿debug﻿
boolean
False
Whether to enable the debug mode (Disabled by default).
﻿subpackages﻿
Object[]
False
Subpackage structure configuration.
﻿workers﻿
string
False
Directory where worker code is placed.
﻿navigateToMiniProgramAppIdList﻿
string[]
False
The list of mini programs to navigate to. For details, see  wx.navigateToMiniProgram﻿
﻿preloadRule﻿
Object
False
Subpackage pre-download rules.
﻿usingComponents﻿
Object
False
Global Custom Component configuration.
﻿permission﻿
Object
False
Mini program API permission settings.
﻿darkmode﻿
boolean
False
Mini program supports dark mode.
﻿themeLocation﻿
string
False
Specifies the location of  theme.json . Required when darkmode is true.
﻿disableSlideCloseGesture﻿
boolean
False
Whether to disable the slide-to-close gesture for the mini program. Default is false.
﻿apiVersion﻿
string
False
Used for API (e.g., wx.login) version control. Defaults to the latest version if not configured.
entryPagePath
Specifies the default startup path (homepage) of the mini program. If left blank, it will default to the first item in the pages list. Page path parameters are not supported.
{
  "entryPagePath": "pages/index/index"
}
pages
Specifies the pages that make up the mini-program, with each item corresponding to the path (including the filename) of a page. No need to include file extensions; the framework will automatically find and process the .json, .js, .wxml, and .wxss files.
If entryPagePath is not specified, the first item in the array represents the initial page (home page) of the mini-program.
To add/remove pages in the mini program, you need to modify the pages array.
For example, if the directory is as follows:
├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils
Write the following in app.json:
{
  "pages": ["pages/index/index", "pages/logs/logs"]
}
window
Sets the status bar, navigation bar, title, and window background color of the mini-program.
Property
Type
Default value
Description
navigationBarBackgroundColor
HexColor
#000000
Sets the background color of the navigation bar, for example, #000000
navigationBarTextStyle
string
white
Sets the navigation bar title and status bar color, supporting black and white.
navigationBarTitleText
string
-
Sets the navigation bar title text.
navigationStyle
string
default
Sets the navigation bar style:
default:  default style, including the native navigation bar and capsule button.
custom:  a custom navigation bar that only keeps the capsule button in the top right corner. This doesn’t take effect on pages containing a web-view .
hide:  hides both the navigation bar and the capsule button. On pages containing a web-view , only the capsule button is hidden.
customV2:  a custom navigation bar that only keeps the capsule button in the top right corner.
hideV2:  hides both the navigation bar and the capsule button.
Refer to Note 2 and Note 3 right after the table.
backgroundColor
HexColor
#ffffff
Sets the window background color.
backgroundTextStyle
string
dark
The pull-down loading style only supports dark or light.
backgroundColorTop
string
#ffffff
Top window background color, supported only on iOS.
backgroundColorBottom
string
#ffffff
Bottom window background color, supported only on iOS.
enablePullDownRefresh
boolean
false
Whether to enable pull-down refresh.
For details, see  Page.onPullDownRefresh﻿
onReachBottomDistance
number
50
The distance (in px) from the bottom of the page when the pull-to-refresh event is triggered.
For details, see  Page.onReachBottom﻿
customNavigateBack
Boolean
false
Whether to intercept the default page back action (such as clicking the tabBar back button, swiping, or pressing the back key) in conjunction with Page.onCustomBack.
pageOrientation
string
portrait
Screen rotation settings support auto, portrait, and landscape modes.
For details, see  Respond to changes in display area﻿
Note 1: HexColor (hexadecimal color value), such as "#ff00ff".
Note 2: For the valid values of navigationStyle, the minimum version requirements for  customV2  and  hideV2  are as follows:
IDE
Base library
SDK for iOS
SDK for Android
2.2.611
2.2.6
2.2.6
2.2.6
Note 3: The values and display effects of navigationStyle are as follows:
navigationStyle
Regular page
Page containing a web-view
default
﻿
﻿
﻿
﻿
custom
﻿
﻿
﻿
hide
﻿
﻿
﻿
﻿
customV2
﻿
﻿
﻿
﻿
hideV2
﻿
﻿
﻿
﻿
﻿
tabBar
If the mini program is a multi-tab app (with a tab bar at the bottom or top of the client window for switching pages), you can use the tabBar configuration to define its appearance and the pages shown when tabs are switched.
Property
Type
‍Required
Default value
Description
color
HexColor
True
-
The default color of the text on the tab. Only hexadecimal colors are supported.
selectedColor
HexColor
True
-
The color of the texts on the tab when they are selected. Only hexadecimal colors are supported.
backgroundColor
HexColor
True
-
The background color of the tab. Only hexadecimal colors are supported.
borderStyle
string
False
black
The color of the top border on the tabBar can only be set to black or white.
list
Array
True
-
The list of tabs. For details, see the description of the list attribute. A maximum of 5 tabs and a minimum of 2 tabs are allowed.
position
string
False
bottom
The position of tabBar can only be set to bottom or top.
custom
boolean
False
false
Customizes the tab bar. For details, see  Custom TabBar﻿
The list can be configured as an array, which allows a maximum of 5 tabs and a minimum of 2 tabs. The tabs are sorted in the order of the array, and each of them is an object with the following parameters:
Property
Type
‍Required
Description
pagePath
string
True
Page path, which must be defined in pages first.
text
string
True
Button text on the tab.
iconPath
string
False
Image path. The upper limit of the icon size is 40 KB, and the recommended pixel size is 81 px × 81 px. Network images are not supported.
When position is set to top, the icon is not displayed.
selectedIconPath
string
False
The image path when the icon is selected. The upper limit of the icon size is 40 KB, and the recommended pixel size is 81 px × 81 px. Network images are not supported.
When position is set to top, the icon is not displayed.
﻿
debug
You can enable the  debug  mode in the IDE. In the console panel, debug information will be provided as  info , including details on page registration, page routing, data updates, and event triggers. It helps developers quickly troubleshoot some common problems.
subpackages
When enabling  subpackage loading , declare the project's subpackage structure.
Note:
SubPackages is also supported.
workers
Specifies the directory for placing Worker code when using  Worker  to handle multi-threaded tasks.
navigateToMiniProgramAppIdList
When the mini program needs to call the  navigateToMiniProgram  to redirect to other mini programs, it is necessary to declare the list of up to 10 appids in the configuration file.
preloadRule
Declares the rules for  Subpackage pre-download .
usingComponents
Custom components declared in  app.json  are considered global custom components and can be used directly in pages or custom components within the mini program without further declaration. It is recommended to only declare custom components that are used by almost all pages.
Note:
Global custom components are treated as dependencies for all pages and will be initialized on every page load, which can impact startup performance and increase the main package size. Custom components that are only used by specific pages or sub-packages should be declared in the page configuration whenever possible.
permission
Mini program API permission settings. The field type is  Object. Its structure is as follows:
Property
Type
‍Required
Default value
Description
scope.userLocation
PermissionObject
False
-
Declaration of location-related permissions.
PermissionObject structure
Property
Type
‍Required
Default value
Description
desc
string
True
-
The description of the API displayed when requesting permissions in the mini program (in Chinese). Max 80 characters.
desc-en
string
False
-
The description of the API displayed when requesting permissions in the mini program (in English). Max 80 characters.
desc-ar
string
False
-
The description of the API displayed when requesting permissions in the mini program (in Arabic). Max 80 characters.
Example:
{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "The mini program will display the location API based on your location information" // Continuous location tracking in the backend during highway driving
    }
  }
}
Scope list
scope
APIs
Description
scope.userInfo
wx.getUserInfo
User information.
scope.userLocation
wx.getLocation
Gets geographic location information.
scope.userFuzzyLocation
wx.getFuzzyLocation
Gets approximate geographic location information.
scope.record
live-pusher component or wx.startRecord
Live streaming or recording.
scope.camera
Camera component
Camera component.
scope.addPhoneCalendar
wx.addPhoneCalendar
Adds logs.
scope.writePhotosAlbum
wx.saveImageToPhotosAlbum
Saves images to an album.
scope.bluetooth
wx.openBluetoothAdapter
Bluetooth.
scope.chooseMessageFile
wx.chooseMessageFile
wx.chooseExternalFile
Selects a file from the client session.
Selects a file from the mobile file picker. 
scope.getPhoneNumber
button component open-type="getPhoneNumber"
Gets the phone number.
scope.getEmail
button component open-type="getEmailAddress"
Gets the email address.
scope.chooseImage
wx.chooseImage
Selects images from the local photo album or take photos using the camera.
scope.chooseVideo
wx.chooseVideo
Records a video or selects a video from the phone's album.
scope.chooseMedia
wx.chooseMedia
Captures or selects images or videos from the phone's album.
darkmode
By setting "darkmode": true, you can enable dark mode in the mini program. All basic components will display different default styles according to the system theme, and the navigation bar and tab bar will also automatically switch according to the developer's configuration.
Please follow the  DarkMode Adaptation Guide  for further styling adjustments.
{
  "darkmode": true
}
themeLocation
The path to the custom  theme.json  file. It is required when  "darkmode":true  is set.
disableSlideCloseGesture
Whether to disable the slide-to-close gesture for the mini program. Default is false.
apiVersion
Used for API (e.g., wx.login) version control. Defaults to the latest version if not configured.
{
  "apiVersion": "v1"
}
Example
{
  "pages": ["pages/index/index", "pages/logs/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "Homepage"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "Log"
      }
    ]
  },
  "debug": true
}
﻿

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Feedback

Property	Type	‍Required	Description
entryPagePath	string	False	The default startup page of the mini program.
pages	string[]	True	List of page paths.
window	Object	False	Default global window appearance.
tabBar	Object	False	Tab bar appearance.
debug	boolean	False	Whether to enable the debug mode (Disabled by default).
subpackages	Object[]	False	Subpackage structure configuration.
workers	string	False	Directory where worker code is placed.
navigateToMiniProgramAppIdList	string[]	False	The list of mini programs to navigate to. For details, see wx.navigateToMiniProgram
preloadRule	Object	False	Subpackage pre-download rules.
usingComponents	Object	False	Global Custom Component configuration.
permission	Object	False	Mini program API permission settings.
darkmode	boolean	False	Mini program supports dark mode.
themeLocation	string	False	Specifies the location of theme.json . Required when darkmode is true.
disableSlideCloseGesture	boolean	False	Whether to disable the slide-to-close gesture for the mini program. Default is false.
apiVersion	string	False	Used for API (e.g., wx.login) version control. Defaults to the latest version if not configured.

Property	Type	Default value	Description
navigationBarBackgroundColor	HexColor	#000000	Sets the background color of the navigation bar, for example, #000000
navigationBarTextStyle	string	white	Sets the navigation bar title and status bar color, supporting black and white.
navigationBarTitleText	string	-	Sets the navigation bar title text.
navigationStyle	string	default	Sets the navigation bar style: default: default style, including the native navigation bar and capsule button. custom: a custom navigation bar that only keeps the capsule button in the top right corner. This doesn’t take effect on pages containing a web-view . hide: hides both the navigation bar and the capsule button. On pages containing a web-view , only the capsule button is hidden. customV2: a custom navigation bar that only keeps the capsule button in the top right corner. hideV2: hides both the navigation bar and the capsule button. Refer to Note 2 and Note 3 right after the table.
backgroundColor	HexColor	#ffffff	Sets the window background color.
backgroundTextStyle	string	dark	The pull-down loading style only supports dark or light.
backgroundColorTop	string	#ffffff	Top window background color, supported only on iOS.
backgroundColorBottom	string	#ffffff	Bottom window background color, supported only on iOS.
enablePullDownRefresh	boolean	false	Whether to enable pull-down refresh. For details, see Page.onPullDownRefresh
onReachBottomDistance	number	50	The distance (in px) from the bottom of the page when the pull-to-refresh event is triggered. For details, see Page.onReachBottom
customNavigateBack	Boolean	false	Whether to intercept the default page back action (such as clicking the tabBar back button, swiping, or pressing the back key) in conjunction with Page.onCustomBack.
pageOrientation	string	portrait	Screen rotation settings support auto, portrait, and landscape modes. For details, see Respond to changes in display area

IDE	Base library	SDK for iOS	SDK for Android
2.2.611	2.2.6	2.2.6	2.2.6

navigationStyle	Regular page	Page containing a web-view
default
custom
hide
customV2
hideV2

scope	APIs	Description
scope.userInfo	wx.getUserInfo	User information.
scope.userLocation	wx.getLocation	Gets geographic location information.
scope.userFuzzyLocation	wx.getFuzzyLocation	Gets approximate geographic location information.
scope.record	live-pusher component or wx.startRecord	Live streaming or recording.
scope.camera	Camera component	Camera component.
scope.addPhoneCalendar	wx.addPhoneCalendar	Adds logs.
scope.writePhotosAlbum	wx.saveImageToPhotosAlbum	Saves images to an album.
scope.bluetooth	wx.openBluetoothAdapter	Bluetooth.
scope.chooseMessageFile	wx.chooseMessageFile wx.chooseExternalFile	Selects a file from the client session. Selects a file from the mobile file picker.
scope.getPhoneNumber	button component open-type="getPhoneNumber"	Gets the phone number.
scope.getEmail	button component open-type="getEmailAddress"	Gets the email address.
scope.chooseImage	wx.chooseImage	Selects images from the local photo album or take photos using the camera.
scope.chooseVideo	wx.chooseVideo	Records a video or selects a video from the phone's album.
scope.chooseMedia	wx.chooseMedia	Captures or selects images or videos from the phone's album.

tencent cloud

Configuration items

entryPagePath

pages

window

tabBar

debug

subpackages

workers

navigateToMiniProgramAppIdList

preloadRule

usingComponents

permission

PermissionObject structure

Scope list

darkmode

themeLocation

disableSlideCloseGesture

apiVersion

Example