🌐 Build and Run Your First Distributed HarmonyOS App in 15 Minutes (HarmonyOS 5.0.0 or high)

🌐 Build and Run Your First Distributed HarmonyOS App in 15 Minutes

Imagine controlling a TV from your phone with just one codebase. With HarmonyOS's distributed capabilities, that future is now. Let’s build a cross-device clipboard app today.

🎯 What You'll Build

A distributed clipboard app:

Runs on both phone and tablet
Shares text instantly across devices
Uses HarmonyOS’s distributedData APIs

🧰 Step 1: Project Setup

Create new project in DevEco Studio

Template: Empty Feature Ability (Stage Model)
Language: ArkTS
1. Add permissions to config.json:

"reqPermissions": [
  { "name": "ohos.permission.DISTRIBUTED_DATASYNC" },
  { "name": "ohos.permission.DISTRIBUTED_DEVICE_MANAGER" }
]

🛠️ Step 2: Create Clipboard Logic

File: entry/src/main/ets/common/clipboard.ets

import distributedData from '@ohos.data.distributedData';

export class ClipboardService {
  private kvManager;
  private kvStore;

  async init() {
    this.kvManager = distributedData.createKVManager({
      bundleName: 'com.example.clipboard',
      context: getContext(this)
    });
    this.kvStore = await this.kvManager.getKVStore({
      storeId: 'clipboard_store',
      type: distributedData.StoreType.SINGLE_VERSION
    });
  }

  async setText(value: string) {
    await this.kvStore.put('shared_text', value);
  }

  async getText(): Promise<string> {
    return await this.kvStore.get('shared_text');
  }
}

🧱 Step 3: Build UI with ArkTS

File: pages/Index.ets

import { ClipboardService } from '../common/clipboard';

@Component
struct IndexPage {
  @State text: string = '';
  clipboard: ClipboardService = new ClipboardService();

  async aboutToAppear() {
    await this.clipboard.init();
    this.text = await this.clipboard.getText();
  }

  build() {
    Column() {
      TextInput({ placeholder: 'Enter text', text: this.text })
        .onChange(value => this.text = value)
        .margin(10)

      Button('Share Across Devices')
        .onClick(async () => {
          await this.clipboard.setText(this.text);
        })
        .margin(10)

      Text(`Shared: ${this.text}`)
        .fontSize(18)
        .margin(10)
    }
  }
}

📱 How to Test Cross-Device Sync

Connect two HarmonyOS virtual devices or real devices (same Wi-Fi)
Enable "Distributed Networking" on both
Input text on one device → check update on the other (manually trigger getText() or bind listener)

⚠️ Common Errors & Fixes

Issue	Cause	Solution
`kvStore is undefined`	`init()` not awaited properly	Ensure `await this.clipboard.init()` is called
Text not syncing	Devices not paired / Wi-Fi not enabled	Enable distributed networking
Error: permission denied	Missing `reqPermissions` or not granted at runtime	Check config + prompt user to allow permissions
Duplicate storeId error	Running same app on multiple emulators w/o cleanup	Use unique `storeId` or clear app cache

📌 Summary

You’ve just built a distributed app that:

Shares data across devices
Uses HarmonyOS distributedData API
Leverages ArkTS for modern UI

🔮 Next Up…

We’ll explore HarmonyOS permission system in depth — understand how to handle camera, location, network, and more with fine-grained control.

👉 Stay tuned and star this guide if you liked it!

Marxu @marxu