Overview of Modular Operation
To address challenges of large and complex application development—such as increased package size due to multiple copies of code during compilation, file dependencies, difficulties in sharing code and resources, and pollution of singletons and global variables—ArkTS supports modular compilation, packaging, and running. This approach not only streamlines the development process but also facilitates easier code writing and feature maintenance.
Modularization is the process of organizing ArkTS/TS/JS modules (where each file corresponds to a module), including so modules, and then loading, parsing, combining, and executing these modules through compilation tools or runtime mechanisms.
ArkTS supports various module types, including ETS/TS/JS files, JSON files, and native modules. It adheres to both ECMAScript module specifications and CommonJS module specifications. In addition, ArkTS extends loading modes to include dynamic import, static import, lazy import, synchronous dynamic loading of native modules, and loading files using Node-API.
Loading Process of Modular Operation
ArkTS modular operation is implemented according to the ECMAScript module specification and executes modules using a post-order traversal method: starting from the leftmost subtree of the module graph, it executes the modules, then their peers, and finally their parents. This algorithm runs recursively until it reaches the root of the module graph.
For example, in the figure below, each parent node loads its corresponding child nodes and executes peers in the order specified by the import statements. The execution order for the module graph files is as follows: D->F->G->E->B->I->H->C->A.
Here, file A is referred to as the entry file, which is the starting point for execution. Certain built-in interfaces for loading content, such as windowStage.loadContent and Navigation, will also be executed as entry files, especially when these files are not loaded using the import syntax.
Starting from file A, a complete set of files will be loaded, including file A, files on which file A depends, and subsequently dependent files, until the leaf nodes of each branch is reached.
A regular module is loaded once in the same thread and multiple times in different threads, creating a new module object in each thread. If you only want to load the module once in a process, use the shared module.
Modular Specifications Supported by ArkTS
ECMAScript Module
ECMAScript modules (ES modules) are a module feature implemented in JavaScript starting from ECMAScript 6.0, standardized in the ECMAScript® 2025 Language Specification (tc39.es). The module functionality is composed of two commands: export and import.
For details about how to use export and import in ArkTS, see ArkTS Introduction.
CommonJS Module
CommonJS modules were proposed as a standard by the JavaScript community in 2009 and first partially adopted and implemented in Node.js. CommonJS treats each file as a module, with the module variable representing the current module. module.exports is the variable exported by the module, and each module also has an exports variable (exports === module.exports).
The following table lists the module import and export syntax.
| Loading Type | Module Import | Module Export (Do Not Mix module.exports with exports) |
|---|---|---|
| Variable | const ohos = require('ohos') | exports.add = add or module.exports.name = name |
| Variable | const ohos = require('ohos') | module.exports = add |
| Function | const ohos = require('ohos') ohos.fun(); |
exports.fun = function foo () {} or module.exports.fun = function foo () {} |
NOTE
CommonJS modules can be used only to export third-party packages. They cannot be created or used in projects.
Compatibility Between CommonJS and ES Modules
The following table lists the compatibility between CommonJS and ES modules, with the import and export syntax following their respective specifications.
| Inter-Module Reference | ES Module Export | CommonJS Export |
|---|---|---|
| ES Module Import | Supported | Supported |
| CommonJS Import | Not supported | Supported |
Module Types Supported by ArkTS
ETS/TS/JS
When loading the ETS, TS, and JS modules, you need to comply with the ECMAScript module specifications and CommonJS module specifications.
JSON File
JavaScript Object Notation (JSON) is a lightweight data interchange format that uses a text-based format independent of any programming language to store and represent data.
JSON files can only be imported using the default method, as shown below:
import data from './example.json'
Native Module
The syntax specifications for importing and exporting the native module (.so) are the same as those for loading the ETS, TS, and JS files. Native modules (.so files) follow the same import/export and loading syntax as ETS/TS/JS modules. For details, see Statically Loading Native Modules.
NOTE
Native modules cannot be imported to CommonJS modules.
Example:
// index.d.ts corresponding to libentry.so
export const add: (a: number, b: number) => number;