ArkTS `import lazy`: One Keyword Cuts Cold-Start Bloat via Compiler-Runtime Loop

As HarmonyOS applications grow, cold-start performance degrades because the engine loads and executes every imported module upfront — even those not used until later user interactions. This redundant loading consumes CPU and memory, prolonging the white-screen wait.

Solution: import lazy Syntax

ArkTS adds a single lazy keyword to import statements:

// Before: loaded synchronously at startup
import { A } from "./A";

// After: loaded only when the imported binding is first used
import lazy { A } from "./A";

The module is skipped during cold start; the runtime triggers a synchronous load the moment the binding is accessed. No call-site rewriting, no async propagation, and existing type references and IDE navigation remain intact.

Core Advantages

1. Near-Zero Migration Cost

Unlike dynamic import() which forces async/await refactoring across call chains, import lazy keeps synchronous semantics — ideal for ArkUI declarative UI patterns.

2. Compiler + Ark Runtime Native Collaboration

Compile time: The compiler marks lazy modules in the generated Ark bytecode (abc) with deferred-execution metadata.

Runtime: Cold start skips source execution of marked modules, maintaining only resolution links; actual load fires synchronously on first use.

This design lets the compiler verify correctness early, removing the need for manual load orchestration.

3. Integrated Detection & Verification Toolchain

ArkTS provides a closed loop: Detect → Mark → Verify → Quantify .

DevEco Profiler Launch Template

Record startup: enable tracing via hdc shell param set persist.ark.properties 0x100105c, then capture the full cold-start trace.

Identify redundant files: the trace highlights modules loaded but never executed during startup.

After adding lazy, re-record and compare trace timelines to confirm elimination.

Command-Line Tool (API 20+)

Run

hdc file recv data/app/el2/100/base/${bundleName}/files/${bundleName}_redundant_file.txt D:\

to pull a report that classifies each file as used or unused and shows the parent import chain — pinpointing exactly where to add lazy.

Official example data shows ~ 15% reduction in resource-loading phase during cold start (improvement scales with redundancy volume).

4. Complements Dynamic import()

import lazy

targets synchronous cold-start optimization; dynamic import() remains for on-demand async loading (e.g., code splitting by route). The two serve distinct, non-overlapping scenarios.

5. Works with Shared Modules (HSP)

Lazy imports apply to HarmonyOS Shared Packages (HSP) without extra configuration — the build pipeline handles it uniformly.

Behavioral Edge Cases

Mixed imports: If the same module is imported both with and without lazy, the eager import wins and the module loads at startup.

Incomplete marking: Within a single .ets file, all dependencies intended for deferral must be marked lazy; partial marking disables deferral and adds runtime overhead.

Usage Caveats

Don't over-annotate: Blind lazy adds compiler/runtime identification overhead — use the detection tools to target true redundancies.

First-use sync block: The initial load is synchronous; triggering it on a UI interaction (button tap) may cause a visible hitch. Evaluate critical-path scenarios.

Avoid re-exporting lazy bindings: Re-export can expose uninitialized values. DevEco Studio offers reExportCheckMode ( noCheck / compatible / strict) to scan for this.

Top-level side effects: Module-level code (global init, globalThis mutations) won't run at startup — ensure no logic depends on that execution order.

Already dynamic-loaded files: If a file is loaded via dynamic import() and also marked lazy, the lazy flag takes effect inside the dynamic load's then callback.

For HarmonyOS developers chasing cold-start gains, import lazy delivers a low-friction, toolchain-integrated path from problem discovery to measured improvement.