Differences and Usage Scenarios of HAR, HSP, and HAP

Read the original article：Differences and Usage Scenarios of HAR, HSP, and HAP

Requirement Description

In projects, we often encounter HAR, HSP, and HAP. What are the differences among them, and what are their respective usage scenarios?

Background Knowledge

HAP: It is the basic unit for application installation and execution. A HAP package is a module package generated by packaging code, resources, third-party libraries, and configuration files. It is mainly divided into two types: entry and feature. An application package can contain only one basic entry package, or one basic entry package plus multiple functional feature packages.

HAR: It is a static shared package that can include code, C++ libraries, resources, and configuration files. HAR enables multiple modules or projects to share ArkUI components, resources, and related code.

• Supports intra-application sharing, and can also be published for use by other applications.
• As a secondary library, it can be published to an OHPM private repository for internal company use.
• As a third-party library, it can be published to the OHPM central repository for other applications.
• When multiple packages (HAP/HSP) reference the same HAR, it results in duplicate copies of code and resources among packages, causing the overall application package size to expand.

HSP: It is a dynamic shared package that can include code, C++ libraries, resources, and configuration files. HSP allows sharing of code and resources. HSP cannot be published independently but is released together with its host application’s APP package. It runs in the same process, with the same package name and lifecycle as the host app. When multiple HAP/HSP share common code and resources within one HSP, it improves reusability and maintainability. At compile time, only one copy of the HSP’s code and resources is retained, effectively reducing the app’s package size.

• In-app HSP: Strongly bound to the application’s bundleName during compilation and can only be used by that specific application.
• Integrated HSP: Not bound to a specific app’s bundleName during build or release; during use, the toolchain automatically replaces the integrated HSP’s package name with the host app’s package name, re-signs it to generate a new HSP package as part of the host app’s installation package—this new HSP is also considered an in-app HSP.

Implementation Steps

Usage scenarios and constraints for HAP, HAR, and HSP are as follows:

Package Type	Usage Scenario	Constraints
HAP	⭐Single HAP scenario: If only UIAbility components are needed without using ExtensionAbility components, prefer using a single HAP (one entry package) for app development. Although a HAP can contain one or more UIAbility components, it is recommended to adopt a “one UIAbility + multiple pages” approach to avoid unnecessary resource loading. ⭐Multi-HAP scenario: For complex apps that require ExtensionAbility components, multiple HAPs (one entry + several feature packages) can be used. Each HAP can contain a UIAbility or ExtensionAbility. In such cases, multiple HAPs may reference the same libraries, causing duplication during packaging.	⭐Does not support exporting interfaces or ArkUI components for use by other modules. ⭐In multi-HAP scenarios, within the APP Pack for the same device type, there must be exactly one entry-type HAP; feature-type HAPs can be one or more, or none. ⭐In multi-HAP scenarios, configuration fields (bundleName, versionCode, versionName, minCompatibleVersionCode, debug, minAPIVersion, targetAPIVersion, apiReleaseType) must be identical across all HAPs of the same application; moduleName tags must be unique. The build process will validate these parameters. ⭐In multi-HAP scenarios, all HAPs and HSPs in the same app must use the same signing certificate. When uploading to the App Market, apps are published as APP Pack files; during distribution, the market will unpack and re-sign all HAPs to ensure consistent signatures. During debugging, all HAPs must have consistent signatures, otherwise installation will fail.
HAR	Static shared package, reused at compile-time. ⭐Supports intra-app sharing or can be published for other apps. ⭐As a secondary library, published to a private OHPM repository for internal use. ⭐As a third-party library, published to the OHPM central repository for other apps.	HAR cannot be installed or run independently on a device—only referenced as a dependency of an app module. ⭐Does not support declaring ExtensionAbility components in the configuration file, but supports UIAbility. ⭐Cannot declare pages in config, but can contain them and navigate to them via Navigation. ⭐Cannot reference resources in the AppScope directory—these are excluded at build time, causing reference failures. ⭐HAR can depend on other HARs, but circular and transitive dependencies are not supported.
HSP	Dynamic shared package, reused at runtime. ⭐When multiple packages (HAP/HSP) reference the same shared package, using HSP instead of HAR avoids code and resource duplication, reducing app size.	⭐Cannot be installed or run independently; must be installed/run with the dependent HAP. The HSP version must match the HAP version. ⭐From API version 18, HSP supports declaring ExtensionAbility components, but not entry-type ExtensionAbility (those configured with entity.system.home or ohos.want.action.home). Versions ≤17 do not support ExtensionAbility declaration. ⭐Supports declaring UIAbility components (except entry ability). ⭐HSP can depend on other HAR or HSP, but circular and transitive dependencies are not supported.

Reference: 【Layered Architecture Design】

Q: If different apps use the same HSP, should the HSP be released separately to the app store?
A: Different apps will not use the same HSP, and HSPs cannot be independently released to the app store. HSPs must be released together with the app package of their host application, sharing the same process, package name, and lifecycle as the host app.

Q: What is the appropriate form for providing an SDK for external use? HAR or HSP?
A: For third-party libraries intended for use by third-party apps, HAR is recommended. The OpenHarmony third-party library central repository only supports the release of HAR shared packages and does not support the release of HSP shared packages.

Q: If multiple modules use the same HAR, will there be multiple HAR packages in the app or just one?
A: There will be multiple copies. Each user will copy a HAR to the corresponding module, which increases the package size. If the HAR contains large files such as duplicate resources, it is recommended to replace them with HSP.

Q: Can data from a HAP be referenced in a HAR package?
A: No. HAPs do not support exporting interfaces or ArkUI components for use by other modules.

Q: Can an AbilityStage be created in a HAR package, and when is the lifecycle of this AbilityStage executed?
A: No. AbilityStages are one-to-one corresponding to HAP packages. For details on the relationship, see the figure below:

Code Snippet / Configuration

Q: After converting HAR to HSP, I encountered a compilation error. How should I troubleshoot it?
A: After converting the HAR package to HSP, make sure the following configurations are correct:

• Check whether "type": "shared" is set in the module.json5 file under HAR, and add "deliveryWithInstall".

# /library/src/main/module.json5
{
  "module": {
    "type": "shared",
    "deliveryWithInstall": true,
    "pages": "$profile:main_pages"
    // ...
  }
}

• Check the hvigorfile.ts file in the module to see if harTasks has been changed to hspTasks.

export default {
    system: hspTasks,  // Built-in plugin of Hvigor.It cannot be modified.
    plugins:[]         // Custom plugin to extend the functionality of Hvigor.
}

• By default, the build-profile.json5 file in the HAR package includes "consumerFiles": './consumer-rules.txt'. This item is configurable only for the HAR module and represents the default obfuscation rules that need to be exported. It should be removed.

Q: Multiple HSPs reference the same HAR. The values in the HAR have been initialized in HSP A, but when used in HSP B, the values in the HAR are still the default ones. How can this be resolved?
A: After a HAR is referenced by multiple HSPs, it will be copied to each HSP. Therefore, instances in a HAR cannot be shared among multiple modules. If this scenario is involved, it is recommended to use HSP instead of HAR.

Q: In what scenarios would multiple HAPs be used?
A: Multiple HAPs are mainly used to help developers manage applications in a modular way, allowing them to combine and deploy multiple HAPs on different devices as needed, reducing the package size.

For example, in a payment application, there is a unified main interface that manages various modules such as "Scan," "Payment," "Messages," and "Wealth Management." The logic for managing these modules is implemented in the entry package, while the modules themselves ("Scan," "Payment," "Messages," and "Wealth Management") are implemented in different feature packages. Developers can develop multiple feature packages separately and test them independently, and finally, the entry package can integrate the features of these feature packages in a unified manner.

Q: Can HAP be used as a shared package for other applications?
A: No. To use it as a shared package for other applications, please use HAR or integrated HSP.
Q: How can I upload an HSP to the central repository for use by other third-party applications?
A: Currently, HSPs can only be released in private repositories. If you need to release them in the OpenHarmony third-party library central repository, you need to convert them to HAR packages.
Q: When using classes and methods from HAR or HSP, why can't the exported classes and methods be automatically identified and imported?
A: Before referencing, you need to configure the dependency on the HAR or HSP in the oh-package.json5 file of the using application, and declare the exposed interfaces of the HAR or HSP in the entry file index.ets. This way, the interfaces can be automatically identified and imported.
Q: In a project, there is one entry-type module and multiple feature-type modules. How can I specify which feature-type modules to load after the program starts?
A: The entry point module of the program can only be of the entry type. It is not possible to specify which feature-type modules to load at startup. However, the type of each module can be freely specified as either "entry" or "feature", as long as there is only one entry-type module. The program will load this module at startup. You can modify the type attribute in the module.json5 file of the module.
Q: When packaging an app, will the HSP package in release mode be compressed?
A: According to the compression rules for packaging apps, HAP and HSP packages in release mode will be compressed during app packaging.
Q: How can an HSP shared within an app, compiled into a.tgz package, depend on external HAR packages?
A: The dependent HAR packages need to be built into the HSP package and compiled together into the.tgz format.
Q: How can an HSP shared within an app, compiled into a.tgz package, depend on external HSP packages?
A: The dependent HSP packages need to be built into the HSP package and compiled together into the.tgz format, or the dependent HSP packages need to be published to a private repository and referenced by version number during the development of the shared HSP.
Q: Can an HAP be set as a separate process?
A: On 2-in-1 and tablet devices, the UIAbility supports setting an HAP as an independent process, allowing the module to run in its own process.
Q: How can JS files in HAR/HSP modules be exported for use by other modules?
A: You can use the export syntax of the ES module specification to export functions, variables, or classes. These can then be declared and exported through the HAR/HSP entry file index.ets. For details, refer to the following example:

// example.js
export function addNum(a, b) {
    return a + b;
}

export const version = '1.0.0'

export class User {
    name;
    age
}
// index.ets entry file
export { addNum, version, User } from './src/main/ets/utils/example';

Q: Why is the app package released to the app market smaller than the HAP package?
A: The HAP package compiled within an app is generally smaller than a normally compiled HAP package. By default, the app package is compiled in non-Debug mode, while the HAP package is compiled in Debug mode. The Debug version includes complete debugging information and symbol tables compared to the release version, which help developers quickly locate issues during debugging, view variable values, function call stacks, etc. In addition, the Debug version is not obfuscated or optimized, which also results in a larger package size compared to the release version.

Q: The version number of the HSP must be the same as that of the HAP. What does the version number refer to here?
A: HSPs cannot be released independently; they are released together with their host app's HAP package and run in the same process as the host app, sharing the same package name and lifecycle. The version number here refers to the version number of the HAP package, which is usually a custom version number defined by the HAP itself. Each HAP package has a different version number.

Q: During installation, the HSP is installed first, followed by the HAP. If the HAP is updated later, can I directly use hdc install hap to install it? If I uninstall the HAP, will the dependent HSPs also be uninstalled?
A: You can directly use hdc install xxx.hap to install the HAP without needing to uninstall and reinstall it. The HSP will not be uninstalled. HSPs are shared modules that may be used by multiple HAPs. The system will not easily delete HSPs that are depended on by other apps to prevent breaking other apps.

Q: In the project-level oh-package.json, there is a dependency on HAR module A. After compilation, HAR A is packed into HSP B. However, HSP B does not actually depend on HAR A, and an error message indicating a circular dependency between A and B is displayed during runtime.
A: The dependencies declared in the project-level oh-package.json apply to the entire project and will be depended on by all modules. Currently, it is not recommended to configure dependencies that are not devDependencies in the project-level dependencies. That is, the non-development-time dependencies of an HSP/Har module should be declared in the dependencies and dynamicDependencies of the corresponding module. Instead, you should declare the dependencies in the oh-package.json of the respective modules as needed.

Q: Is there a callback to notify the HAP that it is being uninstalled when uninstalling an HAP on a PC?
A: There is no callback to notify the HAP.
One of the steps in the uninstallation process is to call the meta-capability interface to kill the app process. The app process is killed first, and then the subsequent uninstallation operations are performed.

Q: If an HAP depends on an HSP and an HAR, and the HSP does not depend on the HAR, can the HSP use the resources in the HAR?
A: There is no dependency relationship between HSP and HAR. Therefore, the HSP cannot use the resources in the HAR.

Limitations or Considerations

This example supports API Version 20 Release and above.

This example supports HarmonyOS 6.0.0 Release SDK and above.

This example requires DevEco Studio 6.0.0 Release and above to compile and run.

Written by Emine Inan