# HarmonyAtomicService: A Modular Blueprint for HarmonyOS NEXT Atomic Services > This repository is a sample project for HarmonyOS NEXT atomic services, built on API 11, that demonstrates modular design, state management, routing, cloud functions, and device adaptation. It is a practical reference for developers building production-grade atomic services, though it lacks a license and recent activity details. **liyufengrex/HarmonyAtomicService** — Sample atomic services for HarmonyOS NEXT development, including static/dynamic library plus multi-module design, state management plus unified routing, cloud functions (cloud database), networking, custom components, dynamic routing, push notifications and other encapsulated utility libraries. - Repository: https://github.com/liyufengrex/HarmonyAtomicService - Stars: 102 · Forks: 13 - Language: TypeScript - License: not declared - Published: 2026-08-17 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/liyufengrex-harmonyatomicservice ## What This Sample Solves and Who It Is For HarmonyOS NEXT introduced atomic services as lightweight, feature-focused applications, but building one involves many non-trivial pieces: modular packaging, state management, routing, permission handling, and cloud connectivity. This repository, written in TypeScript and based on API 11, collects those pieces into one reference project. The intended audience is a HarmonyOS developer who already knows the basics and wants to see how to structure a real atomic service with reusable libraries and business modules. The README explicitly lists the covered topics, from static and dynamic packages to foldable screen adaptation. It is a sample, not a framework, so its value is in the patterns it demonstrates, not in any ready-to-use abstraction. ## Modular Architecture: Static Libraries, Dynamic Packages, and Business Separation The project separates concerns into two layers. The base layer contains three modules: fast_util for utilities like logging, event bus, routing, and permission decorators; fast_ui for common UI components such as text, buttons, toast, and loading; and global_constant for path constants. The business layer holds feature_home, feature_setting, and feature_hsp_page, each as a static package (HAR) or dynamic package (HSP). This separation lets you compile common code once and share it across features, while dynamic packages allow on-demand loading. The directory tree shows an entry module for the main ability and pages, plus a business folder for feature modules. This layout mirrors what a production team would set up, though the sample does not include a build script or dependency graph, so you must inspect the module-level build files yourself. ## Routing: Static Paths, Dynamic Imports, and the WrappedBuilder Trick Routing is handled two ways. FastRouter wraps the standard router API for simple navigation, while FastNavRouter implements dynamic routing using navPathStack, dynamic import, and WrappedBuilder. The key mechanism is a static Map that stores WrappedBuilder objects keyed by a route name. When a page is first loaded, you register a builder function that wraps the target component. The README shows a route name like '@ohos/feature_setting*./src/main/ets/TestDynamicNavPage', which combines the module name and the file path. This approach lets you navigate to a page without a static import, which is useful for feature modules that are loaded on demand. The downside is that you must manually register each route, and the sample does not show how to handle unregistration or memory cleanup. For a small app this is fine, but for a large one you need a more systematic registry. ## Decorators That Do Work: Throttle, Debounce, and Permission Requests The fast_util module includes custom decorators that reduce boilerplate. The @Throttle decorator, shown with a 2000 millisecond window, prevents a click handler from firing more than once in that period. The @Permission decorator takes a context and a list of permissions, and only calls the decorated method after the user grants them. This is a clever way to keep permission logic out of the business method. However, decorators in TypeScript are still experimental and the HarmonyOS implementation may have limitations. The sample does not specify whether these decorators work with async methods or how they handle permission denial. You would need to test those edge cases yourself. Also, the permission list is hardcoded in the example, so you must adapt it to your app's needs. ## Cloud Functions and Cloud Database: Real Backend Integration The project shows how to call Huawei Cloud Functions and use the Cloud Database. For functions, it lists the required dependencies from the @hw-agconnect packages and shows a call to cloudFunction.call with a name, version, timeout, and data payload. The response comes back as a FunctionResult. For the database, it demonstrates upserting a record into a zone called 'CodeLabDemo'. The record is a LogReport object with id, content, and time fields. Both require configuration files: agconnect-services.json in AppScope/resources/rawfile and schema.json in entry/src/main/resources/rawfile. These files must be exported from the AGC console, so you cannot run the sample without your own AGC project. The README does not cover reading data or handling errors beyond a catch block, so the sample is minimal. It is enough to show the pattern, not a full data layer. ## UI Flexibility: BuilderNode, NodeController, and Component Factories Several sections cover advanced UI techniques. BuilderNode and NodeController allow dynamic manipulation of UI nodes, which is useful for overlay or floating elements. The component factory example uses a Map that stores WrappedBuilder objects and then invokes them by key, letting you swap UI components at runtime without conditional rendering. The AttributeModifier example demonstrates setting component attributes dynamically. These patterns are valuable for building configurable or plugin-based interfaces. However, the README only shows fragments, not complete implementations. For a developer new to these APIs, the linked Juejin posts are probably necessary to understand the full context. The sample does not include a demo page for each technique, so you may need to explore the repository yourself to see them in action. ## Foldable Screen Support and Huawei Account Services The project includes a FoldStatusObserver in the entry ability that listens for fold state changes. This is a concrete example of adapting to foldable devices, which is a specific requirement for HarmonyOS apps. The README also covers Huawei Account Services for quick login and phone number verification. The setup requires configuring a client ID and sensitive permissions. These features are tied to Huawei's ecosystem, so they only apply if you target Huawei devices and use Huawei's account system. The foldable observer is a small piece, but it shows the right hook point. The account service example is limited to setup steps; the actual login flow is not detailed. You would need to follow the linked Huawei documentation for the full implementation. ## Limitations, Maintenance, and Licensing Gaps The repository has no license file, which is a significant issue for adoption. Without a license, you cannot legally reuse the code in your own projects, even for learning, unless you contact the author. The last push date is unknown, so you cannot gauge how current the code is relative to the latest HarmonyOS API versions. The README says '持续更新中' (continuously updating), but there is no evidence of recent activity. The sample relies on external services (AGC, Huawei Cloud), so any code that touches those services will not work without proper configuration. There is also no test suite or CI configuration, so you must verify behavior manually. The maintenance cost is moderate: you need to track API changes and update the sample yourself. For a production project, you would likely extract only the patterns you need and write your own implementations. ## Conclusion Adopt this project if you are a HarmonyOS NEXT developer (API 11 or later) who needs a working reference for modular static/dynamic packages, unified routing, decorator-based permission requests, and cloud integration. Avoid it if you require a production-ready library with a defined license or if you are not targeting Huawei's ecosystem. Before using any code, verify the exact API versions and replace the AGC configuration files (agconnect-services.json and schema.json) with your own project credentials. The repository is a teaching sample, not a drop-in solution. ## FAQ ### What are atomic services? HarmonyAtomicService is an example project for building them: an app for HarmonyOS NEXT based on API 11 that runs on NEXT and later. It is described in English as a set of design examples covering static and dynamic packages, multi-module layout, state management, unified routing, network requests, custom components, dynamic routing, notifications and utility library wrappers. ### Which HarmonyOS modules does this project use? Three base modules and three business modules. The base side is fast_util for logging, EventBus, two routers, throttling, permissions and preferences, fast_ui for CommonText, CommonButton, FastToast and FastLoading, and global_constant for page path constants. The business side is two static har packages, feature_home and feature_setting, plus one dynamic hsp package, feature_hsp_page. ### Does this project show how to call a cloud function or cloud database? Yes, both, and both start with a file exported from the AGC platform rather than with code. Cloud functions use AppScope/resources/rawfile/agconnect-services.json and five @hw-agconnect packages at 1.1.2, while the cloud database uses entry/src/main/resources/rawfile/schema.json and a zone handle for the storage zone created on the platform. ## Sources - [Official README](https://github.com/liyufengrex/HarmonyAtomicService#readme) - [Project repository](https://github.com/liyufengrex/HarmonyAtomicService) - [README](https://github.com/liyufengrex/HarmonyAtomicService/blob/main/README.md) - [Releases](https://github.com/liyufengrex/HarmonyAtomicService/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/liyufengrex-harmonyatomicservice