Read the original article：Implementing Environment Switching in HarmonyOS ArkTS with Build Modes
Requirement Description
A HarmonyOS application needs to switch between different environments, such as development, staging, and production, without requiring manual code modifications.
Build Modes should inject environment-specific values (e.g., API_URL, ENABLE_LOGGING, ENABLE_ANALYTICS) so that ArkTS code automatically receives the correct configuration during build time.
Background Knowledge
DevEco Studio supports Build Modes (e.g., debug, stage, release) that can supply environment-specific variables through build-profile.json5.
These variables are compiled into BuildProfile and can be accessed directly in ArkTS code.
Key points:
- Build Modes belong to the project-level build-profile.json5
- Each Build Mode defines its own buildProfileFields
- During build, DevEco generates a BuildProfile file containing the resolved constants
- ArkTS code can read these constants at runtime without manual switching
This allows a clean and safe environment switching without maintaining separate projects or conditionals.
Implementation Steps
1.Define environment variables inside Build Modes
Inside project-level build-profile.json5:
"buildModeSet": [
{
"name": "debug",
"buildOption": {
"debuggable": true,
"arkOptions": {
"buildProfileFields": {
"API_URL": "dev.example.com",
"ENABLE_LOGGING": true,
"ENABLE_ANALYTICS": false
}
}
}
},
{
"name": "stage",
"buildOption": {
"debuggable": false,
"arkOptions": {
"buildProfileFields": {
"API_URL": "stage.example.com",
"ENABLE_LOGGING": true,
"ENABLE_ANALYTICS": true
}
}
}
},
{
"name": "release",
"buildOption": {
"debuggable": false,
"arkOptions": {
"buildProfileFields": {
"API_URL": "prod.example.com",
"ENABLE_LOGGING": false,
"ENABLE_ANALYTICS": true
}
}
}
}
]
Each Build Mode now contains different: API_URL,ENABLE_LOGGING, and ENABLE_ANALYTICS.
2.Ensure modules are linked to a product
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
}
]
This ensures all Build Modes apply correctly.
3.Build the project to generate BuildProfile
After selecting a Build Mode (debug, stage, release), and running a build, DevEco Studio generates BuildProfile.ets file:
entry/build/default/generated/profile/default/BuildProfile.ets
/**
* Use these variables when you tailor your ArkTS code. They must be of the const type.
*/
export const BUNDLE_NAME = 'com.example.myapplication';
export const BUNDLE_TYPE = 'app';
export const VERSION_CODE = 1000000;
export const VERSION_NAME = '1.0.0';
export const TARGET_NAME = 'default';
export const PRODUCT_NAME = 'default';
export const BUILD_MODE_NAME = 'stage';
export const DEBUG = false;
export const API_URL = 'stage.example.com';
export const ENABLE_LOGGING = true;
export const ENABLE_ANALYTICS = true;
/**
* BuildProfile Class is used only for compatibility purposes.
*/
export default class BuildProfile {
static readonly BUNDLE_NAME = BUNDLE_NAME;
static readonly BUNDLE_TYPE = BUNDLE_TYPE;
static readonly VERSION_CODE = VERSION_CODE;
static readonly VERSION_NAME = VERSION_NAME;
static readonly TARGET_NAME = TARGET_NAME;
static readonly PRODUCT_NAME = PRODUCT_NAME;
static readonly BUILD_MODE_NAME = BUILD_MODE_NAME;
static readonly DEBUG = DEBUG;
static readonly API_URL = API_URL;
static readonly ENABLE_LOGGING = ENABLE_LOGGING;
static readonly ENABLE_ANALYTICS = ENABLE_ANALYTICS;
}
Values in this file will change automatically depending on the selected Build Mode.
4.Access environment variables in ArkTS
In your component:
import BuildProfile from 'BuildProfile';
@Entry
@Component
struct Index {
@State apiUrl: string = BuildProfile.API_URL;
@State loggingEnabled: boolean = BuildProfile.ENABLE_LOGGING;
@State analyticsEnabled: boolean = BuildProfile.ENABLE_ANALYTICS;
aboutToAppear(): void {
console.log(`API_URL: ${this.apiUrl}`);
console.log(`ENABLE_LOGGING: ${this.loggingEnabled}`);
console.log(`ENABLE_ANALYTICS: ${this.analyticsEnabled}`);
}
build() {
//..
}
}
The displayed value will automatically match the Build Mode you selected.
Code Snippet / Configuration
Project-level build-profile.json5:
{
"app": {
"signingConfigs": [],
"products": [
{
"name": "default",
"signingConfig": "default",
"compatibleSdkVersion": "5.1.0(18)",
"runtimeOS": "HarmonyOS",
"buildOption": {
"strictMode": {
"caseSensitiveCheck": true,
"useNormalizedOHMUrl": true
}
}
}
],
"buildModeSet": [
{
"name": "debug",
"buildOption": {
"debuggable": true,
"arkOptions": {
"buildProfileFields": {
"API_URL": "dev.example.com",
"ENABLE_LOGGING": true,
"ENABLE_ANALYTICS": false
}
}
}
},
{
"name": "stage",
"buildOption": {
"debuggable": false,
"arkOptions": {
"buildProfileFields": {
"API_URL": "stage.example.com",
"ENABLE_LOGGING": true,
"ENABLE_ANALYTICS": true
}
}
}
},
{
"name": "release",
"buildOption": {
"debuggable": false,
"arkOptions": {
"buildProfileFields": {
"API_URL": "prod.example.com",
"ENABLE_LOGGING": false,
"ENABLE_ANALYTICS": true
}
}
}
}
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
}
]
}
ArkTS usage:
// import: the generated build-profile environment variables file
import BuildProfile from 'BuildProfile';
// usage: access as static readonly variable
console.log(BuildProfile.API_URL);
Test Results
- Switching Build Mode to debug logs: dev.example.com
- Switching to stage logs: stage.example.com
- Switching to release logs: prod.example.com
- No code changes required when switching environments
- BuildProfile regenerated correctly for each Build Mode selection and rebuilding.
Related Documents or Links
HarmonyOS Docs: Customizing a Build Mode
HarmonyOS Docs: Customizing a Build Mode Examples
Top comments (0)