0
# App Lifecycle & Utilities
1

2
Advanced application lifecycle management, loading states, and utility functions for controlling app behavior and performance optimization.
3

4
## Capabilities
5

6
### Loading Indicator
7

8
Programmatically control the loading indicator with fine-grained progress updates and error states.
9

10
```typescript { .api }
11
/**
12
 * Control the app-wide loading indicator programmatically
13
 * @param opts - Loading indicator configuration options
14
 * @returns LoadingIndicator instance with methods and reactive state
15
 */
16
function useLoadingIndicator(opts?: UseLoadingIndicatorOptions): LoadingIndicator;
17

18
interface UseLoadingIndicatorOptions {
19
  duration?: number;
20
  throttle?: number;
21
}
22

23
interface LoadingIndicator {
24
  progress: Ref<number>;
25
  isLoading: Ref<boolean>;
26
  error: Ref<any>;
27
  start(): void;
28
  finish(): void;
29
  set(value: number): void;
30
  clear(): void;
31
}
32
```
33

34
**Usage Example:**
35

36
```typescript
37
<script setup>
38
import { useLoadingIndicator } from "nuxt/app";
39

40
const { progress, isLoading, start, finish, set } = useLoadingIndicator({
41
  duration: 2000,
42
  throttle: 200
43
});
44

45
// Start loading
46
start();
47

48
// Update progress manually
49
set(50);
50

51
// Complete loading
52
finish();
53
</script>
54
```
55

56
### App Reloading
57

58
Reload the Nuxt application programmatically with various options for cache control and state persistence.
59

60
```typescript { .api }
61
/**
62
 * Reload the Nuxt application with optional configuration
63
 * @param options - Reload configuration options
64
 */
65
function reloadNuxtApp(options?: ReloadNuxtAppOptions): void;
66

67
interface ReloadNuxtAppOptions {
68
  ttl?: number;
69
  force?: boolean;
70
  persistState?: boolean;
71
  path?: string;
72
}
73
```
74

75
**Usage Example:**
76

77
```typescript
78
import { reloadNuxtApp } from "nuxt/app";
79

80
// Reload app with state persistence
81
reloadNuxtApp({
82
  persistState: true,
83
  force: true
84
});
85

86
// Reload with specific path
87
reloadNuxtApp({
88
  path: '/dashboard',
89
  ttl: 10000
90
});
91
```
92

93
### Runtime Hooks
94

95
Register and execute runtime hooks for application lifecycle events.
96

97
```typescript { .api }
98
/**
99
 * Register a runtime hook for application lifecycle events
100
 * @param name - Hook name to register
101
 * @param fn - Function to execute when hook is called
102
 */
103
function useRuntimeHook<T extends keyof RuntimeNuxtHooks>(
104
  name: T,
105
  fn: RuntimeNuxtHooks[T]
106
): void;
107

108
interface RuntimeNuxtHooks {
109
  'app:created': (app: NuxtApp) => void;
110
  'app:beforeMount': (app: NuxtApp) => void;
111
  'app:mounted': (app: NuxtApp) => void;
112
  'app:error': (error: any) => void;
113
  'app:error:cleared': (error: any) => void;
114
  'page:start': () => void;
115
  'page:finish': () => void;
116
  'page:transition:finish': () => void;
117
  'app:data:refresh': (keys?: string[]) => void;
118
  'app:manifest:update': (manifest: any) => void;
119
}
120
```
121

122
**Usage Example:**
123

124
```typescript
125
import { useRuntimeHook } from "nuxt/app";
126

127
// Listen for app mount
128
useRuntimeHook('app:mounted', (app) => {
129
  console.log('App is now mounted', app);
130
});
131

132
// Listen for page navigation
133
useRuntimeHook('page:start', () => {
134
  console.log('Page navigation started');
135
});
136
```
137

138
### Once Utilities
139

140
Execute functions only once during the application lifecycle, useful for initialization code.
141

142
```typescript { .api }
143
/**
144
 * Execute a function only once per key, useful for initialization
145
 * @param key - Unique key for the once execution (optional)
146
 * @param fn - Function to execute once
147
 * @returns Result of function execution or cached result
148
 */
149
function callOnce<T>(key?: string, fn?: () => T): T | undefined;
150
function callOnce<T>(fn: () => T): T;
151
```
152

153
**Usage Example:**
154

155
```typescript
156
import { callOnce, onNuxtReady } from "nuxt/app";
157

158
// Initialize analytics only once
159
callOnce('analytics', () => {
160
  // Analytics initialization code
161
  initializeAnalytics();
162
});
163

164
// Execute when app is ready
165
onNuxtReady(() => {
166
  console.log('Nuxt app is ready!');
167
});
168
```
169

170
### App Readiness
171

172
Execute code when the Nuxt application is fully ready and hydrated.
173

174
```typescript { .api }
175
/**
176
 * Execute callback when Nuxt app is fully ready
177
 * @param callback - Function to execute when ready
178
 */
179
function onNuxtReady(callback: () => void): void;
180
```
181

182
### Unique ID Generation
183

184
Generate unique, SSR-safe identifiers for components and elements.
185

186
```typescript { .api }
187
/**
188
 * Generate a unique ID that is SSR-safe and consistent
189
 * @returns Unique string identifier
190
 */
191
function useId(): string;
192
```
193

194
**Usage Example:**
195

196
```typescript
197
<script setup>
198
import { useId } from "nuxt/app";
199

200
const labelId = useId();
201
const inputId = useId();
202
</script>
203

204
<template>
205
  <div>
206
    <label :for="inputId" :id="labelId">Name</label>
207
    <input :id="inputId" :aria-labelledby="labelId" />
208
  </div>
209
</template>
210
```
211

212
## Types
213

214
```typescript { .api }
215
interface ReloadNuxtAppOptions {
216
  /** Time to live for the reload in milliseconds */
217
  ttl?: number;
218
  /** Force reload even if already reloading */
219
  force?: boolean;
220
  /** Persist state across reload */
221
  persistState?: boolean;
222
  /** Path to navigate to after reload */
223
  path?: string;
224
}
225

226
interface UseLoadingIndicatorOptions {
227
  /** Duration for the loading animation in milliseconds */
228
  duration?: number;
229
  /** Throttle interval for progress updates */
230
  throttle?: number;
231
}
232

233
interface LoadingIndicator {
234
  /** Current progress value (0-100) */
235
  progress: Ref<number>;
236
  /** Whether loading is active */
237
  isLoading: Ref<boolean>;
238
  /** Loading error if any */
239
  error: Ref<any>;
240
  /** Start the loading indicator */
241
  start(): void;
242
  /** Finish and hide the loading indicator */
243
  finish(): void;
244
  /** Set specific progress value */
245
  set(value: number): void;
246
  /** Clear the loading state */
247
  clear(): void;
248
}
249
```