tencent cloud

Global Configuration
Download PDF
Last updated: 2025-11-18 15:38:04
Global Configuration
Last updated: 2025-11-18 15:38:04
Download PDF
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 parameters:

Configuration item

attribute
type
required
description
string
no
Mini Program default start home page
pages
string[]
yes
Page Path List
window
Object
no
Global default window representation
tabBar
Object
no
bottom tab Column performance
debug
boolean
no
Whether or not to open debug mode, off by default
Object[]
no
Subpackage structure configuration
workers
string
no
Worker Directory for code placement
string[]
no
The list of mini programs to jump to, see wx.navigateToMiniProgram for details.
Object
no
Subpackage Predownload Rules
Object
no
Overall situation Custom Components configuration
Object
no
Small Program Interface Permissions Related Settings
darkmode
boolean
no
Mini program supports dark mode
string
no
Specify theme.json and dark mode true is required
boolean
no
Whether to disable the side swipe gesture to close the mini program. The default value is false.
string
no
Used for API version control (e.g., wx.login); if not configured, the latest version is called by default.

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 development directory is:
├── app.js
├── app.json
├── app.wxss
├── pages
│   │── index
│   │   ├── index.wxml
│   │   ├── index.js
│   │   ├── index.json
│   │   └── index.wxss
│   └── logs
│       ├── logs.wxml
│       └── logs.js
└── utils
You need to write in the 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.
attribute
type
default value
description
navigationBarBackgroundColor
HexColor
#000000
Navigation bar background color, such as #000000
navigationBarTextStyle
string
white
Navigation bar header color, support only black / white
navigationBarTitleText
string
-
Navigation Title Text Content
navigationStyle
string
default
Navigation bar style supports only the following values
default Default style, includes native navigation bar and capsule buttons.
custom Customize the navigation bar, leaving only the capsule on in the upper right corner. It does not take effect on the page where the web-view is located.
hide Hide the navigation bar and capsule buttons. It only hides the capsule buttons on the page where the web-view is located.
customV2 Customize the navigation bar, leaving only the capsule on in the upper right corner.
hideV2 Hide the navigation bar and capsule buttons.
See note 2, note 3.
backgroundColor
HexColor
#ffffff
The background color of the window
backgroundTextStyle
string
dark
Pull down loading Style, only supports dark / light
backgroundColorTop
string
#ffffff
The background color of the top window, only iOS Support
backgroundColorBottom
string
#ffffff
The background color of the bottom window, only iOS Support
enablePullDownRefresh
boolean
false
Whether to enable global drop-down refresh. See for details Page.onPullDownRefresh
onReachBottomDistance
number
50
The distance from the bottom of the page when the event is triggered, in px. See for details Page.onReachBottom
customNavigateBack
boolean
false
Whether or not you want to intercept the default return of the page (tabBar return or side-swipe or back key return) is used in conjunction with Page.onCustomBack.
pageOrientation
string
portrait
Screen rotation settings, support auto / portrait / landscape
Notes 1: HexColor (hexadecimal color value), such as "#ff00ff".
Notes 2: The minimum version requirements for customV2 and hideV2 in the navigationStyle valid values are as follows:
IDE
Base Library
iOS SDK
Android SDK
2.2.611
2.2.6
2.2.6
2.2.6
Note 3: The values and display scenarios of navigationStyle are as follows:
navigationStyle
Regular page
Page with 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.
attribute
type
required
default
description
color
HexColor
yes
-
tab Default color for text on, only hexadecimal color is supported
selectedColor
HexColor
yes
-
tab Supports hexadecimal colors only
backgroundColor
HexColor
yes
-
tab Supports only hexadecimal colors
borderStyle
string
no
black
Tabs The color of the top border, Support only black / white
list
array
yes
-
tab For a list of list Property explanation, number of the tab： minimum 2 maximum 5
position
string
no
bottom
tabBar Only supports the location of bottom / top
custom
boolean
no
false
custom Tab Bar, see the Custom tabBar
When a list accepts an array, 2 to 5 tabs can be configured. The tabs are sorted in the order of the array, and each of them is an object with the following parameters:
attribute
type
required
introduction
pagePath
string
yes
Page path, must be in the pages first definition
text
string
yes
Text on the tab button
iconPath
string
no
Picture path, icon size limit is 40kb, recommended size 81px * 81px, does not support web pictures.
When the position is set top, does not display the icon.
selectedIconPath
string
no
Selected picture path, icon size limit is 40kb, recommended size 81px * 81px, does not support web pictures.
When the position is set top, does not display the icon.


debug

You can enable the debug mode in the developer tool. 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.
When the mini program needs to call the API to redirect to other mini programs, it is necessary to declare the list of up to 10 appId in the configuration file.

preloadRule

Declare 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 will be considered dependencies for all pages and will be initialized when any page starts, affecting the startup performance and occupying 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:
attribute
type
required
default
description
scope.userLocation
PermissionObject
no
-
Location-dependent permission statement
Permission Object structure
attribute
type
Required
Default
Introduction
desc
string
yes
-
Description of the Chinese usage of the interface displayed by the mini program when obtaining permissions. Maximum 80 characters
desc-en
string
no
-
Description of the English usage of the interface displayed by the mini program when obtaining permissions. Maximum 80 characters
desc-ar
string
no
-
A description of the Arabic usage of the interface displayed when the mini program gets permissions. Maximum 80 characters
Such as:
{
  "pages": ["pages/index/index"],
  "permission": {
    "scope.userLocation": {
      "desc": "Your location information will be used to display the effects of the Mini Program location interface." // Continuous Background Positioning for Freeway Driving
    }
  }
}

scope list

scope
API
Description
scope.userInfo
wx.getUserInfo
User information
scope.userLocation
wx.getLocation
Get location information
scope.userFuzzyLocation
wx.getFuzzyLocation
Get fuzzy location information
scope.record
live-pusher component or wx.startRecord
live-pusher component or wx.startRecord
scope.camera
camera component
camera component
scope.addPhoneCalendar
wx.addPhoneCalendar
Add Calendar
scope.writePhotosAlbum
wx.saveImageToPhotosAlbum
Save Image to Photos Album
scope.bluetooth
wx.openBluetoothAdapter
Bluetooth
scope.chooseMessageFile
wx.chooseMessageFile
wx.chooseExternalFile
Select a file from the client session
Select files from the file selector on your phone
scope.getPhoneNumber
button component: open-type="getPhoneNumber"
Get phone number
scope.getEmail
button component: open-type="getEmailAddress"
Get email address
scope.chooseImage
wx.chooseImage
Select images from the local photo album or take photos using the camera
scope.chooseVideo
wx.chooseVideo
Captures a video or selects a video from the phone's album
scope.chooseMedia
wx.chooseMedia
Captures or selects images or videos from the mobile phone's album

darkmode

By setting "darkmode" to 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. This configuration file is required when "darkmode": true is set.

disableSlideCloseGesture

Whether to disable the side swipe gesture to close the applet. The default value is false.

apiVersion

Used for API version control (e.g., wx.login); if not configured, the latest version is called by default.
{
  "apiVersion": "v1"
}

Configuration example

{
  "pages": ["pages/index/index", "pages/logs/index"],
  "window": {
    "navigationBarTitleText": "Demo"
  },
  "tabBar": {
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "index"
      },
      {
        "pagePath": "pages/logs/logs",
        "text": "logs"
      }
    ]
  },
  "debug": true
}

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback