We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
GuidesGetting StartedDevelopment FundamentalsApplication Configuration Files in Stage Modelapp.json5 Configuration File

app.json5 Configuration File

Last updated: 2026-06-02 07:02
Content overview

An application-level configuration file provides the global configuration of an application and configuration of a specific device type for the compilation tool, OS, and AppGallery. Each project must contain an app.json5 configuration file, which is stored in the project name/AppScope/app.json5 directory.

NOTE

Using the sample code in the actual project may cause a compilation failure. You need to configure the code as required. For example, if the resource file referenced by the $ symbol does not exist in the project, you need to manually add the resource file or replace it with the actual one.

In the configuration file, fields can be repeated. The last field is used.

Configuration File Example

The following example describes the structure and content of the app.json5 configuration file.

Collapse
Word wrap
Dark theme
Copy code
  1. {
  2.   "app": {
  3.     "bundleName": "com.application.myapplication",
  4.     "vendor": "example",
  5.     "versionCode": 1000000,
  6.     "versionName": "1.0.0",
  7.     "icon": "$media:layered_image",
  8.     "label": "$string:app_name",
  9.     "description": "$string:description_application",
  10.     "minAPIVersion": 9,
  11.     "targetAPIVersion": 9,
  12.     "debug": false,
  13.     "car": {
  14.       "minAPIVersion": 8
  15.     },
  16.     "appEnvironments": [
  17.       {
  18.         "name":"name1",
  19.         "value": "value1"
  20.       }
  21.     ],
  22.     "maxChildProcess": 5,
  23.     "multiAppMode": {
  24.       "multiAppModeType": "appClone",
  25.       "maxCount": 5
  26.     },
  27.     "hwasanEnabled": false,
  28.     "ubsanEnabled": false,
  29.     "cloudFileSyncEnabled": false,
  30.     "cloudStructuredDataSyncEnabled": false,
  31.     "configuration": "$profile:configuration",
  32.     "assetAccessGroups": [
  33.       "com.ohos.photos",
  34.       "com.ohos.screenshot",
  35.       "com.ohos.note"
  36.     ],
  37.     "startMode": "mainTask"
  38.   }
  39. }
app.json5

Tags in the Configuration File

As shown above, the app.json5 file contains several tags.

Table 1 Tags in the app.json5 file

Expand
Name Description Data Type Initial Value Allowed
bundleName

Bundle name, which uniquely identifies an application. The value must comply with the following rules:

- The bundle name contains at least three segments, separated by periods (.). Each segment can contain only letters, digits, and underscores (_).

- The first segment starts with a letter, and other segments start with a digit or letter. Each segment ends with a digit or letter.

- Consecutive periods (.) are not allowed.

- Contains 7 to 128 bytes.

You are advised to use the reverse domain name notation, for example, com.example.demo, where the first part is the domain suffix com, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.

 String No
bundleType

Bundle type. The options are as follows:

- app: The bundle is an application.

- atomicService: The bundle is an atomic service.

- shared: The bundle is a shared library application. This tag takes effect only for system applications. If this tag is set for a third-party application, the application cannot be installed.

- appService: The bundle is a system-level shared library application. This tag takes effect only for system applications.

- appPlugin: The bundle is the plugin package of an application. This tag is supported since API version 19.

 String Yes (initial value: app)
debug

Whether the application can be debugged.

- true: Can be debugged. Used in the development phase.

- false: Cannot be debugged. Used in the release phase.

 Boolean Generated by DevEco Studio during compilation and building. Yes (initial value: false)
icon Application icon. The value is the index to an icon resource file. Single-layer icons and layered icons can be configured. For details about the configuration rules and examples, see Configuring Layered Icons. String No
label Application name. The value is the index to a string resource with a maximum of 63 bytes, supporting multiple languages. For details, see Configuring Layered Icons. String No
description Description of an application. The value is a string of a maximum of 255 bytes, indicating the description string or the string resource index of the description. This tag can be used to display application information on, for example, the About page. String Yes (initial value: left empty)
vendor Vendor of the application. The value is a string with a maximum of 255 bytes. This tag can be used to display the vendor information on, for example, the About page. String Yes (initial value: left empty)
versionCode

Version number of an application. The value ranges from 0 to 2147483647. It is used only to determine whether a version is later than another version. A larger value indicates a later version.

Ensure that a new version of the application uses a value greater than any of its predecessors.

 Number No
versionName

Version number of the application displayed to users.

The value contains a maximum of 127 bytes and consists of only digits and dots. The four-part format A.B.C.D is recommended, wherein:

Part 1 (A): major version number. A major version consists of major new features or large changes.

Part 2 (B): minor version number. A minor version consists of some new features and large bug fixes.

Part 3 (C): feature version number. A feature version consists of scheduled new features.

Part 4 (D): patch version number. A patch version consists of some bug fixes.

 String No
minCompatibleVersionCode Minimum historical version compatible with the application. It is used for collaboration across devices, data migration, and cross-device compatibility determination. This tag is reserved and the value ranges from 0 to 2147483647. Number Yes (initial value: value of versionCode)
minAPIVersion Minimum SDK API version required for running an application. The value ranges from 0 to 2147483647. Number Yes (This tag is automatically generated during application build and cannot be manually configured. It corresponds to the compatibleSdkVersion tag in the project-level build-profile.json5 file.)
targetAPIVersion Target API version required for running the application. The value ranges from 0 to 2147483647. Number Yes (This tag is automatically generated during application build and cannot be manually configured. It corresponds to the targetSdkVersion tag in the project-level build-profile.json5 file. If the targetSdkVersion tag is not configured, this tag will be generated by compileSdkVersion.)
apiReleaseType

Type of the target API version required for running the application. The value can be "CanaryN", "BetaN", or "ReleaseN", where N represents a positive integer.

- Canary: indicates a restricted release.

- Beta: indicates a publicly released beta version.

- Release: indicates a publicly released official version.

 String Yes (This tag is automatically generated during application build and cannot be manually configured.)
accessible

Whether an application can access the installation directory. This field takes effect only for the preset system applications but not the third-party applications.

- true: The application installation directory is accessible.

- false: The application installation directory is not accessible.

 Boolean Yes (initial value: false)
multiProjects

Whether the application supports joint development of multiple projects.

- true: The application supports joint development of multiple projects. For details about multi-project development, see Implementing Multi-project Builds.

- false: The application does not support joint development of multiple projects.

 Boolean Yes (This tag is automatically generated during application build and cannot be manually configured. It corresponds to the multiProjects tag in the project-level build-profile.json5 file.)
asanEnabled

Whether to enable Address Sanitizer (ASan) to detect memory corruption issues such as buffer overflows.

- true: ASan is enabled.

- false: ASan is disabled.

 Boolean Yes (initial value: false)
tablet

Tablet-specific configuration, which includes the minAPIVersion attribute.

When running on tablets, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.

 Object Yes (initial value: general settings in the app.json5 file)
tv

TV-specific configuration, which includes the minAPIVersion attribute.

When running on TVs, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.

 Object Yes (initial value: general settings in the app.json5 file)
wearable

Wearable-specific configuration, which includes the minAPIVersion attribute.

When running on wearables, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.

 Object Yes (initial value: general settings in the app.json5 file)
car

Telematics–specific configuration, which includes the minAPIVersion attribute.

When running on telematics devices, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.

 Object Yes (initial value: general settings in the app.json5 file)
default

Default device–specific configuration, which includes the minAPIVersion attribute.

When running on default devices, the application applies the attribute settings under this tag and ignores the general settings in the app.json5 file.

 Object Yes (initial value: general settings in the app.json5 file)
targetBundleName Target bundle name. The value rule and range are the same as those of bundleName. When a value is specified, the target application becomes one with the overlay feature. String Yes (initial value: left empty)
targetPriority Priority of the application. The value ranges from 1 to 100. This tag can be configured only after the targetBundleName tag is configured. Number Yes (initial value: 1)
generateBuildHash

Whether to generate hash values for all HAP and HSP files of the application by using the packaging tool.

If this tag is set to true, the packaging tool generates hash values for all HAP and HSP files of the application. The hash values (if any) are used to determine whether the application needs to be updated when the system is updated in OTA mode but the versionCode value of the application remains unchanged.

- true: The packaging tool generates hash values for all HAPs and HSPs of the current application.

- false: The packaging tool does not generate hash values for all HAPs and HSPs of the current application.

NOTE

This tag takes effect only for pre-installed applications.

 Boolean Yes (initial value: false)
GWPAsanEnabled

Whether to enable GWP-ASan for detecting memory safety violations, including use-after-free and out-of-bounds memory read/write operations.

- true: The GWP-asan detection is enabled for the application.

- false: The GWP-asan detection is disabled for the application.

 Boolean Yes (initial value: false)
appEnvironments Application environment variables configured for the current application. Object array Yes (initial value: left empty)
maxChildProcess Maximum number of child processes that can be created by the current application. The value ranges from 0 to 512. The value 0 indicates that the number is not limited. If the application has multiple modules, use the configuration of the entry module. Number Yes (initial value: 512)
multiAppMode Multi-app mode of the application. This tag takes effect only for the entry or feature module of the application whose bundleType is app. If there are multiple modules, use the configuration of the entry module. Object Yes (initial value: left empty)
hwasanEnabled

Whether Hardware-assisted Address Sanitizer (HWASan) is enabled for an application. HWAsan is an enhanced Asan improved by the Top-Byte-Ignore feature. Compared with Asan, HWAsan has a lower memory overhead and a larger range of detection for memory errors.

- true: HWAsan is enabled.

- false: HWAsan is disabled.

NOTE

This tag is supported since API version 14.

 Boolean Yes (initial value: false)
ubsanEnabled

Whether UBsan detection is enabled for an application.

Undefined Behavior Sanitizer (UBsan) is a tool used to detect undefined behavior in applications during runtime. It aims to help you detect potential errors and vulnerabilities in code.

- true: UBsan is enabled.

- false: UBsan is disabled.

NOTE

This tag is supported since API version 14.

 Boolean Yes (initial value: false)
cloudFileSyncEnabled

Whether device-cloud file synchronization is enabled for the application.

- true: The device-cloud file synchronization is enabled.

- false: The device-cloud file synchronization is disabled.

 Boolean Yes (initial value: false)
cloudStructuredDataSyncEnabled

Whether device-cloud structured data synchronization is enabled for the application.

- true: The device-cloud structured data synchronization is enabled.

- false: The device-cloud structured data synchronization is disabled.

NOTE

This tag is supported since API version 20.

 Boolean Yes (initial value: false)
configuration

Whether the font size of the current application follows the system.

This tag is a profile file resource that used to specify the configuration file that describes the application font size changes with the system.

 String Yes (initial value: nonFollowSystem)
assetAccessGroups

Group ID of an application (configured by the developer), which forms group information with the Developer ID (allocated by AGC).

When HAP is packaged, DevEco Studio uses the developer certificate to sign the group information.

NOTE

This tag takes effect only in the main module (that is, the type field in module.json5 is set to entry).

This tag is supported since API version 18.

 String array Yes (initial value: left empty)
appPreloadPhase

The stage at which the application is preloaded. The options are as follows:

- processCreated: preload the application to the stage where process is created.

- abilityStageCreated: preload the application to the stage where AbilityStage is created.

- windowStageCreated: preload the application to the stage where WindowStage is created.

NOTE

This tag is supported since API version 20.

This tag takes effect only on the PCs/2-in-1 devices.

This field is valid only in the entry module of the application.

This tag only indicates whether the application is ready for preloading to the configured stage. Whether preloading can be performed is determined by the system based on user habits and other information.

 String Yes (If the value is not specified, preloading is not performed.)
startMode

Launch mode of the application. The options are as follows:

- mainTask: main task mode, indicating that the main UIAbility of the application is always started when the icon is tapped.

- recentTask: recent task mode, indicating that the most recently used UIAbility is started when the icon is tapped.

NOTE

This tag is supported since API version 20.

This field is valid only when launchType is set to singleton.

This tag is supported only on phones and tablets (excluding freeform windows).

 String Yes (initial value: mainTask)

appEnvironments

The appEnvironments tag represents the application environment variables. Running applications tend to depend on some third-party libraries that use custom environment variables. To avoid modifying the implementation logic of the third-party libraries, you can customize environment variables in the project configuration file for use during runtime.

Table 2 appEnvironments

Expand
Name Description Data Type Initial Value Allowed
name Name of the environment variable. The value is a string with a maximum of 4096 bytes. String Yes (initial value: left empty)
value Value of the environment variable. The value is a string with a maximum of 4096 bytes. String Yes (initial value: left empty)

Example of the appEnvironments structure:

Collapse
Word wrap
Dark theme
Copy code
  1. {
  2.   "app": {
  3.     // ...
  4.     "appEnvironments": [
  5.       {
  6.         "name":"name1",
  7.         "value": "value1"
  8.       }
  9.     ],
  10.     // ...
  11.   }
  12. }
app.json5

multiAppMode

The multiAppMode tag represents the multi-app mode of the application.

Table 3 multiAppMode

Expand
Name Description Data Type Initial Value Allowed
multiAppModeType

Multi-open mode. The options are as follows:

- multiInstance: multi-instance mode. This tag is supported only on 2-in-1 devices and does not apply to resident processes.

- appClone: app clone mode.

 String No
maxCount

Maximum number of applications that can be opened. The options are as follows:

- In multiInstance mode, the value ranges from 1 to 10.

- In appClone mode, the value ranges from 1 to 5.

 Number No

Example of the multiAppMode structure:

Collapse
Word wrap
Dark theme
Copy code
  1. {
  2.   "app": {
  3.     // ...
  4.     "multiAppMode": {
  5.       "multiAppModeType": "appClone",
  6.       "maxCount": 5
  7.     },
  8.     // ...
  9.   }
  10. }
app.json5

configuration

This tag corresponds to a profile resource, which is used to configure whether the font size of an application changes with the system.

Example of the configuration structure:

Collapse
Word wrap
Dark theme
Copy code
  1. {
  2.   "app": {
  3.     // ...
  4.     "configuration": "$profile:configuration",
  5.     // ...
  6.   }
  7. }
app.json5

Define the configuration.json file under AppScope/resources/base/profile in the development view. The file name (configuration in this example) can be customized, but must be consistent with the file specified by the configuration tag. The configuration file lists the attributes that enable the application font size to change with the system.

Table 4 configuration

Expand
Name Description Data Type Initial Value Allowed
fontSizeScale

Settings of the application font size. The options are as follows:

- followSystem: The font size follows the system.

- nonFollowSystem: The font size does not follow the system.

 String Yes (initial value: nonFollowSystem)
fontSizeMaxScale

Maximum ratio of the application font size after the font size is set to follow the system. The options are as follows: 1, 1.15, 1.3, 1.45, 1.75, 2, and 3.2.

For example, the value is set to 1.75 and the system font size is 10 fp, the application font size changes as follows:

(1) If the system font size is set to 1.5 times its original size in Settings, the application font size also changes to 15 fp, in line with the system.

(2) If the system font size is set to 2 times its original size in Settings, the system font size is 20 fp. However, the application font size is 17.5 fp because the maximum ratio of the application font size is set to 1.75.

NOTE

If fontSizeScale is set to nonFollowSystem, this attribute does not take effect.

 String Yes (initial value: 3.2)

Example of the configuration structure:

Collapse
Word wrap
Dark theme
Copy code
  1. {
  2.   "configuration": {
  3.     "fontSizeScale": "followSystem",
  4.     "fontSizeMaxScale": "3.2"
  5.   }
  6. }
Application Configuration Files (Stage Model)
module.json5 Configuration File
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice
Search in Guides
Enter a keyword.