1# Lazy Import
2
3With the continuous expansion of application features, the time required for cold start increases significantly. The main reason is that a large number of modules are loaded at the early stage of startup, and a large number of redundant files that are not actually executed exist. In this case, not only an initialization process of the application is delayed, but also invalid resource occupation is caused. Therefore, measures urgently need to be taken to simplify a loading process and eliminate unnecessary file execution, to optimize cold start performance and ensure smooth user experience.
4
5> **Note**
6>
7> - The lazy import is supported since API version 12.
8>
9> - To use the lazy import syntax on API version 12, you need to configure **"compatibleSdkVersionStage": "beta3"** in the project. Otherwise, the compilation fails. For details, see [DevEco Studio build-profile.json5 File Description](https://developer.huawei.com/consumer/en/doc/harmonyos-guides-V5/ide-hvigor-build-profile-V5#section511142752919).
10
11
12## **Functions and Features**
13
14With the lazy import, unnecessary files are not loaded in the cold start phase until these files are required during application running, shortening the time required for cold start.
15
16## Storage mode
17
18You can use<!--Del-->[<!--DelEnd-->Trace<!--Del-->](../performance/common-trace-using-instructions.md)<!--DelEnd--> tools or logs to identify files that are not actually called during cold start. By analyzing the data, you can accurately locate the files that do not need to be pre-loaded in the startup phase, and add the **lazy** identifier for the invoking points of these files. Notice that subsequent synchronous loading may block the task execution. (If a task is clicked and lazy import is triggered, the files that are not loaded will be executed in cold start, which increases the time consumption. Therefore, you need to evaluate whether to use the **lazy** identifier.
19
20> **NOTE**
21>
22> You are not advised to blindly add **lazy** identifiers, which also increases the identification overhead during building and running.
23
24## Scenario Behavior Analysis
25
26- Use lazy import.
27
28    ```typescript
29        // main.ets
30        import lazy { a } from "./mod1";    // "mod1" is not executed.
31        import { c } from "./mod2";         // "mod2" is executed.
32
33        // ...
34
35        console.info("main executed");
36        while (false) {
37            let xx = a;
38        }
39
40        // mod1.ets
41        export let a = "mod1 executed"
42        console.info(a);
43
44        // mod2.ets
45        export let c = "mod2 executed"
46        console.info(c);
47
48    ```
49
50    The execution result is as follows:
51
52    ```typescript
53        mod2 executed
54        main executed
55    ```
56
57- Reference lazy import and native import for the same module at the same time.
58
59    ```typescript
60        // main.ets
61        import lazy { a } from "./mod1";    // "mod1" is not executed.
62        import { c } from "./mod2";         // "mod2" is executed.
63        import { c } from "./mod2";         // "mod1" is executed.
64
65        // ...
66
67        console.info("main executed");
68        while (false) {
69            let xx = a;
70        }
71
72        // mod1.ets
73        export let a = "mod1 a executed"
74        console.info(a);
75
76        export let b = "mod1 b executed"
77        console.info(b);
78
79        // mod2.ets
80        export let c = "mod2 c executed"
81        console.info(c);
82
83    ```
84
85    The execution result is as follows:
86
87    ```typescript
88        mod2 c executed
89        mod1 a executed
90        mod1 b executed
91        main executed
92    ```
93
94    If the keyword **lazy** is deleted from **main.ets** file, the execution sequence is as follows:
95
96    ```typescript
97        mod1 a executed
98        mod1 b executed
99        mod2 c executed
100        main executed
101    ```
102
103## Specifications
104
105- Lazy import supports the following instructions:
106
107| Syntax                              | ModuleRequest | ImportName  | LocalName   | Supported by API Version 12   |
108| :--------------------------------- | :------------ | :---------- | :---------- | :------------------- |
109| import lazy { x } from "mod";        | "mod"         | "x"         | "x"         | Yes                 |
110| import lazy { x as v } from "mod";   | "mod"         | "x"         | "v"         | Yes.                 |
111
112- The shared module is lazy imported or the dependency path contains the shared module.
113    Lazy import still takes effect for the shared module. For details about the constraints, see [Shared Module Development](../arkts-utils/arkts-sendable-module.md).
114
115### [Incorrect Example]
116
117Build error is reported if use the following syntax:
118
119```typescript
120    export lazy var v;                  // The compiler reports an application compilation error.
121    export lazy default function f(){}; // The compiler reports an application compilation error.
122    export lazy default function(){};   // The compiler reports an application compilation error.
123    export lazy default 42;             // The compiler reports an application compilation error.
124    export lazy { x };                    // The compiler reports an application compilation error.
125    export lazy { x as v };               // The compiler reports an application compilation error.
126    export lazy { x } from "mod";         // The compiler reports an application compilation error.
127    export lazy { x as v } from "mod";    // The compiler reports an application compilation error.
128    export lazy * from "mod";           // The compiler reports an application compilation error.
129
130    import lazy v from "mod";           // The compiler reports an application compilation error.
131    import lazy * as ns from "mod";     // The compiler reports an application compilation error.
132
133```
134
135If the **type** keyword is added to the syntax, an error is reported.
136
137```typescript
138    import lazy type { obj } from "./mod";    // Not supported. The compiler reports an application compilation error.
139    import type lazy { obj } from "./mod";    // Not supported. The compiler reports an application compilation error.
140
141```
142
143### Syntax Not Recommended
144
145- In the same ets file, not all the dependency modules that require the lazy import are added lazy identifiers.
146
147    Incomplete labeling will cause lazy loading to fail and increase the overhead of identifying lazy loading.
148    ```typescript
149        // main.ets
150        import lazy { a } from "./mod1";    // Obtain the object a from "mod1" and add a lazy identifier.
151        import { c } from "./mod2";
152        import { b } from "./mod1";         // Obtain the attributes in "mod1". This syntax is not added a lazy identifier, so "mod1" is executed by default.
153
154        // ...
155    ```
156- In the same ETS file, lazy loading variables are not used and exported again. Lazy loading variables cannot be exported by re-export.
157
158    The variable c exported in this mode is not used in B.ets, and the B.ets file is not executed. When variable a is used in the A.ets file, the variable is not initialized and a JS exception is thrown.
159    ```typescript
160        // A.ets
161        import { c } from "./B";
162        console.info(c);
163
164        // B.ets
165        import lazy { a } from "./mod1";    // Obtain the object a from "mod1" and add a lazy identifier.
166        export { c }
167
168        // C.ets
169        function c(){};
170        export { c }
171    ```
172    The execution result is as follows:
173    ```typescript
174        ReferenceError: a is not initaliized
175             at func_main_0 (A.ets:2:1)
176    ```
177
178    ```typescript
179        // A_ns.ets
180        import * as ns from "./B";
181        console.info(ns.c);
182
183        // B.ets
184        import lazy { a } from "./mod1";    // Obtain the object a from "mod1" and add a lazy identifier.
185        export { c }
186
187        // C.ets
188        function c(){};
189        export { c }
190    ```
191    The execution result is as follows:
192    ```typescript
193    ReferenceError: module environment is undefined
194        at func_main_0 (A_ns.js:2:1)
195    ```
196
197- Currently, lazy import cannot be executed in kit.
198
199- Developers need to evaluate the impact of lazy loading.
200    * Side-effects that do not depend on the module (such as initializing global variables and mounting globalThis)
201    * When objects are exported, time required for the lazy import deteriorates corresponding features.
202    * Bugs occur when the **lazy** identifier is used but the module is not executed.
203