Multi Target Product Build in HarmonyOS

Read the original article：Multi Target Product Build in HarmonyOS

Context

Modern mobile apps often need multiple build variants—such as free and premium—from the same codebase. HarmonyOS supports this through a native multi-target system, similar to Android’s product flavors.

Description

HarmonyOS uses a build-profile-based configuration to define and manage multiple app variants (targets) from a single codebase.

• Variants can have different bundleName, icons, signing configs, and feature flags.
• Configuration is done using build-profile.json5 files at both the project and module levels.
• Logic in your ArkTS code can access these build flags at runtime using BuildProfile.

Solution

1.Project-Level Configuration (build-profile.json5)

{
    "app": {
        "products": [{ "name": "default", "signingConfig": "default", "runtimeOS": "HarmonyOS" }]
    },
    "modules": [{
        "name": "entry",
        "srcPath": "./entry",
        "targets": [
            { "name": "free", "applyToProducts": ["default"] },
            { "name": "paid", "applyToProducts": ["default"] }
        ]
    }]
}

2. Module-Level Configuration (entry/build-profile.json5)

{
    "apiType": "stageMode",
    "buildOptionSet": [
        {
            "name": "free",
            "arkOptions": { "buildProfileFields": { "IS_PREMIUM": "false" } }
        },
        {
            "name": "paid",
            "arkOptions": { "buildProfileFields": { "IS_PREMIUM": "true" } }
        }
    ],
    "targets": [
        { "name": "free" },
        { "name": "paid" }
    ]
}

3. Use in ArkTS Code

import BuildProfile from 'BuildProfile';

if (BuildProfile.IS_PREMIUM === "true") {
    // Premium features
} else {
    // Free version features
}

Key Takeaways

• HarmonyOS natively supports multi-target builds using build-profile.json5.
• Targets are cleanly defined and linked to products for easy switching.
• You can inject build-time constants like IS_PREMIUM for feature gating.
• This setup improves scalability, security, and automation in app development.

Addional Resources

https://developer.huawei.com/consumer/en/doc/best-practices/bpta-multi-target

Written by Ahmet Furkan Sevim