DEV Community

HarmonyOS
HarmonyOS

Posted on

Rules for integrating multiple HAP packages into the same HSP

#harmonyos #versioncodealignment #integratedhsp #codereuse

Read the original article：Rules for integrating multiple HAP packages into the same HSP

Context

In software engineering, code reuse is common. In complex business scenarios, functionality is often modularized, with shared capabilities abstracted into a common framework or module. When multiple applications (HAPs) need to share the same code and resources, using a shared module like HSP (HarmonyOS Shared Package) enables efficient reuse across multiple HAPs without duplicating code or resources during compilation. However, challenges arise when integrating HSPs across different projects — particularly around bundleName, versionCode, and minAPIVersion alignment. While HAR can be used for sharing, it leads to code duplication and increased app size. HSPs, especially in integrated mode, are the recommended solution for multiple HAPs within the same organization to share code and resources efficiently, as they are compiled only once and loaded at runtime on demand.

Description

When multiple HAPs (HarmonyOS Application Packages) need to share common code or resources, using an integrated HSP allows these components to be bundled and reused across different applications without inflating the overall app size. Unlike HAR, which duplicates code in each HAP, an integrated HSP is compiled once and shared at runtime. However, the versionCode and minAPIVersion must be synchronized between the HSP and all dependent HAPs. The bundleName of the HSP does not need to match the HAPs, thanks to automatic renaming and re-signing by the toolchain during build — the integrated HSP’s bundleName is dynamically replaced with the host HAP’s bundleName, enabling loose coupling. This decouples the HSP from the host application’s identity while maintaining compatibility. Misalignment in versionCode or minAPIVersion between HSP and HAPs leads to installation errors (e.g., error code 10024), which are common when developers overlook version synchronization.

HAR Usage Scenarios:

  • Supports sharing within the application and can be used by other applications after publishing.
  • As a second-party library, published to the OHPM private repository for use by other applications within the company.
  • As a third-party library, published to the OHPM central repository for use by other applications.
  • When multiple packages (HAP/HSP) reference the same HAR, it can cause redundant copying of code and resources between packages, leading to application package bloat.

HSP Usage Scenarios:

  • Code and resources shared by multiple HAP/HSPs are placed in the same HSP, which can improve code and resource reusability and maintainability. During compilation and packaging, only one copy of the HSP code and resources is retained, effectively controlling the size of the application package.
  • HSPs are loaded on-demand at runtime, which helps improve application performance.
  • Within the same organization, multiple applications can use integrated HSPs to achieve code and resource sharing.

Solution / Approach

To enable seamless code and resource sharing across multiple HAPs:

  • Convert the shared module into an integrated HSP.
  • Ensure the versionCode and minAPIVersion of the HSP are identical to those of the host HAP.
  • Use the HarmonyOS toolchain to automatically rename and re-sign the HSP to match the host application’s bundleName during packaging.
  • Maintain version alignment manually between the HSP and all dependent HAPs: if the HSP’s versionCode or minAPIVersion changes, update all dependent HAPs accordingly.
  • Integrated HSPs are ideal for internal enterprise applications and enable runtime loading, reducing APK size and improving maintainability.

To achieve code and resource sharing between different projects, an integrated HSP should be used. The build artifacts of the projects that need to be reused can be changed to an integrated HSP to solve the strong coupling issue of bundleName between the business project and the base project. However, the versionCode and minAPIVersion fields still need to be manually planned in advance to ensure consistency between these fields in the two projects.

  • Plan the version number and minimum API version to ensure that the versionCode and minAPIVersion fields are consistent across multiple project builds.
  • Use an integrated HSP to decouple the bundleName field.

For subsequent evolution, please refer to the following scenarios:

Scenario One: The business project does not involve changes, but the base project needs to evolve (enhance functionality/fix bugs). Only the versionCode and minAPIVersion in the base project need to be modified (if involved). When other business projects are iterated later, increase the versionCode of the corresponding business project to make it consistent with the versionCode in the base project.

image.png

Scenario Two: The base project does not involve changes, but the business project needs to evolve (enhance functionality/fix bugs). Not only does the versionCode in the business project need to be increased, but the versionCode in the base project also needs to be modified. If the minAPIVersion is involved, it also needs to be modified together.

image.png

Key Takeaways

  • Use integrated HSP (not HAR) for cross-HAP sharing.
  • versionCode and minAPIVersion must match exactly between HSP and HAP — bundleName can differ due to automatic renaming.
  • Failure to align versionCode or minAPIVersion results in error 10024 during installation.
  • Integrated HSPs are safe and recommended for enterprise use within the same organization.
  • HSPs reduce code duplication, optimize app size, and support dynamic loading — improving performance and maintainability.

Additional Resources

https://developer.huawei.com/consumer/en/doc/harmonyos-guides/har-package

https://developer.huawei.com/consumer/en/doc/harmonyos-guides/in-app-hsp

Written by Mehmet Algul

Top comments (0)