What Should Be Initialized in AbilityStage? A Guide to App-Wide Setup in HarmonyOS

#harmonyos #stagemodel #abilitystage #processinitialization

Read the original article：What Should Be Initialized in AbilityStage? A Guide to App-Wide Setup in HarmonyOS

Requirement Description

Developers need to initialize application-wide logic in HarmonyOS Stage Model apps. This includes setting up SDKs, logging systems, service registries, and shared resources that should be active throughout the app's lifecycle. The challenge is deciding what belongs in AbilityStage, and what should be deferred to individual UIAbility or ExtensionAbility components.

Background Knowledge

In the HarmonyOS Stage model, AbilityStage acts as the entry point for each process within an application. While it plays a similar role to Android’s Application class, it is instantiated separately for each process, not once per application.

By default, all UIAbility components (with the same bundle name) share a single main process, and thus one AbilityStage instance for that process. However, each type of ExtensionAbility (such as FormExtensionAbility, InputMethodExtensionAbility, etc.) runs in its own independent process, meaning they each receive a separate AbilityStage instance.

As a result, any logic placed in AbilityStage.onCreate() is scoped only to the current process and will not be shared across other processes within the same app.

Implementation Steps

Use AbilityStage.onCreate() to perform app-level, process-wide initialization.
Initialize lightweight SDKs, logging frameworks, or dependency injection containers that rely on the applicationContext rather than a UI context.
Avoid placing logic that depends on specific ability types (UI or service) unless explicitly checking for it.
Detect process types (optional) if you want to conditionally initialize components.
For shared state, persist data to disk or use IPC mechanisms, since AbilityStage instances are not shared across processes.

Code Snippet

export default class MyAbilityStage extends AbilityStage {
  onCreate(): void {
    console.info("AbilityStage created");

    // Initialize a logger
    Logger.init({
      level: 'INFO',
      destination: 'console'
    });

    // Register a global service
    ServiceRegistry.register(ApiClient, new ApiClient(this.context.getApplicationContext()));

    // Optional: Detect current process type
    const processName = this.context.processName; 
    console.info(`Current process: ${processName}`);

    // Avoid initializing UI components here
  }
}

Test Results

Logger initialized once per process as expected.
Global services are accessible to all abilities within the same process.
Services in other extension processes required their own AbilityStage re-initialization.
Conditional initialization based on process type successfully avoided redundant logic.

Limitations or Considerations

AbilityStage is not a global singleton; it exists per process.
Do not perform any UI-related operations in AbilityStage.
Avoid heavy or blocking operations here — use async tasks or delay them to later stages like UIAbility.onWindowStageCreate().
If the app uses multiple processes, each must handle its own AbilityStage setup independently.