HarmonyOS Cross-Package Navigation: Multi-Module Routing with HAP, HSP, HAR

Cross-Package Navigation in HarmonyOS Multi-Module Apps

Large-scale HarmonyOS applications typically split code and business logic into multiple modules — HAP (entry), HSP (shared), and HAR (static library) — developed by different teams. The Navigation framework supports cross-package routing, enabling jumps from a HAP home page to HSP/HAR child pages and back.

Example Module Structure

The demonstration uses six pages across three modules:

HAP module: HapPageA, HapPageB

HSP module: HspPageA, HspPageB

HAR module: HarPageA, HarPageB

All six pages can navigate to each other.

Module Configuration

Each module requires a Navigation system routing table. The IDE screenshots below show the module type selection for HAP, HSP, and HAR.

HAP module

HSP module

HAR module

Creating Router Map

In each module's src/main/resources/base/profile/ directory (create if missing), add a router_map.json file. The routing table is an array named routerMap where each item represents a navigation destination with three required fields and one optional field: name — the pushPath identifier used in navigation pageSourceFile — relative path to the page file buildFunction — the @Builder function name that constructs the page data (optional) — custom data accessible in the target page's onReady lifecycle via NavDestinationContext.getConfigInRouteMap() Example for HAP module:

{
  "routerMap": [
    {
      "name": "HapPageA",
      "pageSourceFile": "src/main/ets/pages/HapPageA.ets",
      "buildFunction": "HapPageABuilder",
      "data": {
        "description": "this is HapPageA"
      }
    },
    {
      "name": "HapPageB",
      "pageSourceFile": "src/main/ets/pages/HapPageB.ets",
      "buildFunction": "HapPageBBuilder",
      "data": {
        "description": "this is HapPageB"
      }
    }
  ]
}

Navigation Implementation

Each page component uses NavDestination and exposes a @Builder function. The onReady callback retrieves the optional data from the route map.

import { ControlPanel } from './Common';
@Component
export struct HapPageA {
  build() {
    NavDestination() {
      Stack({ alignContent: Alignment.Center }) {
        ControlPanel()
      }.width('100%').height('100%')
    }.title('HapPageA')
    .onReady((ctx: NavDestinationContext) => {
      let config = ctx.getConfigInRouteMap();
      console.log(`testTag HapPageA config.data: ${JSON.stringify(config?.data)}`)
    })
  }
}
// Page builder function
@Builder
export function HapPageABuilder(): void {
  HapPageA()
}

Compilation and Build Order

Because HAP depends on HSP and HAR, the shared modules must be compiled first and their artifacts placed in a common directory.

Compile HAR module → produces .har file

Compile HSP module → produces .tgz file

Copy both artifacts to a shared libs folder

Compile HAR

Compile HSP

Configuring Dependencies

In the HAP module's oh-package.json5, declare dependencies on the local HAR and HSP packages using file: protocol:

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "har_a": "file:../libs/HAR_A.har",
    "hsp_a": "file:../libs/HSP_A-default.tgz"
  }
}

Final Build and Run

After configuring dependencies, build the HAP module. The resulting app demonstrates seamless cross-package navigation among all six pages.

Final HAP build

Cross-package navigation in action

For the complete solution and additional code samples, refer to the companion article ArkUI Navigation Component Comprehensive Analysis: From Basic Navigation to Advanced Routing Practice .