0
# Nuxt
1

2
Nuxt is a free and open-source framework with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with Vue.js. It provides server-side rendering, static site generation, hybrid rendering, and edge-side rendering capabilities with automatic routing, built-in data fetching, SEO optimization, and zero-configuration TypeScript support.
3

4
## Package Information
5

6
- **Package Name**: nuxt
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install nuxt`
10

11
## Core Imports
12

13
Main framework functions:
14

15
```typescript
16
import { createNuxt, loadNuxt, build } from "nuxt";
17
```
18

19
Runtime composables and utilities:
20

21
```typescript
22
import { 
23
  useAsyncData, 
24
  useFetch, 
25
  useState, 
26
  useRouter, 
27
  useHead,
28
  defineNuxtPlugin,
29
  useRuntimeConfig,
30
  navigateTo,
31
  createError
32
} from "nuxt/app";
33
```
34

35
Configuration:
36

37
```typescript
38
import { defineNuxtConfig } from "nuxt/config";
39
```
40

41
Module development:
42

43
```typescript
44
import { defineNuxtModule, useNuxt, addPlugin } from "nuxt/kit";
45
```
46

47
For CommonJS:
48

49
```javascript
50
const { createNuxt, loadNuxt } = require("nuxt");
51
const { useAsyncData, useFetch } = require("nuxt/app");
52
```
53

54
## Basic Usage
55

56
### Configuration
57

58
```typescript
59
// nuxt.config.ts
60
import { defineNuxtConfig } from "nuxt/config";
61

62
export default defineNuxtConfig({
63
  modules: ["@nuxtjs/tailwindcss"],
64
  css: ["~/assets/css/main.css"],
65
  runtimeConfig: {
66
    apiSecret: "",
67
    public: {
68
      apiBase: "/api"
69
    }
70
  }
71
});
72
```
73

74
### Data Fetching
75

76
```typescript
77
// pages/users.vue
78
<script setup>
79
import { useFetch } from "nuxt/app";
80

81
// Fetch data with SSR support
82
const { data: users, pending, error } = await useFetch("/api/users");
83

84
// Lazy data fetching (non-blocking)
85
const { data: posts } = await useLazyFetch("/api/posts");
86
</script>
87

88
<template>
89
  <div>
90
    <div v-if="pending">Loading...</div>
91
    <div v-else-if="error">Error: {{ error.message }}</div>
92
    <div v-else>
93
      <user-card v-for="user in users" :key="user.id" :user="user" />
94
    </div>
95
  </div>
96
</template>
97
```
98

99
### State Management
100

101
```typescript
102
// composables/useCounter.ts
103
export const useCounter = () => {
104
  return useState("counter", () => 0);
105
};
106

107
// components/Counter.vue
108
<script setup>
109
const counter = useCounter();
110

111
function increment() {
112
  counter.value++;
113
}
114
</script>
115
```
116

117
### Navigation
118

119
```typescript
120
// Programmatic navigation
121
import { navigateTo } from "nuxt/app";
122

123
await navigateTo("/users");
124
await navigateTo({ name: "users-id", params: { id: "123" } });
125

126
// Router access
127
const router = useRouter();
128
const route = useRoute();
129
</script>
130
```
131

132
## Architecture
133

134
Nuxt is built around several key architectural components:
135

136
- **Universal Rendering**: Server-side rendering (SSR), static site generation (SSG), and client-side rendering (SPA) support
137
- **Auto-routing**: File-based routing system with dynamic routes and nested layouts
138
- **Data Fetching**: Built-in composables for data fetching with SSR, caching, and loading states
139
- **Module System**: Extensible architecture with 200+ community modules
140
- **Build System**: Powered by Vite with automatic code splitting and optimization
141
- **TypeScript Integration**: Full TypeScript support with auto-generated types
142
- **Server API**: Built-in server API routes using Nitro
143
- **Development Tools**: Hot module replacement, DevTools, and debugging utilities
144

145
## Capabilities
146

147
### Core Framework
148

149
Essential functions for creating, configuring, and building Nuxt applications. These are primarily used for programmatic Nuxt instances and custom build processes.
150

151
```typescript { .api }
152
function createNuxt(options: NuxtOptions): Nuxt;
153
function loadNuxt(opts: LoadNuxtOptions): Promise<Nuxt>;
154
function build(nuxt: Nuxt): Promise<void>;
155
```
156

157
[Core Framework](./core.md)
158

159
### Configuration
160

161
Configuration utilities for defining and managing Nuxt application settings with full TypeScript support.
162

163
```typescript { .api }
164
function defineNuxtConfig(config: NuxtConfig): NuxtConfig;
165

166
interface NuxtConfig {
167
  modules?: (string | ModuleOptions)[];
168
  css?: string[];
169
  runtimeConfig?: RuntimeConfig;
170
  ssr?: boolean;
171
  // ... extensive configuration options
172
}
173
```
174

175
[Configuration](./configuration.md)
176

177
### Data Fetching
178

179
Comprehensive data fetching system with server-side rendering support, caching, loading states, and error handling.
180

181
```typescript { .api }
182
function useAsyncData<DataT, ErrorT>(
183
  key: string,
184
  handler: () => Promise<DataT>,
185
  options?: AsyncDataOptions<DataT>
186
): AsyncData<DataT, ErrorT>;
187

188
function useFetch<ResT>(
189
  request: string | Request | Ref<string | Request>,
190
  opts?: UseFetchOptions
191
): AsyncData<ResT>;
192

193
interface AsyncData<DataT, ErrorT> {
194
  data: Ref<DataT | null>;
195
  pending: Ref<boolean>;
196
  error: Ref<ErrorT | null>;
197
  refresh: () => Promise<void>;
198
}
199
```
200

201
[Data Fetching](./data-fetching.md)
202

203
### State Management
204

205
Reactive state management with server-side hydration, cookie management, and error handling.
206

207
```typescript { .api }
208
function useState<T>(key?: string, init?: () => T): Ref<T>;
209
function useCookie<T>(name: string, opts?: CookieOptions<T>): CookieRef<T>;
210
function useError(): Ref<NuxtError | null>;
211
function createError<DataT>(err: string | Partial<NuxtError<DataT>>): NuxtError<DataT>;
212
```
213

214
[State Management](./state.md)
215

216
### Navigation & Routing
217

218
Vue Router integration with programmatic navigation, route middleware, and layout management.
219

220
```typescript { .api }
221
function useRouter(): Router;
222
function useRoute(): RouteLocationNormalizedLoaded;
223
function navigateTo(
224
  to: RouteLocationRaw,
225
  options?: NavigateToOptions
226
): Promise<void | NavigationFailure | false> | false | void;
227
function addRouteMiddleware(
228
  name: string | RouteMiddleware,
229
  middleware?: RouteMiddleware,
230
  options?: AddRouteMiddlewareOptions
231
): void;
232
```
233

234
[Navigation & Routing](./navigation.md)
235

236
### Server-Side Rendering
237

238
Server-side rendering utilities for hydration, request handling, and server-client data synchronization.
239

240
```typescript { .api }
241
function useHydration<K, T>(key: K, get: () => T, set: (value: T) => void): void;
242
function useRequestHeaders(include?: string[]): Record<string, string>;
243
function useRequestEvent(): H3Event;
244
function setResponseStatus(code: number, message?: string): void;
245
```
246

247
[SSR & Hydration](./ssr.md)
248

249
### Head Management
250

251
Document head management with reactive updates, SEO optimization, and server-side rendering support.
252

253
```typescript { .api }
254
function useHead(meta: MaybeComputedRef<MetaObject>): void;
255
function useHeadSafe(meta: MaybeComputedRef<MetaObject>): void;
256
function useSeoMeta(meta: MaybeComputedRef<MetaObject>): void;
257
function useServerHead(meta: MaybeComputedRef<MetaObject>): void;
258
```
259

260
[Head Management](./head.md)
261

262
### Module Development
263

264
Comprehensive utilities for developing Nuxt modules, including configuration, plugins, components, and build system integration.
265

266
```typescript { .api }
267
function defineNuxtModule<OptionsT>(definition: ModuleDefinition<OptionsT>): NuxtModule<OptionsT>;
268
function useNuxt(): Nuxt;
269
function addPlugin(plugin: AddPluginOptions): void;
270
function addComponent(options: AddComponentOptions): void;
271
```
272

273
[Module Development](./module-dev.md)
274

275
### App Lifecycle & Utilities
276

277
Application lifecycle management, loading states, runtime hooks, and utility functions for controlling app behavior.
278

279
```typescript { .api }
280
function useLoadingIndicator(opts?: UseLoadingIndicatorOptions): LoadingIndicator;
281
function reloadNuxtApp(options?: ReloadNuxtAppOptions): void;
282
function useRuntimeHook<T>(name: T, fn: RuntimeNuxtHooks[T]): void;
283
function callOnce<T>(key?: string, fn?: () => T): T | undefined;
284
function onNuxtReady(callback: () => void): void;
285
function useId(): string;
286
```
287

288
[App Lifecycle & Utilities](./app-lifecycle.md)
289

290
### Performance & Optimization
291

292
Advanced performance optimization APIs for component preloading, payload management, and app manifest handling.
293

294
```typescript { .api }
295
function preloadComponents(components: string | string[]): Promise<void>;
296
function prefetchComponents(components: string | string[]): Promise<void>;
297
function loadPayload<T>(url: string, opts?: LoadPayloadOptions): Promise<T | null>;
298
function preloadPayload(url: string, opts?: PreloadPayloadOptions): Promise<void>;
299
function getAppManifest(): Promise<NuxtAppManifest>;
300
function getRouteRules(path: string): Promise<NitroRouteRules>;
301
function isPrerendered(url?: string): Promise<boolean>;
302
function defineNuxtLink<T>(options: NuxtLinkOptions<T>): Component;
303
```
304

305
[Performance & Optimization](./performance.md)
306

307
## Types
308

309
```typescript { .api }
310
interface NuxtApp {
311
  vueApp: App<Element>;
312
  globalName: string;
313
  hooks: Hookable<RuntimeNuxtHooks>;
314
  hook: HookCallback;
315
  callHook: HookCallback;
316
  [key: string]: any;
317
}
318

319
interface AsyncDataOptions<ResT, DataT = ResT, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null> {
320
  server?: boolean;
321
  client?: boolean;
322
  lazy?: boolean;
323
  immediate?: boolean;
324
  default?: () => DefaultT | Ref<DefaultT>;
325
  transform?: (input: ResT) => DataT;
326
  pick?: PickKeys[];
327
  watch?: MultiWatchSources;
328
  deep?: boolean;
329
}
330

331
interface CookieOptions<T = string> {
332
  default?: () => T | Ref<T>;
333
  decode?: (value: string) => T;
334
  encode?: (value: T) => string;
335
  domain?: string;
336
  expires?: Date;
337
  httpOnly?: boolean;
338
  maxAge?: number;
339
  path?: string;
340
  sameSite?: boolean | "lax" | "strict" | "none";
341
  secure?: boolean;
342
}
343

344
interface NuxtError<DataT = any> {
345
  statusCode: number;
346
  statusMessage?: string;
347
  message: string;
348
  stack?: string;
349
  data?: DataT;
350
  cause?: unknown;
351
}
352

353
interface NavigateToOptions {
354
  replace?: boolean;
355
  redirectCode?: number;
356
  external?: boolean;
357
  open?: {
358
    target: string;
359
    windowFeatures?: {
360
      [key: string]: any;
361
    };
362
  };
363
}
364

365
interface ModuleOptions {
366
  src: string;
367
  options?: any;
368
  mode?: "client" | "server" | "all";
369
}
370

371
interface RuntimeConfig {
372
  [key: string]: any;
373
  public?: {
374
    [key: string]: any;
375
  };
376
}
377

378
interface UseFetchOptions<ResT = any> {
379
  method?: string;
380
  body?: any;
381
  headers?: Record<string, string>;
382
  query?: Record<string, any>;
383
  server?: boolean;
384
  client?: boolean;
385
  lazy?: boolean;
386
  immediate?: boolean;
387
  default?: () => ResT | null;
388
  transform?: (input: any) => ResT;
389
  pick?: string[];
390
  watch?: any[];
391
}
392

393
interface CookieRef<T> extends Ref<T> {
394
  value: T;
395
}
396

397
type KeysOf<T> = Array<keyof T extends string ? keyof T : string>;
398

399
type MultiWatchSources = any[];
400

401
interface Hookable<T = Record<string, any>> {
402
  hook<K extends keyof T>(name: K, fn: T[K]): void;
403
  callHook<K extends keyof T>(name: K, ...args: any[]): Promise<void>;
404
}
405

406
interface RuntimeNuxtHooks {
407
  "app:created": (app: any) => void;
408
  "app:beforeMount": (app: any) => void;
409
  "app:mounted": (app: any) => void;
410
  "app:suspense:resolve": (app: any) => void;
411
  [key: string]: (...args: any[]) => void;
412
}
413

414
type HookCallback = (...args: any[]) => void | Promise<void>;
415

416
type MaybeComputedRef<T> = T | Ref<T> | ComputedRef<T> | (() => T);
417

418
type RouteLocationRaw = string | { name?: string; path?: string; params?: Record<string, any>; query?: Record<string, any>; hash?: string };
419

420
interface Request extends globalThis.Request {}
421
interface Response extends globalThis.Response {}
422
interface ComputedRef<T> extends Ref<T> {}
423

424
// App Lifecycle & Utilities Types
425
interface UseLoadingIndicatorOptions {
426
  duration?: number;
427
  throttle?: number;
428
}
429

430
interface LoadingIndicator {
431
  progress: Ref<number>;
432
  isLoading: Ref<boolean>;
433
  error: Ref<any>;
434
  start(): void;
435
  finish(): void;
436
  set(value: number): void;
437
  clear(): void;
438
}
439

440
interface ReloadNuxtAppOptions {
441
  ttl?: number;
442
  force?: boolean;
443
  persistState?: boolean;
444
  path?: string;
445
}
446

447
// Performance & Optimization Types
448
interface LoadPayloadOptions {
449
  fresh?: boolean;
450
  hash?: string;
451
}
452

453
interface PreloadPayloadOptions {
454
  hash?: string;
455
}
456

457
interface NuxtAppManifest {
458
  id: string;
459
  timestamp: number;
460
  routes: Record<string, {
461
    id: string;
462
    file: string;
463
    children?: string[];
464
  }>;
465
  prerendered?: string[];
466
}
467

468
interface NitroRouteRules {
469
  cors?: boolean;
470
  headers?: Record<string, string>;
471
  redirect?: string | {
472
    to: string;
473
    statusCode?: number;
474
  };
475
  prerender?: boolean;
476
  index?: boolean;
477
  robots?: boolean;
478
  sitemap?: boolean;
479
  experimentalNoScripts?: boolean;
480
}
481

482
interface NuxtLinkOptions<T> {
483
  componentName?: string;
484
  externalRelAttribute?: string;
485
  activeClass?: string;
486
  exactActiveClass?: string;
487
  prefetchedClass?: string;
488
  trailingSlash?: 'append' | 'remove';
489
}
490

491
// Navigation Types
492
interface RouteAnnouncerOptions {
493
  politeness?: 'polite' | 'assertive';
494
  skipRoutes?: string[];
495
  formatMessage?: (route: RouteLocationNormalized) => string;
496
}
497

498
interface RouteAnnouncer {
499
  announce(): void;
500
  skip(): void;
501
  set(message: string): void;
502
}
503

504
// Server Context Types  
505
interface AppConfig {
506
  [key: string]: any;
507
}
508
```