# Nuxt

> abortNavigation is a helper function that prevents navigation from taking place and throws an error if one is set as a parameter.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/abort-navigation.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/abort-navigation.md

# abortNavigation

> abortNavigation is a helper function that prevents navigation from taking place and throws an error if one is set as a parameter.

<warning>

`abortNavigation` is only usable inside a [route middleware handler](/docs/4.x/directory-structure/app/middleware).

</warning>

## Type

```ts [Signature]
export function abortNavigation (err?: Error | string): false
```

## Parameters

### `err`

- **Type**: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | `string`<br />

Optional error to be thrown by `abortNavigation`.

## Examples

The example below shows how you can use `abortNavigation` in a route middleware to prevent unauthorized route access:

```ts [app/middleware/auth.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  const user = useState('user')

  if (!user.value.isAuthorized) {
    return abortNavigation()
  }

  if (to.path !== '/edit-post') {
    return navigateTo('/edit-post')
  }
})
```

### `err` as a String

You can pass the error as a string:

```ts [app/middleware/auth.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  const user = useState('user')

  if (!user.value.isAuthorized) {
    return abortNavigation('Insufficient permissions.')
  }
})
```

### `err` as an Error Object

You can pass the error as an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object, e.g. caught by the `catch`-block:

```ts [app/middleware/auth.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  try {
    /* code that might throw an error */
  } catch (err) {
    return abortNavigation(err)
  }
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/add-route-middleware.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/add-route-middleware.md

# addRouteMiddleware

> addRouteMiddleware() is a helper function to dynamically add middleware in your application.

<note>

Route middleware are navigation guards stored in the [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) directory of your Nuxt application (unless [set otherwise](/docs/4.x/api/nuxt-config#middleware)).

</note>

## Type

```ts
function addRouteMiddleware (name: string, middleware: RouteMiddleware, options?: AddRouteMiddlewareOptions): void
function addRouteMiddleware (middleware: RouteMiddleware): void

interface AddRouteMiddlewareOptions {
  global?: boolean
}
```

## Parameters

### `name`

- **Type:** `string` | `RouteMiddleware`

Can be either a string or a function of type `RouteMiddleware`. Function takes the next route `to` as the first argument and the current route `from` as the second argument, both of which are Vue route objects.

Learn more about available properties of [route objects](/docs/4.x/api/composables/use-route).

### `middleware`

- **Type:** `RouteMiddleware`

The second argument is a function of type `RouteMiddleware`. Same as above, it provides `to` and `from` route objects. It becomes optional if the first argument in `addRouteMiddleware()` is already passed as a function.

### `options`

- **Type:** `AddRouteMiddlewareOptions`

An optional `options` argument lets you set the value of `global` to `true` to indicate whether the router middleware is global or not (set to `false` by default).

## Examples

### Named Route Middleware

Named route middleware is defined by providing a string as the first argument and a function as the second:

```ts [app/plugins/my-plugin.ts]
export default defineNuxtPlugin(() => {
  addRouteMiddleware('named-middleware', () => {
    console.log('named middleware added in Nuxt plugin')
  })
})
```

When defined in a plugin, it overrides any existing middleware of the same name located in the `app/middleware/` directory.

### Global Route Middleware

Global route middleware can be defined in two ways:

- Pass a function directly as the first argument without a name. It will automatically be treated as global middleware and applied on every route change.```ts [app/plugins/my-plugin.ts]
export default defineNuxtPlugin(() => {
  addRouteMiddleware((to, from) => {
    console.log('anonymous global middleware that runs on every route change')
  })
})
```
- Set an optional, third argument `{ global: true }` to indicate whether the route middleware is global.```ts [app/plugins/my-plugin.ts]
export default defineNuxtPlugin(() => {
  addRouteMiddleware('global-middleware', (to, from) => {
    console.log('global middleware that runs on every route change')
  },
  { global: true },
  )
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/add.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/add.md

# nuxt add

> Scaffold an entity into your Nuxt application.

```bash [Terminal]
npx nuxt add <TEMPLATE> <NAME> [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--force]
```

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        TEMPLATE
      </code>
    </td>
    
    <td>
      Specify which template to generate (options: <api|app|app-config|component|composable|error|layer|layout|middleware|module|page|plugin|server-middleware|server-plugin|server-route|server-util>)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NAME
      </code>
    </td>
    
    <td>
      Specify name of the generated file
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      <code>
        .
      </code>
    </td>
    
    <td>
      Specify the working directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --force
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Force override file if it already exists
    </td>
  </tr>
</tbody>
</table>

**Modifiers:**

Some templates support additional modifier flags to add a suffix (like `.client` or `.get`) to their name.

```bash [Terminal]
# Generates `/plugins/sockets.client.ts`
npx nuxt add plugin sockets --client
```

## `nuxt add component`

- Modifier flags: `--mode client|server` or `--client` or `--server`

```bash [Terminal]
# Generates `app/components/TheHeader.vue`
npx nuxt add component TheHeader
```

## `nuxt add composable`

```bash [Terminal]
# Generates `app/composables/foo.ts`
npx nuxt add composable foo
```

## `nuxt add layout`

```bash [Terminal]
# Generates `app/layouts/custom.vue`
npx nuxt add layout custom
```

## `nuxt add plugin`

- Modifier flags: `--mode client|server` or `--client`or `--server`

```bash [Terminal]
# Generates `app/plugins/analytics.ts`
npx nuxt add plugin analytics
```

## `nuxt add page`

```bash [Terminal]
# Generates `app/pages/about.vue`
npx nuxt add page about
```

```bash [Terminal]
# Generates `app/pages/category/[id].vue`
npx nuxt add page "category/[id]"
```

## `nuxt add middleware`

- Modifier flags: `--global`

```bash [Terminal]
# Generates `app/middleware/auth.ts`
npx nuxt add middleware auth
```

## `nuxt add api`

- Modifier flags: `--method` (can accept `connect`, `delete`, `get`, `head`, `options`, `patch`, `post`, `put` or `trace`) or alternatively you can directly use `--get`, `--post`, etc.

```bash [Terminal]
# Generates `server/api/hello.ts`
npx nuxt add api hello
```

## `nuxt add layer`

```bash [Terminal]
# Generates `layers/subscribe/nuxt.config.ts`
npx nuxt add layer subscribe
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/analyze.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/analyze.md

# nuxt analyze

> Analyze the production bundle or your Nuxt application.

```bash [Terminal]
npx nuxt analyze [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [-e, --extends=<layer-name>] [--name=<name>] [--no-serve]
```

The `analyze` command builds Nuxt and analyzes the production bundle (experimental).

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --name=<name>
      </code>
    </td>
    
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      Name of the analysis
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --no-serve
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Skip serving the analysis results
    </td>
  </tr>
</tbody>
</table>

<note>

This command sets `process.env.NODE_ENV` to `production`.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api.md

# Source: https://nuxt.com/raw/docs/4.x/api.md

# Nuxt API Reference

> Explore all Nuxt Internals: Components, Composables, Utils, Commands and more.

<card-group>
<card icon="i-lucide-box" title="Components" to="/docs/4.x/api/components/client-only">

Explore Nuxt built-in components for pages, layouts, head, and more.

</card>

<card icon="i-lucide-arrow-left-right" title="Composables" to="/docs/4.x/api/composables/use-app-config">

Discover Nuxt composable functions for data-fetching, head management and more.

</card>

<card icon="i-lucide-square-function" title="Utils" to="/docs/4.x/api/utils/dollarfetch">

Learn about Nuxt utility functions for navigation, error handling and more.

</card>

<card icon="i-lucide-square-terminal" title="Commands" to="/docs/4.x/api/commands/add">

List of Nuxt CLI commands to init, analyze, build, and preview your application.

</card>

<card icon="i-lucide-package" title="Nuxt Kit" to="/docs/4.x/api/kit/modules">

Understand Nuxt Kit utilities to create modules and control Nuxt.

</card>

<card icon="i-lucide-brain" title="Advanced" to="/docs/4.x/api/advanced/hooks">

Go deep in Nuxt internals with Nuxt lifecycle hooks.

</card>

<card icon="i-lucide-cog" title="Nuxt Configuration" to="/docs/4.x/api/nuxt-config">

Explore all Nuxt configuration options to customize your application.

</card>
</card-group>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/app-config.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/app-config.md

# app.config.ts

> Expose reactive configuration within your application with the App Config file.

Nuxt provides an `app/app.config.ts` config file to expose reactive configuration within your application with the ability to update it at runtime within lifecycle or using a nuxt plugin and editing it with HMR (hot-module-replacement).

You can easily provide runtime app configuration using `app.config.ts` file. It can have either of `.ts`, `.js`, or `.mjs` extensions.

```ts [app/app.config.ts]twoslash
export default defineAppConfig({
  foo: 'bar',
})
```

<caution>

Do not put any secret values inside `app.config` file. It is exposed to the user client bundle.

</caution>

<note>

When configuring a custom [`srcDir`](/docs/4.x/api/nuxt-config#srcdir), make sure to place the `app.config` file at the root of the new `srcDir` path.

</note>

## Usage

To expose config and environment variables to the rest of your app, you will need to define configuration in `app.config` file.

```ts [app/app.config.ts]twoslash
export default defineAppConfig({
  theme: {
    primaryColor: '#ababab',
  },
})
```

We can now universally access `theme` both when server-rendering the page and in the browser using [`useAppConfig`](/docs/4.x/api/composables/use-app-config) composable.

```vue [app/pages/index.vue]
<script setup lang="ts">
const appConfig = useAppConfig()

console.log(appConfig.theme)
</script>
```

The [`updateAppConfig`](/docs/4.x/api/utils/update-app-config) utility can be used to update the `app.config` at runtime.

```vue [app/pages/index.vue]
<script setup>
const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }

updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
</script>
```

<read-more to="/docs/4.x/api/utils/update-app-config">

Read more about the `updateAppConfig` utility.

</read-more>

## Typing App Config

Nuxt tries to automatically generate a TypeScript interface from provided app config so you won't have to type it yourself.

However, there are some cases where you might want to type it yourself. There are two possible things you might want to type.

### App Config Input

`AppConfigInput` might be used by module authors who are declaring what valid *input* options are when setting app config. This will not affect the type of `useAppConfig()`.

```ts [index.d.ts]
declare module 'nuxt/schema' {
  interface AppConfigInput {
    /** Theme configuration */
    theme?: {
      /** Primary app color */
      primaryColor?: string
    }
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}
```

### App Config Output

If you want to type the result of calling [`useAppConfig()`](/docs/4.x/api/composables/use-app-config), then you will want to extend `AppConfig`.

<warning>

Be careful when typing `AppConfig` as you will overwrite the types Nuxt infers from your actually defined app config.

</warning>

```ts [index.d.ts]
declare module 'nuxt/schema' {
  interface AppConfig {
    // This will entirely replace the existing inferred `theme` property
    theme: {
      // You might want to type this value to add more specific types than Nuxt can infer,
      // such as string literal types
      primaryColor?: 'red' | 'blue'
    }
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}
```

## Merging Strategy

Nuxt uses a custom merging strategy for the `AppConfig` within [the layers](/docs/4.x/getting-started/layers) of your application.

This strategy is implemented using a [Function Merger](https://github.com/unjs/defu#function-merger), which allows defining a custom merging strategy for every key in `app.config` that has an array as value.

<note>

The function merger can only be used in the extended layers and not the main `app.config` in project.

</note>

Here's an example of how you can use:

<code-group>

```ts [layer/app/app.config.ts]twoslash
export default defineAppConfig({
  // Default array value
  array: ['hello'],
})
```

```ts [app/app.config.ts]twoslash
export default defineAppConfig({
  // Overwrite default array value by using a merger function
  array: () => ['bonjour'],
})
```

</code-group>

## Known Limitations

As of Nuxt v3.3, the `app.config.ts` file is shared with Nitro, which results in the following limitations:

1. You cannot import Vue components directly in `app.config.ts`.
2. Some auto-imports are not available in the Nitro context.

These limitations occur because Nitro processes the app config without full Vue component support.

While it's possible to use Vite plugins in the Nitro config as a workaround, this approach is not recommended:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    vite: {
      plugins: [vue()],
    },
  },
})
```

<warning>

Using this workaround may lead to unexpected behavior and bugs. The Vue plugin is one of many that are not available in the Nitro context.

</warning>

Related issues:

- [Issue #19858](https://github.com/nuxt/nuxt/issues/19858)
- [Issue #19854](https://github.com/nuxt/nuxt/issues/19854)

<note>

Nitro v3 will resolve these limitations by removing support for the app config.
You can track the progress in [this pull request](https://github.com/nitrojs/nitro/pull/2521).

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/app.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/app.md

# app.vue

> The app.vue file is the main component of your Nuxt application.

<tip>

If you have a `app/pages/` directory, the `app.vue` file is optional. Nuxt will automatically include a default `app.vue`, but you can still add your own to customize the structure and content as needed.

</tip>

## Usage

### Minimal Usage

With Nuxt, the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory is optional. If it is not present, Nuxt will not include the [vue-router](https://router.vuejs.org) dependency. This is useful when building a landing page or an application that does not require routing.

```vue [app/app.vue]
<template>
  <h1>Hello World!</h1>
</template>
```

<link-example to="/docs/4.x/examples/hello-world">



</link-example>

### Usage with Pages

When you have a [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory, you need to use the [`<NuxtPage>`](/docs/4.x/api/components/nuxt-page) component to display the current page:

```vue [app/app.vue]
<template>
  <NuxtPage />
</template>
```

You can also define the common structure of your application directly in `app.vue`. This is useful when you want to include global elements such as a header or footer:

```vue [app/app.vue]
<template>
  <header>
    Header content
  </header>
  <NuxtPage />
  <footer>
    Footer content
  </footer>
</template>
```

<note>

Remember that `app.vue` acts as the main component of your Nuxt application. Anything you add to it (JS and CSS) will be global and included in every page.

</note>

<read-more to="/docs/4.x/directory-structure/app/pages">

Learn more about how to structure your pages using the `app/pages/` directory.

</read-more>

### Usage with Layouts

When your application requires different layouts for different pages, you can use the `app/layouts/` directory with the [`<NuxtLayout>`](/docs/4.x/api/components/nuxt-layout) component. This allows you to define multiple layouts and apply them per page.

```vue [app/app.vue]
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>
```

<read-more to="/docs/4.x/directory-structure/app/layouts">

Learn more about how to structure your layouts using the `app/layouts/` directory.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/assets.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/assets.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/assets.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/assets.md

# Assets

> Nuxt offers two options for your assets.

Nuxt uses two directories to handle assets like stylesheets, fonts or images.

- The [`public/`](/docs/4.x/directory-structure/public) directory content is served at the server root as-is.
- The [`app/assets/`](/docs/4.x/directory-structure/app/assets) directory contains by convention every asset that you want the build tool (Vite or webpack) to process.

## Public Directory

The [`public/`](/docs/4.x/directory-structure/public) directory is used as a public server for static assets publicly available at a defined URL of your application.

You can get a file in the [`public/`](/docs/4.x/directory-structure/public) directory from your application's code or from a browser by the root URL `/`.

### Example

For example, referencing an image file in the `public/img/` directory, available at the static URL `/img/nuxt.png`:

```vue [app/app.vue]
<template>
  <img
    src="/img/nuxt.png"
    alt="Discover Nuxt"
  >
</template>
```

## Assets Directory

Nuxt uses [Vite](https://vite.dev/guide/assets) (default) or [webpack](https://webpack.js.org/guides/asset-management/) to build and bundle your application. The main function of these build tools is to process JavaScript files, but they can be extended through [plugins](https://vite.dev/plugins/) (for Vite) or [loaders](https://webpack.js.org/loaders/) (for webpack) to process other kinds of assets, like stylesheets, fonts or SVGs. This step transforms the original file, mainly for performance or caching purposes (such as stylesheet minification or browser cache invalidation).

By convention, Nuxt uses the [`app/assets/`](/docs/4.x/directory-structure/app/assets) directory to store these files but there is no auto-scan functionality for this directory, and you can use any other name for it.

In your application's code, you can reference a file located in the [`app/assets/`](/docs/4.x/directory-structure/app/assets) directory by using the `~/assets/` path.

### Example

For example, referencing an image file that will be processed if a build tool is configured to handle this file extension:

```vue [app/app.vue]
<template>
  <img
    src="~/assets/img/nuxt.png"
    alt="Discover Nuxt"
  >
</template>
```

<note>

Nuxt won't serve files in the [`app/assets/`](/docs/4.x/directory-structure/app/assets) directory at a static URL like `/assets/my-file.png`. If you need a static URL, use the [`public/`](/docs/4.x/getting-started/assets#public-directory) directory.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/auto-imports.md

# Source: https://nuxt.com/raw/docs/3.x/examples/features/auto-imports.md

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/auto-imports.md

# Source: https://nuxt.com/raw/docs/4.x/migration/auto-imports.md

# Source: https://nuxt.com/raw/docs/4.x/examples/features/auto-imports.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/auto-imports.md

# Auto-imports

> Nuxt auto-imports components, composables, helper functions and Vue APIs.

Nuxt auto-imports components, composables and [Vue.js APIs](https://vuejs.org/api/) to use across your application without explicitly importing them.

```vue [app/app.vue]twoslash
<script setup lang="ts">
const count = ref(1) // ref is auto-imported
</script>
```

Thanks to its opinionated directory structure, Nuxt can auto-import your [`app/components/`](/docs/4.x/directory-structure/app/components), [`app/composables/`](/docs/4.x/directory-structure/app/composables) and [`app/utils/`](/docs/4.x/directory-structure/app/utils).

Contrary to a classic global declaration, Nuxt preserves typings, IDEs completions and hints, and **only includes what is used in your production code**.

<note>

In the docs, every function that is not explicitly imported is auto-imported by Nuxt and can be used as-is in your code. You can find a reference for auto-imported components, composables and utilities in the [API section](/docs/4.x/api).

</note>

<note>

In the [`server`](/docs/4.x/directory-structure/server) directory, Nuxt auto-imports exported functions and variables from `server/utils/`.

</note>

<note>

You can also auto-import functions exported from custom folders or third-party packages by configuring the [`imports`](/docs/4.x/api/nuxt-config#imports) section of your `nuxt.config` file.

</note>

## Built-in Auto-imports

Nuxt auto-imports functions and composables to perform [data fetching](/docs/4.x/getting-started/data-fetching), get access to the [app context](/docs/4.x/api/composables/use-nuxt-app) and [runtime config](/docs/4.x/guide/going-further/runtime-config), manage [state](/docs/4.x/getting-started/state-management) or define components and plugins.

```vuetwoslash
<script setup lang="ts">
/* useFetch() is auto-imported */
const { data, refresh, status } = await useFetch('/api/hello')
</script>
```

Vue exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hooks and helpers that are auto-imported by Nuxt.

```vuetwoslash
<script setup lang="ts">
/* ref() and computed() are auto-imported */
const count = ref(1)
const double = computed(() => count.value * 2)
</script>
```

### Vue and Nuxt Composables

When you are using the built-in Composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right *context*.

During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in the same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components.

That means that (with very few exceptions) you cannot use them outside a Nuxt plugin, Nuxt route middleware or Vue setup function. On top of that, you must use them synchronously - that is, you cannot use `await` before calling a composable, except within `<script setup>` blocks, within the setup function of a component declared with `defineNuxtComponent`, in `defineNuxtPlugin` or in `defineNuxtRouteMiddleware`, where we perform a transform to keep the synchronous context even after the `await`.

If you get an error message like `Nuxt instance is unavailable` then it probably means you are calling a Nuxt composable in the wrong place in the Vue or Nuxt lifecycle.

<video-accordion title="Watch a video from Alexander Lichter about avoiding the 'Nuxt instance is unavailable' error" video-id="ofuKRZLtOdY">



</video-accordion>

<tip>

When using a composable that requires the Nuxt context inside a non-SFC component, you need to wrap your component with `defineNuxtComponent` instead of `defineComponent`

</tip>

<read-more to="/docs/4.x/guide/going-further/experimental-features#asynccontext" icon="i-lucide-star">

Checkout the `asyncContext` experimental feature to use Nuxt composables in async functions.

</read-more>

<read-more to="https://github.com/nuxt/nuxt/issues/14269#issuecomment-1397352832" target="_blank">

See the full explanation in this GitHub comment.

</read-more>

**Example of breaking code:**

```ts [composables/example.ts]twoslash
// trying to access runtime config outside a composable
const config = useRuntimeConfig()

export const useMyComposable = () => {
  // accessing runtime config here
}
```

**Example of working code:**

```ts [composables/example.ts]twoslash
export const useMyComposable = () => {
  // Because your composable is called in the right place in the lifecycle,
  // useRuntimeConfig will work here
  const config = useRuntimeConfig()

  // ...
}
```

## Directory-based Auto-imports

Nuxt directly auto-imports files created in defined directories:

- `app/components/` for [Vue components](/docs/4.x/directory-structure/app/components).
- `app/composables/` for [Vue composables](/docs/4.x/directory-structure/app/composables).
- `app/utils/` for helper functions and other utilities.

<link-example to="/docs/4.x/examples/features/auto-imports">



</link-example>

<warning>

**Auto-imported ref and computed won't be unwrapped in a component <template>.** <br />


This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals#caveat-when-unwrapping-in-templates).

</warning>

### Explicit Imports

Nuxt exposes every auto-import with the `#imports` alias that can be used to make the import explicit if needed:

```vue
<script setup lang="ts">
import { computed, ref } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>
```

### Disabling Auto-imports

If you want to disable auto-importing composables and utilities, you can set `imports.autoImport` to `false` in the `nuxt.config` file.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})
```

This will disable auto-imports completely but it's still possible to use [explicit imports](/docs/4.x/guide/concepts/auto-imports#explicit-imports) from `#imports`.

### Partially Disabling Auto-imports

If you want framework-specific functions like `ref` to remain auto-imported but wish to disable auto-imports for your own code (e.g., custom composables), you can set the `imports.scan` option to `false` in your `nuxt.config.ts` file:

```ts
export default defineNuxtConfig({
  imports: {
    scan: false,
  },
})
```

With this configuration:

- Framework functions like `ref`, `computed`, or `watch` will still work without needing manual imports.
- Custom code, such as composables, will need to be manually imported in your files.

<warning>

**Caution:** This setup has certain limitations:

- If you structure your project with layers, you will need to explicitly import the composables from each layer, rather than relying on auto-imports.
- This breaks the layer system’s override feature. If you use `imports.scan: false`, ensure you understand this side-effect and adjust your architecture accordingly.

</warning>

## Auto-imported Components

Nuxt also automatically imports components from your `~/components` directory, although this is configured separately from auto-importing composables and utility functions.

<read-more to="/docs/4.x/directory-structure/app/components">



</read-more>

To disable auto-importing components from your own `~/components` directory, you can set `components.dirs` to an empty array (though note that this will not affect components added by modules).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  components: {
    dirs: [],
  },
})
```

## Auto-import from Third-Party Packages

Nuxt also allows auto-importing from third-party packages.

<tip>

If you are using the Nuxt module for that package, it is likely that the module has already configured auto-imports for that package.

</tip>

For example, you could enable the auto-import of the `useI18n` composable from the `vue-i18n` package like this:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  imports: {
    presets: [
      {
        from: 'vue-i18n',
        imports: ['useI18n'],
      },
    ],
  },
})
```

<video-accordion title="Watch a video from Alexander Lichter on how to easily set up custom auto imports" video-id="FT2LQJ2NvVI">



</video-accordion>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/autoimports.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/autoimports.md

# Auto-imports

> Nuxt Kit provides a set of utilities to help you work with auto-imports. These functions allow you to register your own utils, composables and Vue APIs.

Nuxt auto-imports helper functions, composables and Vue APIs to use across your application without explicitly importing them. Based on the directory structure, every Nuxt application can also use auto-imports for its own composables and plugins.

With Nuxt Kit you can also add your own auto-imports. `addImports` and `addImportsDir` allow you to add imports to the Nuxt application. `addImportsSources` allows you to add listed imports from 3rd party packages to the Nuxt application.

These utilities are powered by [`unimport`](https://github.com/unjs/unimport), which provides the underlying auto-import mechanism used in Nuxt.

<note>

These functions are designed for registering your own utils, composables and Vue APIs. For pages, components and plugins, please refer to the specific sections: [Pages](/docs/4.x/api/kit/pages), [Components](/docs/4.x/api/kit/components), [Plugins](/docs/4.x/api/kit/plugins).

</note>

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/expanding-nuxt-s-auto-imports?friend=nuxt">

Watch Vue School video about Auto-imports Nuxt Kit utilities.

</tip>

## `addImports`

Add imports to the Nuxt application. It makes your imports available in the Nuxt app context without the need to import them manually.

<tip>

To add imports for the Nitro server context, refer to the [`addServerImports`](/docs/4.x/api/kit/nitro#addserverimports) function.

</tip>

### Usage

```tstwoslash
import { addImports, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const names = [
      'useStoryblok',
      'useStoryblokApi',
      'useStoryblokBridge',
      'renderRichText',
      'RichTextSchema',
    ]

    names.forEach(name =>
      addImports({ name, as: name, from: '@storyblok/vue' }),
    )
  },
})
```

### Type

```ts
function addImports (imports: Import | Import[]): void
```

### Parameters

`imports`: An object or an array of objects with the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Import name to be detected.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Module specifier to import from.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        priority
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Priority of the import; if multiple imports have the same name, the one with the highest priority will be used.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        disabled
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If this import is disabled.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meta
      </code>
    </td>
    
    <td>
      <code>
        Record<string, any>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Metadata of the import.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If this import is a pure type import.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        typeFrom
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Use this as the <code>
        from
      </code>
      
       value when generating type declarations.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        as
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Import as this name.
    </td>
  </tr>
</tbody>
</table>

## `addImportsDir`

Add imports from a directory to the Nuxt application. It will automatically import all files from the directory and make them available in the Nuxt application without the need to import them manually.

### Usage

```tstwoslash
import { addImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: '@vueuse/motion',
    configKey: 'motion',
  },
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)
    addImportsDir(resolver.resolve('./runtime/composables'))
  },
})
```

### Type

```ts
function addImportsDir (dirs: string | string[], options?: { prepend?: boolean }): void
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dirs
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          string[]
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      A string or an array of strings with the path to the directory to import from.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          {
        </span>
        
        <span class="sZSNi">
          prepend
        </span>
        
        <span class="sDfIl">
          ?:
        </span>
        
        <span class="sZSNi">
          boolean
        </span>
        
        <span class="sDfIl">
          }
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Options to pass to the import. If <code>
        prepend
      </code>
      
       is set to <code>
        true
      </code>
      
      , the imports will be prepended to the list of imports.
    </td>
  </tr>
</tbody>
</table>

## `addImportsSources`

Add listed imports to the Nuxt application.

### Usage

```tstwoslash
import { addImportsSources, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addImportsSources({
      from: 'h3',
      imports: [
        'defineEventHandler',
        'getQuery',
        'getRouterParams',
        'readBody',
        'sendRedirect',
      ],
    })
  },
})
```

### Type

```ts
function addImportsSources (importSources: ImportSource | ImportSource[]): void
```

### Parameters

**importSources**: An object or an array of objects with the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Module specifier to import from.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        imports
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          PresetImport
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          ImportSource[]
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      An object or an array of objects, which can be import names, import objects or import sources.
    </td>
  </tr>
</tbody>
</table>

---

# Source: https://nuxt.com/raw/deploy/aws-amplify.md

# AWS Amplify

> Deploy your Nuxt Application to AWS Amplify infrastructure.

<tip>

**Zero Configuration ✨**

<br />

Integration with AWS Amplify is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

## Setup

1. Login to the [AWS Amplify Hosting Console](https://console.aws.amazon.com/amplify/?trk=01c5a476-5997-4e6a-88b9-fd0a0a5bbe34&sc_channel=el)
2. Click on "Get Started" > Amplify Hosting (Host your web app)
3. Select and authorize access to your Git repository provider and select the main branch
4. Choose a name for your app, make sure build settings are auto-detected and optionally set requirement environment variables under the advanced section
5. Optionally, select Enable SSR logging to enable server-side logging to your Amazon CloudWatch account
6. Confirm configuration and click on "Save and Deploy"

## Learn more

<read-more target="_blank" to="https://www.youtube.com/watch?v=CAk5_XGkOG4">

Watch an Amplify Hosting tutorial with Nuxt

</read-more>

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/aws-amplify">

Head over **Nitro documentation** to learn more about the aws-amplify deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/deploy/azure.md

# Azure

> Deploy your Nuxt Application to Azure infrastructure.

## Azure Static Web Apps

<tip>

**Zero Configuration ✨**

<br />

Integration with Azure Static Web Apps provider is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

Azure Static Web Apps are designed to be deployed continuously in a [GitHub Actions workflow](https://docs.microsoft.com/en-us/azure/static-web-apps/github-actions-workflow). By default, Nuxt will detect this deployment environment to enable the `azure` preset.

### Local preview

Install [Azure Functions Core Tools](https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local) if you want to test locally.

You can invoke a development environment to preview before deploying.

```bash [Terminal]
npx nuxi build --preset=azure
npx @azure/static-web-apps-cli start .output/public --api-location .output/server
```

### Configuration

Azure Static Web Apps are [configured](https://learn.microsoft.com/en-us/azure/static-web-apps/configuration) using the `staticwebapp.config.json` file.

Nuxt automatically generates this configuration file whenever the application is built with the `azure` preset.

It adds the following properties based on the following criteria:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Criteria
    </th>
    
    <th>
      Default
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        <a href="https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#platform" rel="nofollow">
          platform.apiRuntime
        </a>
      </strong>
    </td>
    
    <td>
      Will automatically set to <code>
        node:16
      </code>
      
       or <code>
        node:14
      </code>
      
       depending on your package configuration.
    </td>
    
    <td>
      <code>
        node:16
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        <a href="https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#fallback-routes" rel="nofollow">
          navigationFallback.rewrite
        </a>
      </strong>
    </td>
    
    <td>
      Is always <code>
        /api/server
      </code>
    </td>
    
    <td>
      <code>
        /api/server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        <a href="https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#routes" rel="nofollow">
          routes
        </a>
      </strong>
    </td>
    
    <td>
      All prerendered routes are added. Additionally, if you do not have an <code>
        index.html
      </code>
      
       file an empty one is created for you for compatibility purposes and also requests to <code>
        /index.html
      </code>
      
       are redirected to the root directory which is handled by <code>
        /api/server
      </code>
      
      .
    </td>
    
    <td>
      <code>
        []
      </code>
    </td>
  </tr>
</tbody>
</table>

### Custom Configuration

You can alter the generated configuration using `azure.config` option. For instance, if you wanted to specify a Node runtime for your Azure Functions, edit your `nuxt.config.ts` file to the following:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  // ...
  nitro: {
    azure: {
      config: {
        // ...
        platform: {
          apiRuntime: 'node:18'
        }
      }
    }
  }
})
```

Custom routes will be added and matched first. In the case of a conflict (determined if an object has the same route property), custom routes will override generated ones.

### Deploy from CI/CD via GitHub Actions

When you link your GitHub repository to Azure Static Web Apps, a workflow file is added to the repository.

When you are asked to select your framework, select custom and provide the following information:

<table>
<thead>
  <tr>
    <th>
      Input
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        app_location
      </strong>
    </td>
    
    <td>
      '/'
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        api_location
      </strong>
    </td>
    
    <td>
      '.output/server'
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        output_location
      </strong>
    </td>
    
    <td>
      '.output/public'
    </td>
  </tr>
</tbody>
</table>

If you miss this step, you can always find the build configuration section in your workflow and update the build configuration:

```yaml [.github/workflows/azure-static-web-apps-<RANDOM_NAME>.yml]
###### Repository/Build Configurations ######
app_location: '/'
api_location: '.output/server'
output_location: '.output/public'
###### End of Repository/Build Configurations ######
```

<callout>

That's it! Now Azure Static Web Apps will automatically deploy your Nitro-powered application on push.

</callout>

If you are using `runtimeConfig`, you will likely want to configure the corresponding [environment variables on Azure](https://docs.microsoft.com/en-us/azure/static-web-apps/application-settings).

## More options

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/azure">

Learn about the other Azure deployment presets on Nitro documentation.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/best-practices.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/best-practices.md

# Follow Best Practices

> Build performant and maintainable Nuxt modules with these guidelines.

With great power comes great responsibility. While modules are powerful, here are some best practices to keep in mind while authoring modules to keep applications performant and developer experience great.

## Handle Async Setup

As we've seen, Nuxt modules can be asynchronous. For example, you may want to develop a module that needs fetching some API or calling an async function.

However, be careful with asynchronous behaviors as Nuxt will wait for your module to setup before going to the next module and starting the development server, build process, etc. Prefer deferring time-consuming logic to Nuxt hooks.

<warning>

If your module takes more than **1 second** to setup, Nuxt will emit a warning about it.

</warning>

## Prefix Your Exports

Nuxt modules should provide an explicit prefix for any exposed configuration, plugin, API, composable, component, or server route to avoid conflicts with other modules, Nuxt internals, or user-defined code.

Ideally, prefix them with your module's name. For example, if your module is called `nuxt-foo`:

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      ❌ Avoid
    </th>
    
    <th>
      ✅ Prefer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Components
    </td>
    
    <td>
      <code>
        <Button>
      </code>
      
      , <code>
        <Modal>
      </code>
    </td>
    
    <td>
      <code>
        <FooButton>
      </code>
      
      , <code>
        <FooModal>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Composables
    </td>
    
    <td>
      <code>
        useData()
      </code>
      
      , <code>
        useModal()
      </code>
    </td>
    
    <td>
      <code>
        useFooData()
      </code>
      
      , <code>
        useFooModal()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Server routes
    </td>
    
    <td>
      <code>
        /api/track
      </code>
      
      , <code>
        /api/data
      </code>
    </td>
    
    <td>
      <code>
        /api/_foo/track
      </code>
      
      , <code>
        /api/_foo/data
      </code>
    </td>
  </tr>
</tbody>
</table>

### Server Routes

This is particularly important for server routes, where common paths like `/api/auth`, `/api/login`, or `/api/user` are very likely already used by the application.

Use a unique prefix based on your module name:

- `/api/_foo/...` (using underscore prefix)
- `/_foo/...` (for non-API routes)

## Use Lifecycle Hooks

When your module needs to perform one-time setup tasks (like generating configuration files, setting up databases, or installing dependencies), use lifecycle hooks instead of running the logic in your main `setup` function.

```ts
import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
import semver from 'semver'

export default defineNuxtModule({
  meta: {
    name: 'my-database-module',
    version: '1.0.0',
  },
  async onInstall (nuxt) {
    // One-time setup: create database schema, generate config files, etc.
    await generateDatabaseConfig(nuxt.options.rootDir)
  },
  async onUpgrade (nuxt, options, previousVersion) {
    // Handle version-specific migrations
    if (semver.lt(previousVersion, '1.0.0')) {
      await migrateLegacyData()
    }
  },
  setup (options, nuxt) {
    // Regular setup logic that runs on every build
    addServerHandler({ /* ... */ })
  },
})
```

This pattern prevents unnecessary work on every build and provides a better developer experience. See the [lifecycle hooks documentation](/docs/4.x/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) for more details.

## Be TypeScript Friendly

Nuxt has first-class TypeScript integration for the best developer experience.

Exposing types and using TypeScript to develop modules benefits users even when not using TypeScript directly.

## Use ESM Syntax

Nuxt relies on native ESM. Please read [Native ES Modules](/docs/4.x/guide/concepts/esm) for more information.

## Document Your Module

Consider documenting module usage in the readme file:

- Why use this module?
- How to use this module?
- What does this module do?

Linking to the integration website and documentation is always a good idea.

## Provide a Demo

It's a good practice to make a minimal reproduction with your module and [StackBlitz](https://nuxt.new/s/v4) that you add to your module readme.

This not only provides potential users of your module a quick and easy way to experiment with the module but also an easy way for them to build minimal reproductions they can send you when they encounter issues.

## Stay Version Agnostic

Nuxt, Nuxt Kit, and other new toolings are made to have both forward and backward compatibility in mind.

Please use "X for Nuxt" instead of "X for Nuxt 3" to avoid fragmentation in the ecosystem and prefer using `meta.compatibility` to set Nuxt version constraints.

## Follow Starter Conventions

The module starter comes with a default set of tools and configurations (e.g. ESLint configuration). If you plan on open-sourcing your module, sticking with those defaults ensures your module shares a consistent coding style with other [community modules](/modules) out there, making it easier for others to contribute.

---

# Source: https://nuxt.com/raw/docs/3.x/bridge/bridge-composition-api.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/bridge-composition-api.md

# Legacy Composition API

> Learn how to migrate to Composition API with Nuxt Bridge.

Nuxt Bridge provides access to Composition API syntax. It is specifically designed to be aligned with Nuxt 3. Because of this, there are a few extra steps to take when enabling Nuxt Bridge, if you have been using the Composition API previously.

## Remove Modules

- Remove `@vue/composition-api` from your dependencies.
- Remove `@nuxtjs/composition-api` from your dependencies (and from your modules in `nuxt.config`).

## Using `@vue/composition-api`

If you have been using just `@vue/composition-api` and not `@nuxtjs/composition-api`, then things are very straightforward.

1. First, remove the plugin where you are manually registering the Composition API. Nuxt Bridge will handle this for you.```diff
- import Vue from 'vue'
- import VueCompositionApi from '@vue/composition-api'
-
- Vue.use(VueCompositionApi)
```
2. Otherwise, there is nothing you need to do. However, if you want, you can remove your explicit imports from `@vue/composition-api` and rely on Nuxt Bridge auto-importing them for you.

## Migrating from `@nuxtjs/composition-api`

Nuxt Bridge implements the Composition API slightly differently from `@nuxtjs/composition-api` and provides different composables (designed to be aligned with the composables that Nuxt 3 provides).

Because some composables have been removed and don't yet have a replacement, this will be a slightly more complicated process.

### Remove `@nuxtjs/composition-api/module` from your buildModules

You don't have to immediately update your imports yet - Nuxt Bridge will automatically provide a 'shim' for most imports you currently have, to give you time to migrate to the new, Nuxt 3-compatible composables, with the following exceptions:

- `withContext` has been removed. See [below](/docs/4.x/bridge/nuxt3-compatible-api#usecontext-and-withcontext).
- `useStatic` has been removed. There is no current replacement. Feel free to raise a discussion if you have a use case for this.
- `reqRef` and `reqSsrRef`, which were deprecated, have now been removed entirely. Follow the instructions below regarding [ssrRef](/docs/4.x/bridge/nuxt3-compatible-api#ssrref-and-shallowssrref) to replace this.

### Set `bridge.capi`

```ts
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    capi: true,
    nitro: false, // If migration to Nitro is complete, set to true
  },
})
```

For each other composable you are using from `@nuxtjs/composition-api`, follow the steps below.

### useFetch

`$fetchState` and `$fetch` have been removed.

```diff
const {
- $fetch,
- $fetchState,
+ fetch,
+ fetchState,
} = useFetch(() => { posts.value = await $fetch('/api/posts') })
```

### `defineNuxtMiddleware`

This was a type-helper stub function that is now removed.

Remove the `defineNuxtMiddleware` wrapper:

```diff
- import { defineNuxtMiddleware } from '@nuxtjs/composition-api`
- export default defineNuxtMiddleware((ctx) => {})
+ export default (ctx) => {}
```

For typescript support, you can use `@nuxt/types`:

```ts
import type { Middleware } from '@nuxt/types'

export default <Middleware> function (ctx) { }
```

### `defineNuxtPlugin`

This was a type-helper stub function that is now removed.

You may also keep using Nuxt 2-style plugins, by removing the function (as with [defineNuxtMiddleware](/docs/4.x/bridge/bridge-composition-api#definenuxtmiddleware)).

Remove the `defineNuxtPlugin` wrapper:

```diff
- import { defineNuxtPlugin } from '@nuxtjs/composition-api'
- export default defineNuxtPlugin((ctx, inject) => {})
+ export default (ctx, inject) => {}
```

For typescript support, you can use `@nuxt/types`:

```ts
import type { Plugin } from '@nuxt/types'

export default <Plugin> function (ctx, inject) {}
```

<warning>

While this example is valid, Nuxt 3 introduces a new defineNuxtPlugin function that has a slightly different signature.

</warning>

<read-more link="/docs/4.x/directory-structure/app/plugins#creating-plugins">



</read-more>

### `useRouter` and `useRoute`

Nuxt Bridge provides direct replacements for these composables via [`useRouter`](/docs/4.x/api/composables/use-router)  and `useRoute`.

The only key difference is that [`useRoute`](/docs/4.x/api/composables/use-route) no longer returns a computed property.

```diff
- import { useRouter, useRoute } from '@nuxtjs/composition-api'

  const router = useRouter()
  const route = useRoute()

- console.log(route.value.path)
+ console.log(route.path)
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/build-module.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/build-module.md

# nuxt build-module

> Nuxt command to build your Nuxt module before publishing.

```bash [Terminal]
npx nuxt build-module [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--build] [--stub] [--sourcemap] [--prepare]
```

The `build-module` command runs `@nuxt/module-builder` to generate `dist` directory within your `rootDir` that contains the full build for your **nuxt-module**.

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --build
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Build module for distribution
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --stub
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Stub dist instead of actually building it for development
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --sourcemap
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Generate sourcemaps
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --prepare
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Prepare module for local development
    </td>
  </tr>
</tbody>
</table>

<read-more icon="i-simple-icons-github" target="\_blank" to="https://github.com/nuxt/module-builder">

Read more about `@nuxt/module-builder`.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/build.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/build.md

# nuxt build

> Build your Nuxt application.

```bash [Terminal]
npx nuxt build [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--prerender] [--preset] [--dotenv] [--envName] [-e, --extends=<layer-name>]
```

The `build` command creates a `.output` directory with all your application, server and dependencies ready for production.

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --prerender
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Build Nuxt and prerender static routes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --preset
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Nitro server preset
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --envName
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The environment to use when resolving configuration overrides (default is <code>
        production
      </code>
      
       when building, and <code>
        development
      </code>
      
       when running the dev server)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
</tbody>
</table>

<note>

This command sets `process.env.NODE_ENV` to `production`.

</note>

<note>

`--prerender` will always set the `preset` to `static`

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/builder.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/builder.md

# Builder

> Nuxt Kit provides a set of utilities to help you work with the builder. These functions allow you to extend the Vite and webpack configurations.

Nuxt have builders based on [Vite](https://github.com/nuxt/nuxt/tree/main/packages/vite) and [webpack](https://github.com/nuxt/nuxt/tree/main/packages/webpack). You can extend the config passed to each one using `extendViteConfig` and `extendWebpackConfig` functions. You can also add additional plugins via `addVitePlugin`, `addWebpackPlugin` and `addBuildPlugin`.

## `extendViteConfig`

Extends the Vite configuration. Callback function can be called multiple times, when applying to both client and server builds.

<warning>

This hook is now deprecated, and we recommend using a Vite plugin instead with a `config` hook, or — for environment-specific configuration — the `applyToEnvironment` hook.

</warning>

### Usage

```tstwoslash
import { defineNuxtModule, extendViteConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    extendViteConfig((config) => {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('cross-fetch')
    })
  },
})
```

For environment-specific configuration in Nuxt 5+, use `addVitePlugin()` instead:

```tstwoslash
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    // For global configuration (affects all environments)
    addVitePlugin(() => ({
      name: 'my-global-plugin',
      config (config) {
        // This runs before environment setup
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('cross-fetch')
      },
    }))

    // For environment-specific configuration
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      configEnvironment (name, config) {
        // This only affects the client environment
        config.optimizeDeps ||= {}
        config.optimizeDeps.include ||= []
        config.optimizeDeps.include.push('client-only-package')
      },
    }))
  },
})
```

<warning>

**Important:** The `config` hook runs before `applyToEnvironment` and modifies the global configuration. Use `configEnvironment` for environment-specific configuration changes.

</warning>

### Type

```tstwoslash
// @errors: 2391
import type { UserConfig as ViteConfig } from 'vite'
import type { ExtendViteConfigOptions } from '@nuxt/kit'
// ---cut---
function extendViteConfig (callback: ((config: ViteConfig) => void), options?: ExtendViteConfigOptions): void
```

<read-more icon="i-simple-icons-vite" target="_blank" to="https://vite.dev/config/">

Check out the Vite website for more information about its configuration.

</read-more>

### Parameters

**callback**: A callback function that will be called with the Vite configuration object.

**options**: Options to pass to the callback function. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in development mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in production mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the server bundle. <strong>
        Deprecated in Nuxt 5+.
      </strong>
      
       Use <code>
        addVitePlugin()
      </code>
      
       with <code>
        applyToEnvironment()
      </code>
      
       instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        client
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the client bundle. <strong>
        Deprecated in Nuxt 5+.
      </strong>
      
       Use <code>
        addVitePlugin()
      </code>
      
       with <code>
        applyToEnvironment()
      </code>
      
       instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be prepended to the array with <code>
        unshift()
      </code>
      
       instead of <code>
        push()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## `extendWebpackConfig`

Extends the webpack configuration. Callback function can be called multiple times, when applying to both client and server builds.

### Usage

```tstwoslash
import { defineNuxtModule, extendWebpackConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    extendWebpackConfig((config) => {
      config.module!.rules!.push({
        test: /\.txt$/,
        use: 'raw-loader',
      })
    })
  },
})
```

### Type

```tstwoslash
// @errors: 2391
import type { Configuration as WebpackConfig } from 'webpack'
import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
// ---cut---
function extendWebpackConfig (callback: ((config: WebpackConfig) => void), options?: ExtendWebpackConfigOptions): void
```

<read-more icon="i-simple-icons-webpack" target="_blank" to="https://webpack.js.org/configuration/">

Check out webpack website for more information about its configuration.

</read-more>

### Parameters

**callback**: A callback function that will be called with the webpack configuration object.

**options**: Options to pass to the callback function. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in development mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in production mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the server bundle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        client
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the client bundle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be prepended to the array with <code>
        unshift()
      </code>
      
       instead of <code>
        push()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## `addVitePlugin`

Append Vite plugin to the config.

<warning>

In Nuxt 5+, plugins registered with `server: false` or `client: false` options will not have their `config` or `configResolved` hooks called. Instead, use the `applyToEnvironment()` method instead for environment-specific plugins.

</warning>

### Usage

```tstwoslash
// @errors: 2307
// ---cut---
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
import { svg4VuePlugin } from 'vite-plugin-svg4vue'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-svg-icons',
    configKey: 'nuxtSvgIcons',
  },
  defaults: {
    svg4vue: {
      assetsDirName: 'assets/icons',
    },
  },
  setup (options) {
    addVitePlugin(svg4VuePlugin(options.svg4vue))

    // or, to add a vite plugin to only one environment
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      // ... rest of your client-only plugin
    }))
  },
})
```

### Type

```tstwoslash
// @errors: 2391
import type { Plugin as VitePlugin } from 'vite'
import type { ExtendViteConfigOptions } from '@nuxt/kit'
// ---cut---
function addVitePlugin (pluginOrGetter: VitePlugin | VitePlugin[] | (() => VitePlugin | VitePlugin[]), options?: ExtendViteConfigOptions): void
```

<tip>

See [Vite website](https://vite.dev/guide/api-plugin) for more information about Vite plugins. You can also use [this repository](https://github.com/vitejs/awesome-vite#plugins) to find a plugin that suits your needs.

</tip>

### Parameters

**pluginOrGetter**: A Vite plugin instance or an array of Vite plugin instances. If a function is provided, it must return a Vite plugin instance or an array of Vite plugin instances. The function can also be async or return a Promise, which is useful for lazy-loading plugins:

```tstwoslash
// @errors: 2307
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    // Lazy load the plugin - only imported when the build actually runs
    addVitePlugin(() => import('my-vite-plugin').then(r => r.default()))
  },
})
```

**options**: Options to pass to the callback function. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in development mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in production mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the server bundle. <strong>
        Deprecated in Nuxt 5+.
      </strong>
      
       Use <code>
        applyToEnvironment()
      </code>
      
       instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        client
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the client bundle. <strong>
        Deprecated in Nuxt 5+.
      </strong>
      
       Use <code>
        applyToEnvironment()
      </code>
      
       instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be prepended to the array with <code>
        unshift()
      </code>
      
       instead of <code>
        push()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## `addWebpackPlugin`

Append webpack plugin to the config.

### Usage

```ts
import EslintWebpackPlugin from 'eslint-webpack-plugin'
import { addWebpackPlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-eslint',
    configKey: 'eslint',
  },
  defaults: nuxt => ({
    include: [`${nuxt.options.srcDir}/**/*.{js,jsx,ts,tsx,vue}`],
    lintOnStart: true,
  }),
  setup (options, nuxt) {
    const webpackOptions = {
      ...options,
      context: nuxt.options.srcDir,
      files: options.include,
      lintDirtyModulesOnly: !options.lintOnStart,
    }
    addWebpackPlugin(new EslintWebpackPlugin(webpackOptions), { server: false })
  },
})
```

### Type

```tstwoslash
// @errors: 2391
import type { WebpackPluginInstance } from 'webpack'
import type { ExtendWebpackConfigOptions } from '@nuxt/kit'
// ---cut---
function addWebpackPlugin (pluginOrGetter: WebpackPluginInstance | WebpackPluginInstance[] | (() => WebpackPluginInstance | WebpackPluginInstance[]), options?: ExtendWebpackConfigOptions): void
```

<tip>

See [webpack website](https://webpack.js.org/concepts/plugins/) for more information about webpack plugins. You can also use [this collection](https://webpack.js.org/awesome-webpack/#webpack-plugins) to find a plugin that suits your needs.

</tip>

### Parameters

**pluginOrGetter**: A webpack plugin instance or an array of webpack plugin instances. If a function is provided, it must return a webpack plugin instance or an array of webpack plugin instances. The function can also be async or return a Promise, enabling lazy-loading of plugins.

**options**: Options to pass to the callback function. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in development mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in production mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the server bundle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        client
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the client bundle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be prepended to the array with <code>
        unshift()
      </code>
      
       instead of <code>
        push()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## `addBuildPlugin`

Builder-agnostic version of `addVitePlugin` and `addWebpackPlugin`. It will add the plugin to both Vite and webpack configurations if they are present.

### Type

```tstwoslash
// @errors: 2391
import type { ExtendConfigOptions } from '@nuxt/kit'
import type { Plugin as VitePlugin } from 'vite'
import type { WebpackPluginInstance } from 'webpack'
import type { RspackPluginInstance } from '@rspack/core'

interface AddBuildPluginFactory {
  vite?: () => VitePlugin | VitePlugin[]
  webpack?: () => WebpackPluginInstance | WebpackPluginInstance[]
  rspack?: () => RspackPluginInstance | RspackPluginInstance[]
}
// ---cut---
function addBuildPlugin (pluginFactory: AddBuildPluginFactory, options?: ExtendConfigOptions): void
```

### Parameters

**pluginFactory**: A factory function that returns an object with `vite` and/or `webpack` properties. These properties must be functions that return a Vite plugin instance or an array of Vite plugin instances and/or a webpack plugin instance or an array of webpack plugin instances.

**options**: Options to pass to the callback function. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in development mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        build
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building in production mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the server bundle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        client
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be called when building the client bundle.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        prepend
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the callback function will be prepended to the array with <code>
        unshift()
      </code>
      
       instead of <code>
        push()
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

---

# Source: https://nuxt.com/raw/blog/building-a-feedback-widget.md

# Building a Privacy-First Feedback Widget

> A lightweight, privacy-focused widget to gather your feedback on Nuxt documentation, built with Drizzle, NuxtHub database and Motion Vue.

Documentation is at the heart of the Nuxt developer experience. To continuously improve it, we needed a simple and effective way to collect user feedback directly on each page. Here's how we designed and implemented our feedback widget, drawing inspiration from Plausible's privacy-first approach.

## Why a feedback widget?

Currently, users can provide feedback on our documentation by creating GitHub issues or contacting us directly. While these channels are valuable and remain important, they require users to leave their current context and take several steps to share their thoughts.

We wanted something different:

- **Contextual**: Directly integrated into each documentation page
- **Frictionless**: Maximum 2 clicks to provide feedback
- **Privacy-respecting**: No personal tracking, GDPR compliant by design

<video :controls="true" className="rounded-lg" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/so_0/v1749746517/nuxt/nuxt-feedback_lh6zyg.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1749746517/nuxt/nuxt-feedback_lh6zyg.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1749746517/nuxt/nuxt-feedback_lh6zyg.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1749746517/nuxt/nuxt-feedback_lh6zyg.ogg" type="video/ogg" />
</video>

## Technical architecture

Our solution consists of three main components:

### 1. Frontend with Motion animations

The interface combines Vue 3's Composition API with [Motion for Vue](https://motion.dev/docs/vue) to create an engaging user experience. The widget uses layout animations for smooth state transitions and spring physics for natural feedback. The `useFeedback` composable handles all state management and automatically resets when users navigate between pages.

Here's the success state animation, for example:

```vue
<template>
  <!-- ... -->
  <motion.div
    v-if="isSubmitted"
    key="success"
    :initial="{ opacity: 0, scale: 0.95 }"
    :animate="{ opacity: 1, scale: 1 }"
    :transition="{ duration: 0.3 }"
    class="flex items-center gap-3 py-2"
    role="status"
    aria-live="polite"
    aria-label="Feedback submitted successfully"
  >
    <motion.div
      :initial="{ scale: 0 }"
      :animate="{ scale: 1 }"
      :transition="{ delay: 0.1, type: 'spring', visualDuration: 0.4 }"
      class="text-xl"
      aria-hidden="true"
    >
      ✨
    </motion.div>
    <motion.div
      :initial="{ opacity: 0, x: 10 }"
      :animate="{ opacity: 1, x: 0 }"
      :transition="{ delay: 0.2, duration: 0.3 }"
    >
      <div class="text-sm font-medium text-highlighted">
        Thank you for your feedback!
      </div>
      <div class="text-xs text-muted mt-1">
        Your input helps us improve the documentation.
      </div>
    </motion.div>
  </motion.div>
  <!-- ... -->
</template>
```

You can find the source code of the feedback widget [here](https://github.com/nuxt/nuxt.com/tree/main/app/components/Feedback.vue).

### 2. Plausible-inspired anonymization

The challenge was detecting duplicates (a user changing their mind) while preserving privacy. We took inspiration from [Plausible](https://plausible.io/)'s approach to [counting unique visitors without cookies](https://plausible.io/data-policy).

```typescript
export async function generateHash(
  today: string,
  ip: string,
  domain: string,
  userAgent: string
): Promise<string> {
  const data = `${today}+${domain}+${ip}+${userAgent}`

  const buffer = await crypto.subtle.digest(
    'SHA-1',
    new TextEncoder().encode(data)
  )

  return [...new Uint8Array(buffer)]
    .map(b => b.toString(16).padStart(2, '0'))
    .join('')
}
```

This method generates a unique daily identifier by combining:

- **IP + User-Agent**: Naturally sent with every HTTP request
- **Domain**: Enables environment isolation
- **Current date**: Forces daily rotation of identifiers

**Why is this secure?**

- IP and User-Agent are never stored in the database
- The hash changes daily, preventing long-term tracking
- Very difficult to reverse engineer original data from the hash
- GDPR compliant by design (no persistent personal data)

### 3. Database persistence with conflict handling

First, we define the schema for the feedback table and add a unique constraint on the `path` and `fingerprint` columns.

```typescript
export const feedback = sqliteTable('feedback', {
  id: integer('id').primaryKey({ autoIncrement: true }),
  rating: text('rating').notNull(),
  feedback: text('feedback'),
  path: text('path').notNull(),
  title: text('title').notNull(),
  stem: text('stem').notNull(),
  country: text('country').notNull(),
  fingerprint: text('fingerprint').notNull(),
  createdAt: integer({ mode: 'timestamp' }).notNull(),
  updatedAt: integer({ mode: 'timestamp' }).notNull()
}, table => [uniqueIndex('path_fingerprint_idx').on(table.path, table.fingerprint)])
```

Then, in the server, we use [Drizzle](https://orm.drizzle.team/docs/get-started) with an `UPSERT` strategy:

```typescript
await drizzle.insert(tables.feedback).values({
  rating: data.rating,
  feedback: data.feedback || null,
  path: data.path,
  title: data.title,
  stem: data.stem,
  country: event.context.cf?.country || 'unknown',
  fingerprint,
  createdAt: new Date(),
  updatedAt: new Date()
}).onConflictDoUpdate({
  target: [tables.feedback.path, tables.feedback.fingerprint],
  set: {
    rating: data.rating,
    feedback: data.feedback || null,
    country,
    updatedAt: new Date()
  }
})
```

This approach enables updates if the user changes their mind within the day, creation for new feedback, and automatic deduplication per page and user.

You can find the source code of the server side [here](https://github.com/nuxt/nuxt.com/tree/main/server).

## Shared types for consistency

We use Zod for runtime validation and type generation:

```typescript
export const FEEDBACK_RATINGS = [
  'very-helpful',
  'helpful', 
  'not-helpful',
  'confusing'
] as const

export const feedbackSchema = z.object({
  rating: z.enum(FEEDBACK_RATINGS),
  feedback: z.string().optional(),
  path: z.string(),
  title: z.string(),
  stem: z.string()
})

export type FeedbackInput = z.infer<typeof feedbackSchema>
```

This approach ensures consistency across frontend, API, and database.

## What's next

The widget is now live across all documentation pages. Our next step is building an admin interface within nuxt.com to analyze feedback patterns and identify pages that need improvement. This will help us continuously enhance the documentation quality based on real user feedback.

The complete source code is available on [GitHub](https://github.com/nuxt/nuxt.com) for inspiration and contributions!

---

# Source: https://nuxt.com/raw/blog/building-nuxt-mcp.md

# Building an MCP Server for Nuxt

> How we built the Nuxt MCP server to enable AI assistants to access our documentation through structured data and composable tools.

AI assistants are becoming an increasingly important part of the developer experience. To help them provide accurate, up-to-date information about Nuxt, we built an MCP server that exposes our documentation, blog posts, and deployment guides in a structured way. Here's how we did it with the [Nuxt MCP Toolkit](https://mcp-toolkit.nuxt.dev), and how you can build your own.

<callout icon="i-lucide-bot">

Want to test the Nuxt MCP server? Jump to the [Nuxt MCP Server Documentation](/docs/4.x/guide/ai/mcp).

</callout>

## What is MCP and why did we build it?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to securely access data and tools. Think of it as an API specifically designed for AI assistants: rather than returning HTML or generic JSON, it provides structured, semantic data that LLMs can easily understand and use.

MCP defines three main primitives:

- **Resources**: Allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a URI.
- **Tools**: Enable AI models to interact with external systems and perform operations (like searching or API calls)
- **Prompts**: Reusable prompt templates with arguments that can be invoked by users

### Why MCP over RAG?

We've observed that AI assistants using MCP servers provide **significantly better responses** than traditional RAG (Retrieval-Augmented Generation) approaches:

- **Structured data in, structured data out**: Tools accept well-defined parameters and return typed data that prevents hallucinations
- **Composable tools**: AI assistants can chain tools together, using the output of one tool as input for another (e.g., search for a topic, then fetch the full content)
- **Faster and more accurate**: No need to process and chunk large documents at query time
- **Always up-to-date**: Direct access to your content layer without reindexing
- **Context-aware navigation**: The AI can intelligently navigate relationships between content

Both [Nuxt](https://nuxt.com/mcp) and [Nuxt UI](https://ui.nuxt.com/mcp) now have MCP servers with similar architectures, making it easier for AI assistants to help developers with these frameworks.

## Technical architecture

Our MCP server is built directly into nuxt.com using the [Nuxt MCP Toolkit](https://mcp-toolkit.nuxt.dev) module. The module provides automatic discovery of tools, resources, and prompts from your server directory:

```text
nuxt.com/
├── server/
│   └── mcp/
│       ├── tools/
│       │   ├── list-documentation-pages.ts
│       │   ├── get-documentation-page.ts
│       │   └── ...
│       ├── resources/
│       │   ├── nuxt-documentation-pages.ts
│       │   └── ...
│       └── prompts/
│           ├── find-documentation-for-topic.ts
│           └── ...
└── nuxt.config.ts
```

The architecture is straightforward: you define your tools, resources, and prompts as individual files, and the module automatically registers them and exposes an HTTP endpoint for MCP clients to connect. No manual server setup, no transport configuration, just create files in the right directories and they're ready to use.

## Implementation deep dive

### Module setup

Getting started is as simple as adding the module to your Nuxt config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'Nuxt',
  }
})
```

That's it. The module will automatically scan your `server/mcp/` directory and register everything it finds.

### Tools: Operations for AI models

Tools enable language models to interact with external systems by accepting parameters and performing operations. Here's how we implemented our `list_documentation_pages` tool:

```ts [server/mcp/tools/list-documentation-pages.ts]
import { z } from 'zod'
import { queryCollection } from '@nuxt/content/server'

export default defineMcpTool({
  description: `Lists all available Nuxt documentation pages with their categories and basic information.

WHEN TO USE: Use this tool when you need to EXPLORE or SEARCH for documentation about a topic but don't know the exact page path.

WHEN NOT TO USE: If you already know the specific page path, use get_documentation_page directly instead.`,
  inputSchema: {
    version: z.enum(['3.x', '4.x', 'all']).optional().default('4.x').describe('Documentation version to fetch')
  },
  cache: '1h',
  async handler({ version }) {
    const event = useEvent()

    const allDocs = await queryCollection(event, 'docsv4')
      .select('title', 'path', 'description')
      .all()

    return jsonResult(allDocs.map(doc => ({
      title: doc.title,
      path: doc.path,
      description: doc.description,
      url: `https://nuxt.com${doc.path}`
    })))
  }
})
```

Notice a few key things:

- **defineMcpTool** is auto-imported, no need to import it manually
- **inputSchema** uses Zod for parameter validation
- **cache: '1h'** enables built-in response caching
- **jsonResult()** is a helper that formats the response correctly

The tool name is automatically derived from the filename (`list-documentation-pages.ts` becomes `list_documentation_pages`).

### Resources: Context for language models

Resources allow servers to share data that provides context to language models, such as files, database schemas, or application-specific information. Each resource is uniquely identified by a URI.

The simplest way to expose a file is using the `file` property, which automatically handles URI generation, MIME type detection, and file reading:

```ts [server/mcp/resources/readme.ts]
export default defineMcpResource({
  name: 'readme',
  description: 'Project README file',
  file: 'README.md' // Relative to project root
})
```

For dynamic resources, you can use a custom handler:

```ts [server/mcp/resources/nuxt-documentation-pages.ts]
import { queryCollection } from '@nuxt/content/server'

export default defineMcpResource({
  uri: 'resource://nuxt-com/documentation-pages',
  description: 'Complete list of available Nuxt documentation pages (defaults to v4.x)',
  cache: '1h',
  async handler(uri: URL) {
    const event = useEvent()

    const allDocs = await queryCollection(event, 'docsv4')
      .select('title', 'path', 'description')
      .all()

    const result = allDocs.map(doc => ({
      title: doc.title,
      path: doc.path,
      description: doc.description,
      version: '4.x',
      url: `https://nuxt.com${doc.path}`
    }))

    return {
      contents: [{
        uri: uri.href,
        mimeType: 'application/json',
        text: JSON.stringify(result, null, 2)
      }]
    }
  }
})
```

Unlike tools which are model-controlled, resources are application-driven, the host application determines how to incorporate them based on user needs, such as through UI elements for explicit selection or automatic context inclusion.

### Prompts: Reusable templates

Prompts are reusable templates with arguments that users can invoke. They return a conversation format that guides the AI through specific workflows:

```ts [server/mcp/prompts/find-documentation-for-topic.ts]
import { z } from 'zod'
import { queryCollection } from '@nuxt/content/server'

export default defineMcpPrompt({
  description: 'Find the best Nuxt documentation for a specific topic or feature',
  inputSchema: {
    topic: z.string().describe('Describe what you want to learn about'),
    version: z.enum(['3.x', '4.x']).optional().describe('Documentation version to search')
  },
  async handler({ topic, version = '4.x' }) {
    const event = useEvent()
    const docsVersion = version === '4.x' ? 'docsv4' : 'docsv3'

    const allDocs = await queryCollection(event, docsVersion)
      .select('title', 'path', 'description')
      .all()

    const allPages = allDocs?.map(doc => ({
      title: doc.title,
      path: doc.path,
      description: doc.description,
      url: `https://nuxt.com${doc.path}`
    })) || []

    return {
      messages: [{
        role: 'user' as const,
        content: {
          type: 'text' as const,
          text: `Help me find the best Nuxt documentation for this topic: "${topic}". Here are all available documentation pages: ${JSON.stringify(allPages, null, 2)}`
        }
      }]
    }
  }
})
```

Prompts differ from tools in that they are user-invoked and return conversation messages, while tools are model-controlled and return structured data.

### Built-in helpers

The module provides several auto-imported helpers to simplify common patterns:

- **defineMcpTool**, **defineMcpResource**, **defineMcpPrompt**: Define your MCP primitives
- **jsonResult(data)**: Format a JSON response for tools
- **errorResult(message)**: Return an error response from tools

### Using Nuxt server utilities

To use Nuxt server utilities like `useEvent()` in your handlers, enable `asyncContext` in your Nuxt config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    asyncContext: true
  }
})
```

Then you can access the H3 event and use Nuxt server composables like `queryCollection` from [Nuxt Content](https://content.nuxt.com).

## Building your own MCP server

Ready to build an MCP server for your own application? With the Nuxt MCP Toolkit, it takes just a few minutes.

### 1. Install the module

```bash [Terminal]
npx nuxi module add mcp-toolkit
```

### 2. Configure the module

Add basic configuration to your Nuxt config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/mcp-toolkit'],
  mcp: {
    name: 'my-app'
  }
})
```

### 3. Create your first tool

Create a file in `server/mcp/tools/`:

```ts [server/mcp/tools/search.ts]
import { z } from 'zod'

export default defineMcpTool({
  description: 'Search through my content',
  inputSchema: {
    query: z.string().describe('Search query')
  },
  async handler({ query }) {
    // Your search logic here
    const results = await searchContent(query)
    return jsonResult(results)
  }
})
```

That's it! Your MCP server is now accessible at `https://your-domain.com/mcp`.

### 4. Add resources and prompts (optional)

You can also add resources and prompts following the same pattern:

```ts [server/mcp/resources/readme.ts]
export default defineMcpResource({
  name: 'readme',
  description: 'Project README file',
  file: 'README.md'
})
```

For more advanced configuration options, check out the [Nuxt MCP Toolkit documentation](https://mcp-toolkit.nuxt.dev).

## Get started with the Nuxt MCP server

Ready to experience the power of MCP with Nuxt? Our server is already live and provides access to all Nuxt documentation, blog posts, and deployment guides.

### Quick install for Cursor

The easiest way to get started is with Cursor's one-click installation:

<u-button color="neutral" icon="i-custom-cursor" label="Install Nuxt MCP Server in Cursor" to="cursor://anysphere.cursor-deeplink/mcp/install?name=nuxt&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbnV4dC5jb20vbWNwIn0%3D">



</u-button>

### Other AI assistants

The Nuxt MCP server works with Claude Desktop, Windsurf, Visual Studio Code, ChatGPT, and many other MCP-compatible AI assistants. For complete setup instructions for all platforms, check out our [MCP documentation](/docs/4.x/guide/ai/mcp).

We encourage you to build MCP servers for your own applications. Whether it's documentation, API references, or domain-specific knowledge, MCP makes it easy for AI assistants to provide accurate, helpful information to your users.

The complete source code for our MCP server is available on [GitHub](https://github.com/nuxt/nuxt.com) in the [`server/mcp/`](https://github.com/nuxt/nuxt.com/tree/main/server/mcp) directory. Feel free to use it as inspiration for your own implementation!

---

# Source: https://nuxt.com/raw/docs/3.x/migration/bundling.md

# Source: https://nuxt.com/raw/docs/4.x/migration/bundling.md

# Build Tooling

> Learn how to migrate from Nuxt 2 to Nuxt 3 build tooling.

We use the following build tools by default:

- [Vite](https://vite.dev) or [webpack](https://webpack.js.org)
- [Rollup](https://rollupjs.org)
- [PostCSS](https://postcss.org)
- [esbuild](https://esbuild.github.io)

For this reason, most of your previous `build` configuration in `nuxt.config` will now be ignored, including any custom babel configuration.

If you need to configure any of Nuxt's build tools, you can do so in your `nuxt.config`, using the new top-level `vite`, `webpack` and `postcss` keys.

In addition, Nuxt ships with TypeScript support.

<read-more to="/docs/4.x/guide/concepts/typescript">



</read-more>

## Steps

1. Remove `@nuxt/typescript-build` and `@nuxt/typescript-runtime` from your dependencies and modules.
2. Remove any unused babel dependencies from your project.
3. Remove any explicit core-js dependencies.
4. Migrate `require` to `import`.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/call-once.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/call-once.md

# callOnce

> Run a given function or block of code once during SSR or CSR.

<important>

This utility is available since [Nuxt v3.9](/blog/v3-9).

</important>

## Purpose

The `callOnce` function is designed to execute a given function or block of code only once during:

- server-side rendering but not hydration
- client-side navigation

This is useful for code that should be executed only once, such as logging an event or setting up a global state.

## Usage

The default mode of `callOnce` is to run code only once. For example, if the code runs on the server it won't run again on the client. It also won't run again if you `callOnce` more than once on the client, for example by navigating back to this page.

```vue [app/app.vue]
<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  console.log('This will only be logged once')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>
```

It is also possible to run on every navigation while still avoiding the initial server/client double load. For this, it is possible to use the `navigation` mode:

```vue [app/app.vue]
<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  console.log('This will only be logged once and then on every client side navigation')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
}, { mode: 'navigation' })
</script>
```

<important>

`navigation` mode is available since [Nuxt v3.15](/blog/v3-15).

</important>

<tip to="/docs/4.x/getting-started/state-management#usage-with-pinia">

`callOnce` is useful in combination with the [Pinia module](/modules/pinia) to call store actions.

</tip>

<read-more to="/docs/4.x/getting-started/state-management">



</read-more>

<warning>

Note that `callOnce` doesn't return anything. You should use [`useAsyncData`](/docs/4.x/api/composables/use-async-data) or [`useFetch`](/docs/4.x/api/composables/use-fetch) if you want to do data fetching during SSR.

</warning>

<note>

`callOnce` is a composable meant to be called directly in a setup function, plugin, or route middleware, because it needs to add data to the Nuxt payload to avoid re-calling the function on the client when the page hydrates.

</note>

## Type

```ts [Signature]
export function callOnce (key?: string, fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>
export function callOnce (fn?: (() => any | Promise<any>), options?: CallOnceOptions): Promise<void>

type CallOnceOptions = {
  /**
   * Execution mode for the callOnce function
   * @default 'render'
   */
  mode?: 'navigation' | 'render'
}
```

## Parameters

- `key`: A unique key ensuring that the code is run once. If you do not provide a key, then a key that is unique to the file and line number of the instance of `callOnce` will be generated for you.
- `fn`: The function to run once. It can be asynchronous.
- `options`: Setup the mode, either to re-execute on navigation (`navigation`) or just once for the lifetime of the app (`render`). Defaults to `render`.

  - `render`: Executes once during initial render (either SSR or CSR) - Default mode
  - `navigation`: Executes once during initial render and once per subsequent client-side navigation

---

# Source: https://nuxt.com/raw/docs/3.x/community/changelog.md

# Source: https://nuxt.com/raw/docs/4.x/community/changelog.md

# Releases

> Discover the latest releases of Nuxt & Nuxt official modules.

<card-group>
<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/nuxt" to="https://github.com/nuxt/nuxt/releases">

Nuxt framework releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/cli" to="https://github.com/nuxt/cli/releases">

Nuxt CLI (`@nuxt/cli`) releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/a11y" to="https://github.com/nuxt/a11y/releases">

Nuxt A11y releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/content" to="https://github.com/nuxt/content/releases">

Nuxt Content releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/devtools" to="https://github.com/nuxt/devtools/releases">

Nuxt DevTools releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/fonts" to="https://github.com/nuxt/fonts/releases">

Nuxt Fonts releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/hints" to="https://github.com/nuxt/hints/releases">

Nuxt Hints releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/image" to="https://github.com/nuxt/image/releases">

Nuxt Image releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/scripts" to="https://github.com/nuxt/scripts/releases">

Nuxt Scripts releases.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="nuxt/ui" to="https://github.com/nuxt/ui/releases">

Nuxt UI releases.

</card>
</card-group>

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt">

Discover the `nuxt` organization on GitHub

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/cleanup.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/cleanup.md

# nuxt cleanup

> Remove common generated Nuxt files and caches.

```bash [Terminal]
npx nuxt cleanup [ROOTDIR] [--cwd=<directory>]
```

The `cleanup` command removes common generated Nuxt files and caches, including:

- `.nuxt`
- `.output`
- `node_modules/.vite`
- `node_modules/.cache`

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/clear-error.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/clear-error.md

# clearError

> The clearError composable clears all handled errors.

Within your pages, components, and plugins, you can use `clearError` to clear all errors and redirect the user.

**Parameters:**

- `options?: { redirect?: string }`

You can provide an optional path to redirect to (for example, if you want to navigate to a 'safe' page).

```ts
// Without redirect
clearError()

// With redirect
clearError({ redirect: '/homepage' })
```

Errors are set in state using [`useError()`](/docs/4.x/api/composables/use-error). The `clearError` composable will reset this state and calls the `app:error:cleared` hook with the provided options.

<read-more to="/docs/4.x/getting-started/error-handling">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/clear-nuxt-data.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/clear-nuxt-data.md

# clearNuxtData

> Delete cached data, error status and pending promises of useAsyncData and useFetch.

<note>

This method is useful if you want to invalidate the data fetching for another page.

</note>

## Type

```ts [Signature]
export function clearNuxtData (keys?: string | string[] | ((key: string) => boolean)): void
```

## Parameters

- `keys`: One or an array of keys that are used in [`useAsyncData`](/docs/4.x/api/composables/use-async-data) to delete their cached data. If no keys are provided, **all data** will be invalidated.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/clear-nuxt-state.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/clear-nuxt-state.md

# clearNuxtState

> Delete the cached state of useState.

<note>

This method is useful if you want to invalidate the state of `useState`.

</note>

## Type

```ts [Signature]
export function clearNuxtState (keys?: string | string[] | ((key: string) => boolean)): void
```

## Parameters

- `keys`: One or an array of keys that are used in [`useState`](/docs/4.x/api/composables/use-state) to delete their cached state. If no keys are provided, **all state** will be invalidated.

---

# Source: https://nuxt.com/raw/deploy/cleavr.md

# Cleavr

> Deploy your Nuxt Application to Cleavr infrastructure.

<tip>

**Zero Configuration ✨**

<br />

Integration with this provider is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

## Setup

**In your Cleavr.io panel:**

1. Provision a new server
2. Add a website, selecting **Nuxt 3** as the app type
3. In web app > settings > Code Repo, point to your project's code repository
4. In web app > settings > Environment variables, set `SERVER_PRESET=cleavr`

You're now all set to deploy your project!

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/cleavr">

Head over **Nitro documentation** to learn more about the cleavr deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/deploy/clever-cloud.md

# Clever Cloud

> Deploy your Nuxt Application to Clever Cloud infrastructure.

Nuxt supports deploying on [Clever Cloud](https://www.clever-cloud.com/) with minimal configuration.

## Deploy Clever Cloud from the Console

To deploy your Nuxt project to Clever Cloud, you will need to create a **new application**. The application wizard will walk you through the necessary configuration steps.

1. From the lateral menubar, click **Create > An application**
2. Choose how to deploy: **Create an application from a local repository** or **Create an application from a GitHub repository**
3. Select a **Node.js** application, or a **static one**.
4. Set up the minimal size for your instance and scalability options. Nuxt app must be deployed with a minimum size of **XS** instance for **Node.js** application and **nano** instance for **static one**. The build process, however, will need to be configured later with at least an M instance size to ensure it can handle the resource requirements. Depending on your project’s specifications and dependencies, you may need to adjust further as you monitor the metrics from the **Overview** page.
5. Select a **region** to deploy your instance.
6. Skip connecting **Add-ons** to your Clever application unless you’re using a database.
7. Inject **environment variables**:

- For **Node.js**

<code-group sync="pm">

```ini [npm]
CC_POST_BUILD_HOOK="npm run build"
CC_RUN_COMMAND="node .output/server/index.mjs"
```

```ini [yarn]
CC_POST_BUILD_HOOK="yarn build"
CC_RUN_COMMAND="node .output/server/index.mjs"
```

```ini [pnpm]
CC_POST_BUILD_HOOK="pnpm build"
CC_RUN_COMMAND="node .output/server/index.mjs"
```

```ini [bun]
CC_POST_BUILD_HOOK="bun build"
CC_RUN_COMMAND="node .output/server/index.mjs"
```

</code-group>

- For a **static application**

<note>

If [`ssr: false` is set in `nuxt.config.ts`](https://nuxt.com/docs/4.x/getting-started/deployment#static-hosting) **or** if your project contains dynamic routes that cannot be pre-rendered, you should :

1. Use a **Static Apache** application
2. Create a [`.htaccess`](https://www.clever.cloud/developers/doc/applications/static-apache/#serving-indexhtml-for-spa-single-page-application-routers) file that redirects all routes to `index.html` to ensure proper routing for your SPA.

Otherwise, you can use the default **Static HTML** application.

</note>

<code-group sync="pm">

```ini [npm]
CC_WEBROOT=/.output/public
CC_OVERRIDE_BUILDCACHE=/.output/public
CC_PRE_BUILD_HOOK=npm install
CC_POST_BUILD_HOOK=npm run generate
```

```ini [yarn]
CC_WEBROOT=/.output/public
CC_OVERRIDE_BUILDCACHE=/.output/public
CC_PRE_BUILD_HOOK=yarn install
CC_POST_BUILD_HOOK=yarn generate
```

```ini [pnpm]
CC_WEBROOT=/.output/public
CC_OVERRIDE_BUILDCACHE=/.output/public
CC_PRE_BUILD_HOOK=pnpm install
CC_POST_BUILD_HOOK=pnpm generate
```

```ini [bun]
CC_WEBROOT=/.output/public
CC_OVERRIDE_BUILDCACHE=/.output/public
CC_PRE_BUILD_HOOK=bun install
CC_POST_BUILD_HOOK=bun generate
```

</code-group>

1. Navigate to the application **Information** menu and enable the **enable dedicated build instance** option on a minimal instance of type **M**.
2. **Deploy!** If you’re deploying from **GitHub**, your deployment should start automatically. If you’re using **Git**, show [this docs](https://www.clever-cloud.com/developers/doc/quickstart/#choose-how-to-deploy).

## Learn more

<read-more target="_blank" to="https://developers.clever-cloud.com/guides/nuxt">

Clever Cloud documentation for deploying Nuxt

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/client-only.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/client-only.md

# <ClientOnly>

> Render components only in client-side with the <ClientOnly> component.

The `<ClientOnly>` component is used for purposely rendering a component only on client side.

<note>

The content of the default slot will be tree-shaken out of the server build. (This does mean that any CSS used by components within it may not be inlined when rendering the initial HTML.)

</note>

## Props

- `placeholderTag` | `fallbackTag`: specify a tag to be rendered server-side.
- `placeholder` | `fallback`: specify a content to be rendered server-side.

```vue
<template>
  <div>
    <Sidebar />
    <!-- The <Comment> component will only be rendered on client-side -->
    <ClientOnly
      fallback-tag="span"
      fallback="Loading comments..."
    >
      <Comment />
    </ClientOnly>
  </div>
</template>
```

## Slots

- `#fallback`: specify a content to be rendered on the server and displayed until `<ClientOnly>` is mounted in the browser.

```vue [app/pages/example.vue]
<template>
  <div>
    <Sidebar />
    <!-- This renders the "span" element on the server side -->
    <ClientOnly fallback-tag="span">
      <!-- this component will only be rendered on client side -->
      <Comments />
      <template #fallback>
        <!-- this will be rendered on server side -->
        <p>Loading comments...</p>
      </template>
    </ClientOnly>
  </div>
</template>
```

## Examples

### Accessing HTML Elements

Components inside `<ClientOnly>` are rendered only after being mounted. To access the rendered elements in the DOM, you can watch a template ref:

```vue [app/pages/example.vue]
<script setup lang="ts">
const nuxtWelcomeRef = useTemplateRef('nuxtWelcomeRef')

// The watch will be triggered when the component is available
watch(nuxtWelcomeRef, () => {
  console.log('<NuxtWelcome /> mounted')
}, { once: true })
</script>

<template>
  <ClientOnly>
    <NuxtWelcome ref="nuxtWelcomeRef" />
  </ClientOnly>
</template>
```

---

# Source: https://nuxt.com/raw/deploy/cloudflare.md

# Cloudflare

> Deploy your Nuxt Application to Cloudflare infrastructure.

## Cloudflare Pages

<tip>

**Zero Configuration ✨**

<br />

Integration with Cloudflare Pages is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

<important>

Checkout the [@nuxthub/core](/modules/hub) module to build full-stack Nuxt applications with Cloudflare, learn more on [hub.nuxt.com](https://hub.nuxt.com).

</important>

### Git Integration

If you use the GitHub/GitLab integration with Cloudflare Pages, **no configuration is required**. Pushing to your repository will automatically build your project and deploy it.

<note>

Nuxt will detect the environment to set the correct [Server/Nitro preset](https://nitro.unjs.io/deploy/providers/cloudflare).

</note>

To leverage server-side rendering on the edge, set the build command to: `nuxt build`

To statically generate your website, set the build command to: `nuxt generate`

### Route matching

On CloudFlare Pages, if an HTML file is found with a matching path to the current route requested, it will serve it. It will also redirect HTML pages to their extension-less counterparts: for instance, `/contact.html` will be redirected to `/contact`, and `/about/index.html` will be redirected to `/about/`.

To match Cloudflare [route matching](https://developers.cloudflare.com/pages/configuration/serving-pages/#route-matching) rules, set the nitro option `autoSubfolderIndex` to `false`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    prerender: {
      autoSubfolderIndex: false
    }
  }
})
```

### Direct Upload

Alternatively, you can use [wrangler](https://github.com/cloudflare/workers-sdk) to upload your project to Cloudflare.

In this case, you will have to set the preset manually.

1. Build your project for Cloudflare Pages:

```bash [Terminal]
npx nuxi build --preset=cloudflare_pages
```

1. Deploy, it will ask you to create a project for the first time:

```bash [Terminal]
npx wrangler pages deploy dist/
```

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/cloudflare">

Head over **Nitro documentation** to learn more about the Cloudflare deployment preset.

</read-more>

<read-more target="_blank" to="https://developers.cloudflare.com/pages/framework-guides/deploy-a-nuxt-site/#use-bindings-in-your-nuxt-application">

Head over **CloudFlare Pages** documentation to learn more about it.

</read-more>

## Templates

<card-group>
<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Atidone" to="https://github.com/atinux/atidone">

A todos application with user authentication, SSR and Cloudflare D1.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Atinotes" to="https://github.com/atinux/atinotes">

An editable website with universal rendering based on Cloudflare KV.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Atidraw" to="https://github.com/atinux/atidraw">

Web application that lets you to draw and share your drawings with the world, with Cloudflare R2 & AI.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Nuxt Image Gallery" to="https://github.com/flosciante/nuxt-image-gallery">

An image gallery to upload, edit and share your images to the world, with Cloudflare R2.

</card>
</card-group>

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/cloudflare">

Head over **Nitro documentation** to learn more about the cloudflare deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/code-style.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/code-style.md

# Code Style

> Nuxt supports ESLint out of the box

## ESLint

The recommended approach for Nuxt is to enable ESLint support using the [`@nuxt/eslint`](https://eslint.nuxt.com/packages/module) module, that will setup project-aware ESLint configuration for you.

<callout icon="i-lucide-lightbulb">

The module is designed for the [new ESLint flat config format](https://eslint.org/docs/latest/use/configure/configuration-files) which is the [default format since ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/). If you are using the legacy `.eslintrc` config, you will need to [configure manually with `@nuxt/eslint-config`](https://eslint.nuxt.com/packages/config#customizing-the-config). We highly recommend you to migrate over the flat config to be future-proof.

</callout>

## Quick Setup

```bash
npx nuxt module add eslint
```

Start your Nuxt app, a `eslint.config.mjs` file will be generated under your project root. You can customize it as needed.

You can learn more about the module and customizations in [Nuxt ESLint's documentation](https://eslint.nuxt.com/packages/module).

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/compatibility.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/compatibility.md

# Compatibility

> Nuxt Kit provides a set of utilities to help you check the compatibility of your modules with different Nuxt versions.

Nuxt Kit utilities can be used in Nuxt 3, Nuxt 2 with Bridge and even Nuxt 2 without Bridge. To make sure your module is compatible with all versions, you can use the `checkNuxtCompatibility`, `assertNuxtCompatibility` and `hasNuxtCompatibility` functions. They will check if the current Nuxt version meets the constraints you provide. Also you can use `isNuxt2`, `isNuxt3` and `getNuxtVersion` functions for more granular checks.

## `checkNuxtCompatibility`

Checks if constraints are met for the current Nuxt version. If not, returns an array of messages. Nuxt 2 version also checks for `bridge` support.

### Usage

```tstwoslash
import { checkNuxtCompatibility, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const issues = await checkNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (issues.length) {
      console.warn('Nuxt compatibility issues found:\n' + issues.toString())
    } else {
      // do something
    }
  },
})
```

### Type

```ts
function checkNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<NuxtCompatibilityIssues>
```

### Parameters

**constraints**: Version and builder constraints to check against. It accepts the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        nuxt
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Nuxt version in semver format. Versions may be defined in Node.js way, for example: <code>
        >=2.15.0 <3.0.0
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bridge
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Record
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sbKd-">
          false
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Specifies version constraints or disables compatibility for specific Nuxt builders like <code>
        vite
      </code>
      
      , <code>
        webpack
      </code>
      
      , or <code>
        rspack
      </code>
      
      . Use <code>
        false
      </code>
      
       to disable.
    </td>
  </tr>
</tbody>
</table>

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

## `assertNuxtCompatibility`

Asserts that constraints are met for the current Nuxt version. If not, throws an error with the list of issues as string.

### Type

```tstwoslash
// @errors: 2391
import type { Nuxt, NuxtCompatibility } from '@nuxt/schema'
// ---cut---
function assertNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<true>
```

### Parameters

**constraints**: Version and builder constraints to check against. Refer to the [constraints table in `checkNuxtCompatibility`](/docs/4.x/api/kit/compatibility#parameters) for details.

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

## `hasNuxtCompatibility`

Checks if constraints are met for the current Nuxt version. Return `true` if all constraints are met, otherwise returns `false`. Nuxt 2 version also checks for `bridge` support.

### Usage

```tstwoslash
import { defineNuxtModule, hasNuxtCompatibility } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const usingNewPostcss = await hasNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (usingNewPostcss) {
      // do something
    } else {
      // do something else
    }
  },
})
```

### Type

```ts
function hasNuxtCompatibility (constraints: NuxtCompatibility, nuxt?: Nuxt): Promise<boolean>
```

### Parameters

**constraints**: Version and builder constraints to check against. Refer to the [constraints table in `checkNuxtCompatibility`](/docs/4.x/api/kit/compatibility#parameters) for details.

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

## `isNuxtMajorVersion`

Check if current Nuxt instance is of specified major version

### Usage

```tstwoslash
import { defineNuxtModule, isNuxtMajorVersion } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    if (isNuxtMajorVersion(3)) {
      // do something for Nuxt 3
    } else {
      // do something else for other versions
    }
  },
})
```

### Type

```ts
function isNuxtMajorVersion (major: number, nuxt?: Nuxt): boolean
```

### Parameters

**major**: Major version to check against.

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

## `isNuxt3`

Checks if the current Nuxt version is 3.x.

<note>

Use `isNuxtMajorVersion(2, nuxt)` instead. This may be removed in @nuxt/kit v5 or a future major version.

</note>

### Type

```ts
function isNuxt3 (nuxt?: Nuxt): boolean
```

### Parameters

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

## `isNuxt2`

Checks if the current Nuxt version is 2.x.

<note>

Use `isNuxtMajorVersion(2, nuxt)` instead. This may be removed in @nuxt/kit v5 or a future major version.

</note>

### Type

```ts
function isNuxt2 (nuxt?: Nuxt): boolean
```

### Parameters

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

## `getNuxtVersion`

Returns the current Nuxt version.

### Type

```ts
function getNuxtVersion (nuxt?: Nuxt): string
```

### Parameters

**nuxt**: Nuxt instance. If not provided, it will be retrieved from the context via `useNuxt()` call.

---

# Source: https://nuxt.com/raw/docs/3.x/migration/component-options.md

# Source: https://nuxt.com/raw/docs/4.x/migration/component-options.md

# Component Options

> Learn how to migrate from Nuxt 2 components options to Nuxt 3 composables.

## `asyncData` and `fetch`

Nuxt 3 provides new options for [fetching data from an API](/docs/4.x/getting-started/data-fetching).

### Isomorphic Fetch

In Nuxt 2 you might use `@nuxtjs/axios` or `@nuxt/http` to fetch your data - or just the polyfilled global `fetch`.

In Nuxt 3 you can use a globally available `fetch` method that has the same API as [the Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) or [`$fetch`](/docs/4.x/api/utils/dollarfetch) method which is using [unjs/ofetch](https://github.com/unjs/ofetch). It has a number of benefits, including:

1. It will handle 'smartly' making [direct API calls](/docs/4.x/guide/concepts/server-engine#direct-api-calls) if it's running on the server, or making a client-side call to your API if it's running on the client. (It can also handle calling third-party APIs.)
2. Plus, it comes with convenience features including automatically parsing responses and stringifying data.

You can read more [about direct API calls](/docs/4.x/guide/concepts/server-engine#direct-api-calls) or [fetching data](/docs/4.x/getting-started/data-fetching).

### Composables

Nuxt 3 provides new composables for fetching data: [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and `useFetch`. They each have 'lazy' variants (`useLazyAsyncData` and `useLazyFetch`), which do not block client-side navigation.

In Nuxt 2, you'd fetch your data in your component using a syntax similar to:

```ts
export default {
  async asyncData ({ params, $http }) {
    const post = await $http.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
    return { post }
  },
  // or alternatively
  fetch () {
    this.post = await $http.$get(`https://api.nuxtjs.dev/posts/${params.id}`)
  },
}
```

Within your methods and templates, you could use the `post` variable similar how you'd use any other piece of data provided by your component.

With Nuxt 3, you can perform this data fetching using composables in your `setup()` method or `<script setup>` tag:

```vue
<script setup lang="ts">
// Define params wherever, through `defineProps()`, `useRoute()`, etc.
const { data: post, refresh } = await useAsyncData('post', () => $fetch(`https://api.nuxtjs.dev/posts/${params.id}`))
// Or instead - useFetch is a convenience wrapper around useAsyncData when you're just performing a simple fetch
const { data: post, refresh } = await useFetch(`https://api.nuxtjs.dev/posts/${params.id}`)
</script>
```

You can now use `post` inside of your Nuxt 3 template, or call `refresh` to update the data.

<note>

Despite the names, [`useFetch`](/docs/4.x/api/composables/use-fetch) is not a direct replacement of the `fetch()` hook. Rather, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) replaces both hooks and is more customizable; it can do more than simply fetching data from an endpoint. [`useFetch`](/docs/4.x/api/composables/use-fetch) is a convenience wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) for simply fetching data from an endpoint.

</note>

### Migration

1. Replace the `asyncData` hook with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) or [`useFetch`](/docs/4.x/api/composables/use-fetch) in your page/component.
2. Replace the `fetch` hook with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) or [`useFetch`](/docs/4.x/api/composables/use-fetch) in your component.

## `head`

<read-more to="/docs/4.x/migration/meta">



</read-more>

## `key`

You can now define a key within the [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) compiler macro.

```diff [app/pages/index.vue]
- <script>
- export default {
-   key: 'index'
-   // or a method
-   // key: route => route.fullPath
- }
+ <script setup>
+ definePageMeta({
+   key: 'index'
+   // or a method
+   // key: route => route.fullPath
+ })
</script>
```

## `layout`

<read-more to="/docs/4.x/migration/pages-and-layouts">



</read-more>

## `loading`

This feature is not yet supported in Nuxt 3.

## `middleware`

<read-more to="/docs/4.x/migration/plugins-and-middleware">



</read-more>

## `scrollToTop`

This feature is not yet supported in Nuxt 3. If you want to overwrite the default scroll behavior of `vue-router`, you can do so in an `~/router.options.ts` (see [docs](/docs/4.x/guide/recipes/custom-routing#router-options)) for more info.
Similar to `key`, specify it within the [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) compiler macro.

```diff [app/pages/index.vue]
- <script>
- export default {
-   scrollToTop: false
- }
+ <script setup>
+ definePageMeta({
+   scrollToTop: false
+ })
</script>
```

## `transition`

<read-more to="/docs/4.x/getting-started/transitions">



</read-more>

## `validate`

The validate hook in Nuxt 3 only accepts a single argument, the `route`. Just as in Nuxt 2, you can return a boolean value. If you return false and another match can't be found, this will mean a 404. You can also directly return an object with `status`/`statusText` to respond immediately with an error (other matches will not be checked).

```diff [app/pages/users/[id].vue]
- <script>
- export default {
-   async validate({ params }) {
-     return /^\d+$/.test(params.id)
-   }
- }
+ <script setup>
+ definePageMeta({
+   validate: async (route) => {
+     const nuxtApp = useNuxtApp()
+     return /^\d+$/.test(route.params.id)
+   }
+ })
  </script>
```

## `watchQuery`

This is not supported in Nuxt 3. Instead, you can directly use a watcher to trigger refetching data.

```vue [app/pages/users/[id].vue]
<script setup lang="ts">
const route = useRoute()
const { data, refresh } = await useFetch('/api/user')
watch(() => route.query, () => refresh())
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/components.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/components.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/components.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/components.md

# components

> The components/ directory is where you put all your Vue components.

Nuxt automatically imports any components in this directory (along with components that are registered by any modules you may be using).

```bash [Directory Structure]
-| components/
---| AppHeader.vue
---| AppFooter.vue
```

```html [app/app.vue]
<template>
  <div>
    <AppHeader />
    <NuxtPage />
    <AppFooter />
  </div>
</template>
```

## Component Names

If you have a component in nested directories such as:

```bash [Directory Structure]
-| components/
---| base/
-----| foo/
-------| Button.vue
```

... then the component's name will be based on its own path directory and filename, with duplicate segments being removed. Therefore, the component's name will be:

```html
<BaseFooButton />
```

<note>

For clarity, we recommend that the component's filename matches its name. So, in the example above, you could rename `Button.vue` to be `BaseFooButton.vue`.

</note>

If you want to auto-import components based only on its name, not path, then you need to set `pathPrefix` option to `false` using extended form of the configuration object:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  components: [
    {
      path: '~/components',
      pathPrefix: false, // [!code ++]
    },
  ],
})
```

This registers the components using the same strategy as used in Nuxt 2. For example, `~/components/Some/MyComponent.vue` will be usable as `<MyComponent>` and not `<SomeMyComponent>`.

## Dynamic Components

If you want to use the Vue `<component :is="someComputedComponent">` syntax, you need to use the `resolveComponent` helper provided by Vue or import the component directly from `#components` and pass it into `is` prop.

For example:

```vue [app/pages/index.vue]
<script setup lang="ts">
import { SomeComponent } from '#components'

const MyButton = resolveComponent('MyButton')
</script>

<template>
  <component :is="clickable ? MyButton : 'div'" />
  <component :is="SomeComponent" />
</template>
```

<important>

If you are using `resolveComponent` to handle dynamic components, make sure not to insert anything but the name of the component, which must be a literal string and not be or contain a variable. The string is statically analyzed at the compilation step.

</important>

<video-accordion title="Watch Daniel Roe's short video about resolveComponent()" video-id="4kq8E5IUM2U">



</video-accordion>

Alternatively, though not recommended, you can register all your components globally, which will create async chunks for all your components and make them available throughout your application.

```diff
export default defineNuxtConfig({
    components: {
+     global: true,
+     dirs: ['~/components']
    },
  })
```

You can also selectively register some components globally by placing them in a `~/components/global` directory, or by using a `.global.vue` suffix in the filename. As noted above, each global component is rendered in a separate chunk, so be careful not to overuse this feature.

<note>

The `global` option can also be set per component directory.

</note>

## Dynamic Imports

To dynamically import a component (also known as lazy-loading a component) all you need to do is add the `Lazy` prefix to the component's name. This is particularly useful if the component is not always needed.

By using the `Lazy` prefix you can delay loading the component code until the right moment, which can be helpful for optimizing your JavaScript bundle size.

```vue [app/pages/index.vue]
<script setup lang="ts">
const show = ref(false)
</script>

<template>
  <div>
    <h1>Mountains</h1>
    <LazyMountainsList v-if="show" />
    <button
      v-if="!show"
      @click="show = true"
    >
      Show List
    </button>
  </div>
</template>
```

## Delayed (or Lazy) Hydration

Lazy components are great for controlling the chunk sizes in your app, but they don't always enhance runtime performance, as they still load eagerly unless conditionally rendered. In real-world applications, some pages may include a lot of content and a lot of components, and most of the time not all of them need to be interactive as soon as the page is loaded. Having them all load eagerly can negatively impact performance.

In order to optimize your app, you may want to delay the hydration of some components until they're visible, or until the browser is done with more important tasks.

Nuxt supports this using lazy (or delayed) hydration, allowing you to control when components become interactive.

### Hydration Strategies

Nuxt provides a range of built-in hydration strategies. Only one strategy can be used per lazy component.

<note>

Any prop change on a lazily hydrated component will trigger hydration immediately. (e.g., changing a prop on a component with `hydrate-never` will cause it to hydrate)

</note>

<warning>

Currently Nuxt's built-in lazy hydration only works in single-file components (SFCs), and requires you to define the prop in the template (rather than spreading an object of props via `v-bind`). It also does not work with direct imports from `#components`.

</warning>

#### `hydrate-on-visible`

Hydrates the component when it becomes visible in the viewport.

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent hydrate-on-visible />
  </div>
</template>
```

<read-more to="https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver" title="IntersectionObserver options">

Read more about the options for `hydrate-on-visible`.

</read-more>

<note>

Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async#hydrate-on-visible).

</note>

#### `hydrate-on-idle`

Hydrates the component when the browser is idle. This is suitable if you need the component to load as soon as possible, but not block the critical rendering path.

You can also pass a number which serves as a max timeout.

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent hydrate-on-idle />
  </div>
</template>
```

<note>

Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async#hydrate-on-idle).

</note>

#### `hydrate-on-interaction`

Hydrates the component after a specified interaction (e.g., click, mouseover).

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent hydrate-on-interaction="mouseover" />
  </div>
</template>
```

If you do not pass an event or list of events, it defaults to hydrating on `pointerenter`, `click` and `focus`.

<note>

Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async#hydrate-on-interaction).

</note>

#### `hydrate-on-media-query`

Hydrates the component when the window matches a media query.

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent hydrate-on-media-query="(max-width: 768px)" />
  </div>
</template>
```

<note>

Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async#hydrate-on-media-query).

</note>

#### `hydrate-after`

Hydrates the component after a specified delay (in milliseconds).

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent :hydrate-after="2000" />
  </div>
</template>
```

#### `hydrate-when`

Hydrates the component based on a boolean condition.

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent :hydrate-when="isReady" />
  </div>
</template>

<script setup lang="ts">
const isReady = ref(false)
function myFunction () {
  // trigger custom hydration strategy...
  isReady.value = true
}
</script>
```

#### `hydrate-never`

Never hydrates the component.

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent hydrate-never />
  </div>
</template>
```

### Listening to Hydration Events

All delayed hydration components emit a `@hydrated` event when they are hydrated.

```vue [app/pages/index.vue]
<template>
  <div>
    <LazyMyComponent
      hydrate-on-visible
      @hydrated="onHydrate"
    />
  </div>
</template>

<script setup lang="ts">
function onHydrate () {
  console.log('Component has been hydrated!')
}
</script>
```

### Caveats and Best Practices

Delayed hydration can offer performance benefits, but it's essential to use it correctly:

1. **Prioritize In-Viewport Content:** Avoid delayed hydration for critical, above-the-fold content. It's best suited for content that isn't immediately needed.
2. **Conditional Rendering:** When using `v-if="false"` on a lazy component, you might not need delayed hydration. You can just use a normal lazy component.
3. **Shared State:** Be mindful of shared state (`v-model`) across multiple components. Updating the model in one component can trigger hydration in all components bound to that model.
4. **Use Each Strategy's Intended Use Case:** Each strategy is optimized for a specific purpose.
  - `hydrate-when` is best for components that might not always need to be hydrated.
  - `hydrate-after` is for components that can wait a specific amount of time.
  - `hydrate-on-idle` is for components that can be hydrated when the browser is idle.
5. **Avoid hydrate-never on interactive components:** If a component requires user interaction, it should not be set to never hydrate.

## Direct Imports

You can also explicitly import components from `#components` if you want or need to bypass Nuxt's auto-importing functionality.

```vue [app/pages/index.vue]
<script setup lang="ts">
import { LazyMountainsList, NuxtLink } from '#components'

const show = ref(false)
</script>

<template>
  <div>
    <h1>Mountains</h1>
    <LazyMountainsList v-if="show" />
    <button
      v-if="!show"
      @click="show = true"
    >
      Show List
    </button>
    <NuxtLink to="/">Home</NuxtLink>
  </div>
</template>
```

## Custom Directories

By default, only the `~/components` directory is scanned. If you want to add other directories, or change how the components are scanned within a subfolder of this directory, you can add additional directories to the configuration:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  components: [
    // ~/calendar-module/components/event/Update.vue => <EventUpdate />
    { path: '~/calendar-module/components' },

    // ~/user-module/components/account/UserDeleteDialog.vue => <UserDeleteDialog />
    { path: '~/user-module/components', pathPrefix: false },

    // ~/components/special-components/Btn.vue => <SpecialBtn />
    { path: '~/components/special-components', prefix: 'Special' },

    // It's important that this comes last if you have overrides you wish to apply
    // to sub-directories of `~/components`.
    //
    // ~/components/Btn.vue => <Btn />
    // ~/components/base/Btn.vue => <BaseBtn />
    '~/components',
  ],
})
```

<note>

Any nested directories need to be added first as they are scanned in order.

</note>

## npm Packages

If you want to auto-import components from an npm package, you can use [`addComponent`](/docs/4.x/api/kit/components#addcomponent) in a [local module](/docs/4.x/directory-structure/modules) to register them.

<code-group>

```ts [~/modules/register-component.ts]twoslash
import { addComponent, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    // import { MyComponent as MyAutoImportedComponent } from 'my-npm-package'
    addComponent({
      name: 'MyAutoImportedComponent',
      export: 'MyComponent',
      filePath: 'my-npm-package',
    })
  },
})
```

```vue [app/app.vue]
<template>
  <div>
    <!--  the component uses the name we specified and is auto-imported  -->
    <MyAutoImportedComponent />
  </div>
</template>
```

</code-group>

## Component Extensions

By default, any file with an extension specified in the [extensions key of `nuxt.config.ts`](/docs/4.x/api/nuxt-config#extensions) is treated as a component.
If you need to restrict the file extensions that should be registered as components, you can use the extended form of the components directory declaration and its `extensions` key:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  components: [
    {
      path: '~/components',
      extensions: ['.vue'], // [!code ++]
    },
  ],
})
```

## Client Components

If a component is meant to be rendered only client-side, you can add the `.client` suffix to your component.

```bash [Directory Structure]
| components/
--| Comments.client.vue
```

```vue [app/pages/example.vue]
<template>
  <div>
    <!-- this component will only be rendered on client side -->
    <Comments />
  </div>
</template>
```

<note>

This feature only works with Nuxt auto-imports and `#components` imports. Explicitly importing these components from their real paths does not convert them into client-only components.

</note>

<important>

`.client` components are rendered only after being mounted. To access the rendered template using `onMounted()`, add `await nextTick()` in the callback of the `onMounted()` hook.

</important>

<read-more to="/docs/4.x/api/components/client-only">

You can also achieve a similar result with the `<ClientOnly>` component.

</read-more>

## Server Components

Server components allow server-rendering individual components within your client-side apps. It's possible to use server components within Nuxt, even if you are generating a static site. That makes it possible to build complex sites that mix dynamic components, server-rendered HTML and even static chunks of markup.

Server components can either be used on their own or paired with a [client component](/docs/4.x/directory-structure/app/components#paired-with-a-client-component).

<video-accordion title="Watch Learn Vue video about Nuxt Server Components" video-id="u1yyXe86xJM">



</video-accordion>

<tip icon="i-lucide-newspaper" target="_blank" to="https://roe.dev/blog/nuxt-server-components">

Read Daniel Roe's guide to Nuxt Server Components.

</tip>

### Standalone server components

Standalone server components will always be rendered on the server, also known as Islands components.

When their props update, this will result in a network request that will update the rendered HTML in-place.

Server components are currently experimental and in order to use them, you need to enable the 'component islands' feature in your nuxt.config:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    componentIslands: true,
  },
})
```

Now you can register server-only components with the `.server` suffix and use them anywhere in your application automatically.

```bash [Directory Structure]
-| components/
---| HighlightedMarkdown.server.vue
```

```vue [app/pages/example.vue]
<template>
  <div>
    <!--
      this will automatically be rendered on the server, meaning your markdown parsing + highlighting
      libraries are not included in your client bundle.
     -->
    <HighlightedMarkdown markdown="# Headline" />
  </div>
</template>
```

Server-only components use [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island) under the hood, meaning that `lazy` prop and `#fallback` slot are both passed down to it.

<warning>

Server components (and islands) must have a single root element. (HTML comments are considered elements as well.)

</warning>

<warning>

Props are passed to server components via URL query parameters, and are therefore limited by the possible length of a URL, so be careful not to pass enormous amounts of data to server components via props.

</warning>

<warning>

Be careful when nesting islands within other islands as each island adds some extra overhead.

</warning>

<warning>

Most features for server-only components and island components, such as slots and client components, are only available for single file components.

</warning>

#### Client components within server components

<note>

This feature needs `experimental.componentIslands.selectiveClient` within your configuration to be true.

</note>

You can partially hydrate a component by setting a `nuxt-client` attribute on the component you wish to be loaded client-side.

```vue [app/components/ServerWithClient.vue]
<template>
  <div>
    <HighlightedMarkdown markdown="# Headline" />
    <!-- Counter will be loaded and hydrated client-side -->
    <Counter
      nuxt-client
      :count="5"
    />
  </div>
</template>
```

<note>

This only works within a server component. Slots for client components are working only with `experimental.componentIsland.selectiveClient` set to `'deep'` and since they are rendered server-side, they are not interactive once client-side.

</note>

#### Server Component Context

When rendering a server-only or island component, `<NuxtIsland>` makes a fetch request which comes back with a `NuxtIslandResponse`. (This is an internal request if rendered on the server, or a request that you can see in the network tab if it's rendering on client-side navigation.)

This means:

- A new Vue app will be created server-side to create the `NuxtIslandResponse`.
- A new 'island context' will be created while rendering the component.
- You can't access the 'island context' from the rest of your app and you can't access the context of the rest of your app from the island component. In other words, the server component or island is *isolated* from the rest of your app.
- Your plugins will run again when rendering the island, unless they have `env: { islands: false }` set (which you can do in an object-syntax plugin).

<important>

Route middleware does not run when rendering island components. Middleware is a routing concept that applies to pages, not components, and is not designed to control component rendering.

</important>

Within an island component, you can access its island context through `nuxtApp.ssrContext.islandContext`. Note that while island components are still marked as experimental, the format of this context may change.

<note>

Slots can be interactive and are wrapped within a `<div>` with `display: contents;`

</note>

### Paired with a Client component

In this case, the `.server` + `.client` components are two 'halves' of a component and can be used in advanced use cases for separate implementations of a component on server and client side.

```bash [Directory Structure]
-| components/
---| Comments.client.vue
---| Comments.server.vue
```

```vue [app/pages/example.vue]
<template>
  <div>
    <!-- this component will render Comments.server on the server then Comments.client once mounted in the browser -->
    <Comments />
  </div>
</template>
```

## Built-In Nuxt Components

There are a number of components that Nuxt provides, including `<ClientOnly>` and `<DevOnly>`. You can read more about them in the API documentation.

<read-more to="/docs/4.x/api">



</read-more>

## Library Authors

Making Vue component libraries with automatic tree-shaking and component registration is super easy. ✨

You can use the [`addComponentsDir`](/docs/4.x/api/kit/components#addcomponentsdir) method provided from the `@nuxt/kit` to register your components directory in your Nuxt module.

Imagine a directory structure like this:

```bash [Directory Structure]
-| node_modules/
---| awesome-ui/
-----| components/
-------| Alert.vue
-------| Button.vue
-----| nuxt.ts
-| pages/
---| index.vue
-| nuxt.config.ts
```

Then in `awesome-ui/nuxt.ts` you can use the `addComponentsDir` hook:

```tstwoslash
import { addComponentsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const resolver = createResolver(import.meta.url)

    // Add ./components dir to the list
    addComponentsDir({
      path: resolver.resolve('./components'),
      prefix: 'awesome',
    })
  },
})
```

That's it! Now in your project, you can import your UI library as a Nuxt module in your `nuxt.config` file:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  modules: ['awesome-ui/nuxt'],
})
```

... and directly use the module components (prefixed with `awesome-`) in our `app/pages/index.vue`:

```vue
<template>
  <div>
    My <AwesomeButton>UI button</AwesomeButton>!
    <awesome-alert>Here's an alert!</awesome-alert>
  </div>
</template>
```

It will automatically import the components only if used and also support HMR when updating your components in `node_modules/awesome-ui/components/`.

<link-example to="/docs/4.x/examples/features/auto-imports">



</link-example>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/composables.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/composables.md

# composables

> Use the composables/ directory to auto-import your Vue composables into your application.

## Usage

**Method 1:** Using named export

```ts [app/composables/useFoo.ts]
export const useFoo = () => {
  return useState('foo', () => 'bar')
}
```

**Method 2:** Using default export

```ts [app/composables/use-foo.ts or composables/useFoo.ts]
// It will be available as useFoo() (camelCase of file name without extension)
export default function () {
  return useState('foo', () => 'bar')
}
```

**Usage:** You can now use auto imported composable in `.js`, `.ts` and `.vue` files

```vue [app/app.vue]
<script setup lang="ts">
const foo = useFoo()
</script>

<template>
  <div>
    {{ foo }}
  </div>
</template>
```

<note>

The `app/composables/` directory in Nuxt does not provide any additional reactivity capabilities to your code. Instead, any reactivity within composables is achieved using Vue's Composition API mechanisms, such as ref and reactive. Note that reactive code is also not limited to the boundaries of the `app/composables/` directory. You are free to employ reactivity features wherever they're needed in your application.

</note>

<read-more to="/docs/4.x/guide/concepts/auto-imports">



</read-more>

<link-example to="/docs/4.x/examples/features/auto-imports">



</link-example>

## Types

Under the hood, Nuxt auto generates the file `.nuxt/imports.d.ts` to declare the types.

Be aware that you have to run [`nuxt prepare`](/docs/4.x/api/commands/prepare), [`nuxt dev`](/docs/4.x/api/commands/dev) or [`nuxt build`](/docs/4.x/api/commands/build) in order to let Nuxt generate the types.

<note>

If you create a composable without having the dev server running, TypeScript will throw an error, such as `Cannot find name 'useBar'.`

</note>

## Examples

### Nested Composables

You can use a composable within another composable using auto imports:

```ts [app/composables/test.ts]
export const useFoo = () => {
  const nuxtApp = useNuxtApp()
  const bar = useBar()
}
```

### Access plugin injections

You can access [plugin injections](/docs/4.x/directory-structure/app/plugins#providing-helpers) from composables:

```ts [app/composables/test.ts]
export const useHello = () => {
  const nuxtApp = useNuxtApp()
  return nuxtApp.$hello
}
```

## How Files Are Scanned

Nuxt only scans files at the top level of the [`app/composables/` directory](/docs/4.x/directory-structure/app/composables), e.g.:

```bash [Directory Structure]
-| composables/
---| index.ts     // scanned
---| useFoo.ts    // scanned
---| nested/
-----| utils.ts   // not scanned
```

Only `app/composables/index.ts` and `app/composables/useFoo.ts` would be searched for imports.

To get auto imports working for nested modules, you could either re-export them (recommended) or configure the scanner to include nested directories:

**Example:** Re-export the composables you need from the `app/composables/index.ts` file:

```ts [app/composables/index.ts]
// Enables auto import for this export
export { utils } from './nested/utils.ts'
```

**Example:** Scan nested directories inside the `app/composables/` folder:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  imports: {
    dirs: [
      // Scan top-level composables
      '~/composables',
      // ... or scan composables nested one level deep with a specific name and file extension
      '~/composables/*/index.{ts,js,mjs,mts}',
      // ... or scan all composables within given directory
      '~/composables/**',
    ],
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/config-extends.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/config-extends.md

# Layers

> This example shows how to use the extends key in `nuxt.config.ts`.

This example shows how to use the `extends` key in `nuxt.config.ts` to use the `base/` directory as a base Nuxt application, and use its components, composables or config and override them if necessary.

<read-more to="/docs/getting-started/layers">



</read-more>

<sandbox branch="main" dir="examples/advanced/config-extends" file="nuxt.config.ts" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/configuration.md

# Source: https://nuxt.com/raw/docs/3.x/bridge/configuration.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/configuration.md

# Source: https://nuxt.com/raw/docs/4.x/migration/configuration.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/configuration.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/configuration.md

# Configuration

> Nuxt is configured with sensible defaults to make you productive.

By default, Nuxt is configured to cover most use cases. The [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file can override or extend this default configuration.

## Nuxt Configuration

The [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file is located at the root of a Nuxt project and can override or extend the application's behavior.

A minimal configuration file exports the `defineNuxtConfig` function containing an object with your configuration. The `defineNuxtConfig` helper is globally available without import.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  // My Nuxt config
})
```

This file will often be mentioned in the documentation, for example to add custom scripts, register modules or change rendering modes.

<read-more to="/docs/4.x/api/configuration/nuxt-config">

Every option is described in the **Configuration Reference**.

</read-more>

<note>

You don't have to use TypeScript to build an application with Nuxt. However, it is strongly recommended to use the `.ts` extension for the `nuxt.config` file. This way you can benefit from hints in your IDE to avoid typos and mistakes while editing your configuration.

</note>

### Environment Overrides

You can configure fully typed, per-environment overrides in your nuxt.config

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true },
    },
  },
  $development: {
    //
  },
  $env: {
    staging: {
      //
    },
  },
})
```

To select an environment when running a Nuxt CLI command, simply pass the name to the `--envName` flag, like so: `nuxt build --envName staging`.

To learn more about the mechanism behind these overrides, please refer to the `c12` documentation on [environment-specific configuration](https://github.com/unjs/c12?tab=readme-ov-file#environment-specific-configuration).

<video-accordion title="Watch a video from Alexander Lichter about the env-aware nuxt.config.ts" video-id="DFZI2iVCrNc">



</video-accordion>

<note>

If you're authoring layers, you can also use the `$meta` key to provide metadata that you or the consumers of your layer might use.

</note>

### Environment Variables and Private Tokens

The `runtimeConfig` API exposes values like environment variables to the rest of your application. By default, these keys are only available server-side. The keys within `runtimeConfig.public` and `runtimeConfig.app` (which is used by Nuxt internally) are also available client-side.

Those values should be defined in `nuxt.config` and can be overridden using environment variables.

<code-group>

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available server-side
    apiSecret: '123',
    // Keys within public are also exposed client-side
    public: {
      apiBase: '/api',
    },
  },
})
```

```ini [.env]
# This will override the value of apiSecret
NUXT_API_SECRET=api_secret_token
```

</code-group>

These variables are exposed to the rest of your application using the [`useRuntimeConfig()`](/docs/4.x/api/composables/use-runtime-config) composable.

```vue [app/pages/index.vue]
<script setup lang="ts">
const runtimeConfig = useRuntimeConfig()
</script>
```

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

## App Configuration

The `app.config.ts` file, located in the source directory (by default `app/`), is used to expose public variables that can be determined at build time. Contrary to the `runtimeConfig` option, these cannot be overridden using environment variables.

A minimal configuration file exports the `defineAppConfig` function containing an object with your configuration. The `defineAppConfig` helper is globally available without import.

```ts [app/app.config.ts]
export default defineAppConfig({
  title: 'Hello Nuxt',
  theme: {
    dark: true,
    colors: {
      primary: '#ff0000',
    },
  },
})
```

These variables are exposed to the rest of your application using the [`useAppConfig`](/docs/4.x/api/composables/use-app-config) composable.

```vue [app/pages/index.vue]
<script setup lang="ts">
const appConfig = useAppConfig()
</script>
```

<read-more to="/docs/4.x/directory-structure/app/app-config">



</read-more>

## `runtimeConfig` vs. `app.config`

As stated above, `runtimeConfig` and `app.config` are both used to expose variables to the rest of your application. To determine whether you should use one or the other, here are some guidelines:

- `runtimeConfig`: Private or public tokens that need to be specified after build using environment variables.
- `app.config`: Public tokens that are determined at build time, website configuration such as theme variant, title and any project config that are not sensitive.

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      <code>
        runtimeConfig
      </code>
    </th>
    
    <th>
      <code>
        app.config
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Client-side
    </td>
    
    <td>
      Hydrated
    </td>
    
    <td>
      Bundled
    </td>
  </tr>
  
  <tr>
    <td>
      Environment variables
    </td>
    
    <td>
      ✅ Yes
    </td>
    
    <td>
      ❌ No
    </td>
  </tr>
  
  <tr>
    <td>
      Reactive
    </td>
    
    <td>
      ✅ Yes
    </td>
    
    <td>
      ✅ Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Types support
    </td>
    
    <td>
      ✅ Partial
    </td>
    
    <td>
      ✅ Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Configuration per request
    </td>
    
    <td>
      ❌ No
    </td>
    
    <td>
      ✅ Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Hot module replacement
    </td>
    
    <td>
      ❌ No
    </td>
    
    <td>
      ✅ Yes
    </td>
  </tr>
  
  <tr>
    <td>
      Non-primitive JS types
    </td>
    
    <td>
      ❌ No
    </td>
    
    <td>
      ✅ Yes
    </td>
  </tr>
</tbody>
</table>

## External Configuration Files

Nuxt uses [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file as the single source of truth for configurations and skips reading external configuration files. During the course of building your project, you may have a need to configure those. The following table highlights common configurations and, where applicable, how they can be configured with Nuxt.

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Config File
    </th>
    
    <th>
      How To Configure
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://nitro.build" rel="nofollow">
        Nitro
      </a>
    </td>
    
    <td>
      <del>
        <code>
          nitro.config.ts
        </code>
      </del>
    </td>
    
    <td>
      Use <a href="/docs/4.x/api/nuxt-config#nitro">
        <code>
          nitro
        </code>
      </a>
      
       key in <code>
        nuxt.config
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://postcss.org" rel="nofollow">
        PostCSS
      </a>
    </td>
    
    <td>
      <del>
        <code>
          postcss.config.js
        </code>
      </del>
    </td>
    
    <td>
      Use <a href="/docs/4.x/api/nuxt-config#postcss">
        <code>
          postcss
        </code>
      </a>
      
       key in <code>
        nuxt.config
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://vite.dev" rel="nofollow">
        Vite
      </a>
    </td>
    
    <td>
      <del>
        <code>
          vite.config.ts
        </code>
      </del>
    </td>
    
    <td>
      Use <a href="/docs/4.x/api/nuxt-config#vite">
        <code>
          vite
        </code>
      </a>
      
       key in <code>
        nuxt.config
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://webpack.js.org" rel="nofollow">
        webpack
      </a>
    </td>
    
    <td>
      <del>
        <code>
          webpack.config.ts
        </code>
      </del>
    </td>
    
    <td>
      Use <a href="/docs/4.x/api/nuxt-config#webpack-1">
        <code>
          webpack
        </code>
      </a>
      
       key in <code>
        nuxt.config
      </code>
    </td>
  </tr>
</tbody>
</table>

Here is a list of other common config files:

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Config File
    </th>
    
    <th>
      How To Configure
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://www.typescriptlang.org" rel="nofollow">
        TypeScript
      </a>
    </td>
    
    <td>
      <code>
        tsconfig.json
      </code>
    </td>
    
    <td>
      <a href="/docs/4.x/directory-structure/tsconfig">
        More Info
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://eslint.org" rel="nofollow">
        ESLint
      </a>
    </td>
    
    <td>
      <code>
        eslint.config.js
      </code>
    </td>
    
    <td>
      <a href="https://eslint.org/docs/latest/use/configure/configuration-files" rel="nofollow">
        More Info
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://prettier.io" rel="nofollow">
        Prettier
      </a>
    </td>
    
    <td>
      <code>
        prettier.config.js
      </code>
    </td>
    
    <td>
      <a href="https://prettier.io/docs/configuration.html" rel="nofollow">
        More Info
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://stylelint.io" rel="nofollow">
        Stylelint
      </a>
    </td>
    
    <td>
      <code>
        stylelint.config.js
      </code>
    </td>
    
    <td>
      <a href="https://stylelint.io/user-guide/configure/" rel="nofollow">
        More Info
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://tailwindcss.com" rel="nofollow">
        TailwindCSS
      </a>
    </td>
    
    <td>
      <code>
        tailwind.config.js
      </code>
    </td>
    
    <td>
      <a href="https://tailwindcss.nuxtjs.org/tailwindcss/configuration/" rel="nofollow">
        More Info
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://vitest.dev" rel="nofollow">
        Vitest
      </a>
    </td>
    
    <td>
      <code>
        vitest.config.ts
      </code>
    </td>
    
    <td>
      <a href="https://vitest.dev/config/" rel="nofollow">
        More Info
      </a>
    </td>
  </tr>
</tbody>
</table>

## Vue Configuration

### With Vite

If you need to pass options to `@vitejs/plugin-vue` or `@vitejs/plugin-vue-jsx`, you can do this in your `nuxt.config` file.

- `vite.vue` for `@vitejs/plugin-vue`. Check [available options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue).
- `vite.vueJsx` for `@vitejs/plugin-vue-jsx`. Check [available options](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue-jsx).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  vite: {
    vue: {
      customElement: true,
    },
    vueJsx: {
      mergeProps: true,
    },
  },
})
```

<read-more to="/docs/4.x/api/configuration/nuxt-config#vue">



</read-more>

### With webpack

If you use webpack and need to configure `vue-loader`, you can do this using `webpack.loaders.vue` key inside your `nuxt.config` file. The available options are [defined here](https://github.com/vuejs/vue-loader/blob/main/src/index.ts#L32-L62).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  webpack: {
    loaders: {
      vue: {
        hotReload: true,
      },
    },
  },
})
```

<read-more to="/docs/4.x/api/configuration/nuxt-config#loaders">



</read-more>

### Enabling Experimental Vue Features

You may need to enable experimental features in Vue, such as `propsDestructure`. Nuxt provides an easy way to do that in `nuxt.config.ts`, no matter which builder you are using:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  vue: {
    propsDestructure: true,
  },
})
```

#### experimental `reactivityTransform` migration from Vue 3.4 and Nuxt 3.9

Since Nuxt 3.9 and Vue 3.4, `reactivityTransform` has been moved from Vue to Vue Macros which has a [Nuxt integration](https://vue-macros.dev/guide/nuxt-integration.html).

<read-more to="/docs/4.x/api/configuration/nuxt-config#vue-1">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/content.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/content.md

# content

> Use the content/ directory to create a file-based CMS for your application.

[Nuxt Content](https://content.nuxt.com) reads the `content/` directory in your project and parses `.md`, `.yml`, `.csv` and `.json` files to create a file-based CMS for your application.

- Render your content with built-in components.
- Query your content with a MongoDB-like API.
- Use your Vue components in Markdown files with the MDC syntax.
- Automatically generate your navigation.

<read-more target="_blank" to="https://content.nuxt.com">

Learn more in **Nuxt Content** documentation.

</read-more>

## Enable Nuxt Content

Install the `@nuxt/content` module in your project as well as adding it to your `nuxt.config.ts` with one command:

```bash [Terminal]
npx nuxt module add content
```

## Create Content

Place your markdown files inside the `content/` directory:

```md [content/index.md]
# Hello Content
```

The module automatically loads and parses them.

## Render Content

To render content pages, add a [catch-all route](/docs/4.x/directory-structure/app/pages/#catch-all-route) using the [`<ContentRenderer>`](https://content.nuxt.com/docs/components/content-renderer) component:

```vue [app/pages/[...slug].vue]
<script lang="ts" setup>
const route = useRoute()
const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('content').path(route.path).first()
})
</script>

<template>
  <div>
    <header><!-- ... --></header>

    <ContentRenderer
      v-if="page"
      :value="page"
    />

    <footer><!-- ... --></footer>
  </div>
</template>
```

## Documentation

<tip icon="i-lucide-book">

Head over to [https://content.nuxt.com](https://content.nuxt.com) to learn more about the Content module features, such as how to build queries and use Vue components in your Markdown files with the MDC syntax.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/context.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/context.md

# Context

> Nuxt Kit provides a set of utilities to help you work with context.

Nuxt modules allow you to enhance Nuxt's capabilities. They offer a structured way to keep your code organized and modular. If you're looking to break down your module into smaller components, Nuxt offers the `useNuxt` and `tryUseNuxt` functions. These functions enable you to conveniently access the Nuxt instance from the context without having to pass it as an argument.

<note>

When you're working with the `setup` function in Nuxt modules, Nuxt is already provided as the second argument. This means you can access it directly without needing to call `useNuxt()`.

</note>

## `useNuxt`

Get the Nuxt instance from the context. It will throw an error if Nuxt is not available.

### Usage

```ts
import { useNuxt } from '@nuxt/kit'

const setupSomeFeature = () => {
  const nuxt = useNuxt()

  // You can now use the nuxt instance
  console.log(nuxt.options)
}
```

### Type

```tstwoslash
// @errors: 2391
import type { Nuxt } from '@nuxt/schema'
// ---cut---
function useNuxt (): Nuxt
```

### Return Value

The `useNuxt` function returns the Nuxt instance, which contains all the options and methods available in Nuxt.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        NuxtOptions
      </code>
    </td>
    
    <td>
      The resolved Nuxt configuration.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hooks
      </code>
    </td>
    
    <td>
      <code>
        Hookable<NuxtHooks>
      </code>
    </td>
    
    <td>
      The Nuxt hook system. Allows registering and listening to lifecycle events.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hook
      </code>
    </td>
    
    <td>
      <code>
        (name: string, (...args: any[]) => Promise<void> | void) => () => void
      </code>
    </td>
    
    <td>
      Shortcut for <code>
        nuxt.hooks.hook
      </code>
      
      . Registers a single callback for a specific lifecycle hook.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        callHook
      </code>
    </td>
    
    <td>
      <code>
        (name: string, ...args: any[]) => Promise<any>
      </code>
    </td>
    
    <td>
      Shortcut for <code>
        nuxt.hooks.callHook
      </code>
      
      . Triggers a lifecycle hook manually and runs all registered callbacks.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        addHooks
      </code>
    </td>
    
    <td>
      <code>
        (configHooks: NestedHooks) => () => void
      </code>
    </td>
    
    <td>
      Shortcut for <code>
        nuxt.hooks.addHooks
      </code>
      
      . Registers multiple hooks at once.
    </td>
  </tr>
</tbody>
</table>

### Examples

<code-group>

```ts [setupTranspilation.ts]twoslash
import { useNuxt } from '@nuxt/kit'

export const setupTranspilation = () => {
  const nuxt = useNuxt()

  if (nuxt.options.builder === '@nuxt/webpack-builder') {
    nuxt.options.build.transpile ||= []
    nuxt.options.build.transpile.push('xstate')
  }
}
```

```ts [module.ts]twoslash
// @module: esnext
// @filename: setupTranspilation.ts
export const setupTranspilation = () => {}
// @filename: module.ts
import { defineNuxtModule } from '@nuxt/kit'
// ---cut---
import { setupTranspilation } from './setupTranspilation'

export default defineNuxtModule({
  setup () {
    setupTranspilation()
  },
})
```

</code-group>

## `tryUseNuxt`

Get the Nuxt instance from the context. It will return `null` if Nuxt is not available.

### Usage

```tstwoslash
import { tryUseNuxt } from '@nuxt/kit'

function setupSomething () {
  const nuxt = tryUseNuxt()

  if (nuxt) {
    // You can now use the nuxt instance
    console.log(nuxt.options)
  } else {
    console.log('Nuxt is not available')
  }
}
```

### Type

```tstwoslash
// @errors: 2391
import type { Nuxt } from '@nuxt/schema'
// ---cut---
function tryUseNuxt (): Nuxt | null
```

### Return Value

The `tryUseNuxt` function returns the Nuxt instance if available, or `null` if Nuxt is not available.

The Nuxt instance as described in the `useNuxt` section.

### Examples

<code-group>

```ts [requireSiteConfig.ts]twoslash
declare module 'nuxt/schema' {
  interface NuxtOptions {
    siteConfig: SiteConfig
  }
}
// ---cut---
import { tryUseNuxt } from '@nuxt/kit'

interface SiteConfig {
  title?: string
}

export const requireSiteConfig = (): SiteConfig => {
  const nuxt = tryUseNuxt()
  if (!nuxt) {
    return {}
  }
  return nuxt.options.siteConfig
}
```

```ts [module.ts]twoslash
// @module: esnext
// @filename: requireSiteConfig.ts
interface SiteConfig {
  title?: string
}
export const requireSiteConfig = (): SiteConfig => {
  return {}
}
// @filename: module.ts
// ---cut---
import { defineNuxtModule, useNuxt } from '@nuxt/kit'
import { requireSiteConfig } from './requireSiteConfig'

export default defineNuxtModule({
  setup (_, nuxt) {
    const config = requireSiteConfig()
    nuxt.options.app.head.title = config.title
  },
})
```

</code-group>

---

# Source: https://nuxt.com/raw/docs/3.x/community/contribution.md

# Source: https://nuxt.com/raw/docs/4.x/community/contribution.md

# Contribution

> Nuxt is a community project - and so we love contributions of all kinds! ❤️

There is a range of different ways you might be able to contribute to the Nuxt ecosystem.

## Ecosystem

The Nuxt ecosystem includes many different projects and organizations:

- [nuxt/](https://github.com/nuxt) - core repositories for the Nuxt framework itself. [**nuxt/nuxt**](https://github.com/nuxt/nuxt) contains the Nuxt framework (both versions 2 and 3).
- [nuxt-modules/](https://github.com/nuxt-modules) - community-contributed and maintained modules and libraries. There is a [process to migrate a module](/docs/4.x/guide/modules/ecosystem) to `nuxt-modules`. While these modules have individual maintainers, they are not dependent on a single person.
- [unjs/](https://github.com/unjs) - many of these libraries are used throughout the Nuxt ecosystem. They are designed to be universal libraries that are framework- and environment-agnostic. We welcome contributions and usage by other frameworks and projects.

## How To Contribute

### Triage Issues and Help Out in Discussions

Check out the issues and discussions for the project you want to help. For example, here are [the issues board](https://github.com/nuxt/nuxt/issues) and [discussions](https://github.com/nuxt/nuxt/discussions) for Nuxt. Helping other users, sharing workarounds, creating reproductions, or even poking into a bug a little bit and sharing your findings makes a huge difference.

### Creating an Issue

Thank you for taking the time to create an issue! ❤️

- **Reporting bugs**: Check out [our guide](/docs/4.x/community/reporting-bugs) for some things to do before opening an issue.
- **Feature requests**: Check that there is not an existing issue or discussion covering the scope of the feature you have in mind. If the feature is to another part of the Nuxt ecosystem (such as a module), please consider raising a feature request there first. If the feature you have in mind is general or the API is not entirely clear, consider opening a discussion in the **Ideas** section to discuss with the community first.

We'll do our best to follow our [internal issue decision making flowchart](https://mermaid.live/view#pako:eNqFlE1v2zAMhv8K4UuToslhx2Bo0TZt12Edhm7YMCAXWqJtorLk6qOpkfS_j7KdfpyWQ-BQr8mHL6nsCuU0FauiMm6rGvQRfq03FuRzvvvTYIQHthpcBT_ugQNwPHuZjheLxf4i1VDx8x4udrf5EBCOQvSsYg4ffS79KS9pmX9QALTgyid2KYB7Ih-4bmKWbDk2YB0E1gRUVaRi-FDmmjAmT3u4nB3DmoNKIUA1BsGSohA49jnVMQhHbDh_EZQUImyxh-gAtfaiG-KWSJ-N8nt6YtpCdgEeE5rXPOdav5YwWJIJU7zrvNADV9C7JBIyIC07Wxupkx3LFQ5vCkguRno5f9fP2qnUko0Y2dk9rGdvHAa9IIhVGlCp5FFNPN-ce4DKeXBd53xMliOLp9IZtyORQVsnrGm-WJzejtUu5fFqdr5FGQ3bLslYvGthjZbJTLpReZG5_lLYw7XQ_CbPVT92ws9gnEJj-v84dk-PiaXnmF1XGAaPsOsMKywNvYmG80ZohV8k4wDR9_N3KN_dHm5mh1lnkM5FsYzRfNiTvJoT5gnQsl6uxjqXLhkNQ9syHJ0UZZ8ERUIlNShr6N8gZDEliR-ow7QZa0fhY4LoHLRo-8N7ZxPwjRj5ZZYXpvOSNs9v3Jjs8NXB4ets92xan3zydXZHvj64lKMayh4-gZC1bjASW2ipLeWuzIuToiXfImu5rbucclMIc0ubYiWPGv3DptjYF9Fhiu5nb1Wxij7RSZE6jZHWjLXHtlhVaIJESXN0_m68_sO_wMs_oO9gyg) when responding to issues.

### Send a Pull Request

We always welcome pull requests! ❤️

#### Before You Start

Before you fix a bug, we recommend that you check whether **there's an issue that describes it**, as it's possible it's a documentation issue or that there is some context that would be helpful to know.

If you're working on a feature, then we ask that you **open a feature request issue first** to discuss with the maintainers whether the feature is desired - and the design of those features. This helps save time for both the maintainers and the contributors and means that features can be shipped faster. The issue **should be confirmed** by a framework team member before building out a feature in a pull request.

For typo fixes, it's recommended to batch multiple typo fixes into one pull request to maintain a cleaner commit history.

For bigger changes to Nuxt itself, we recommend that you first [create a Nuxt module](/docs/4.x/community/contribution#create-a-module) and implement the feature there. This allows for quick proof-of-concept. You can then [create an RFC](/docs/4.x/community/contribution#make-an-rfc) in the form of a discussion. As users adopt it and you gather feedback, it can then be refined and either added to Nuxt core or continue as a standalone module.

#### Commit Conventions

We use [Conventional Commits](https://www.conventionalcommits.org) for commit messages, which [allows a changelog to be auto-generated](https://github.com/unjs/changelogen) based on the commits. Please read the guide through if you aren't familiar with it already.

Note that `fix:` and `feat:` are for **actual code changes** (that might affect logic). For typo or document changes, use `docs:` or `chore:` instead:

- ~~fix: typo~~ -> `docs: fix typo`

If you are working in a project with a monorepo, like `nuxt/nuxt`, ensure that you specify the main scope of your commit in brackets. For example: `feat(kit): add 'addMagicStuff' utility`.

#### Making the Pull Request

If you don't know how to send a pull request, we recommend reading [the guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).

When sending a pull request, make sure your PR's title also follows the [Commit Convention](/docs/4.x/community/contribution#commit-conventions).

If your PR fixes or resolves existing issues, please make sure you mention them in the PR description.

It's ok to have multiple commits in a single PR; you don't need to rebase or force push for your changes as we will use `Squash and Merge` to squash the commits into one commit when merging.

We do not add any commit hooks to allow for quick commits. But before you make a pull request, you should ensure that any lint/test scripts are passing.

In general, please also make sure that there are no *unrelated* changes in a PR. For example, if your editor has made any changes to whitespace or formatting elsewhere in a file that you edited, please revert these so it is more obvious what your PR changes. And please avoid including multiple unrelated features or fixes in a single PR. If it is possible to separate them, it is better to have multiple PRs to review and merge separately. In general, a PR should do *one thing only*.

#### Once You've Made a Pull Request

Once you've made a pull request, we'll do our best to review it promptly.

If we assign it to a maintainer, then that means that person will take special care to review it and implement any changes that may be required.

If we request changes on a PR, please ignore the red text! It doesn't mean we think it's a bad PR - it's just a way of easily telling the status of a list of pull requests at a glance.

If we mark a PR as 'pending', that means we likely have another task to do in reviewing the PR - it's an internal note-to-self, and not necessarily a reflection on whether the PR is a good idea or not. We will do our best to explain via a comment the reason for the pending status.

We'll do our best to follow [our PR decision making flowchart](https://mermaid.live/view#pako:eNp9VE1v2kAQ_SsjXzBSEqlALlaUisSh0ACK2l4qcVm8Y9hi7672Iwly-O-ZtYPt5FAOCHbee_PmzdpVlCmOURLlhXrJ9sw4-JNuJNBnWs1UQafIQVjrERyWumAOv58-AJeXt29_0b7BXbWwwL0uRPa1vlZvcB_fF8oiMMmB2QM4BXkt3UoON7Lh3LWaDz2SVkK6QGt7DHvw0CKt5sxCKaQoWQEGtVHcZ04oGdw04LTVngW_LHOeFcURGGz97mw6PSv-iJdsi0UCA4nI7SfNwc3W3JZit3eQ1SZFDlKB15yswQ2MgbOjbYeatY3n8bcr-IWlekYYaJRcyB04I9gOB1CEfkF5dAVTzmFAtnqn4-bUYAiMMmHZgWhNPRhgus5mW2BATxq0NkIZ4Y4NbNjzE2ZchBzcHmGLe_ZMSKCcyRXyLrVFa_5n_PBK2xKy3kk9eOjULUdltk6C8kI-7NFDr8f4EVGDoqlp-wa4sJm3ltIMIuZ_mTQXJyTSkQZtunPqsKxShV9GKdkBYe1fHXjpbcjlvONlO9Kqx_M7YHmOmav_luxfE5zKwVs09hM5DLSupgYDlr5flDkwo7ykixKG-xDsUly1LZ-uY32dgDc7lG7YqwbNp0msJwmIUivjWFtfd-xRrEcJ7Omydz37qFplHOtxEp4GskI2qB5dRCWakglOz3oV8JuITJa4iRL6yZk5bKKNPBGOead-H2UWJc54vIiaW53SPgwrz4fIhVNm1bw76lfI6R2_MW21) when responding and reviewing to pull requests.

### AI-Assisted Contributions

We welcome the thoughtful use of AI tools when contributing to Nuxt, yet ask all contributors to follow [two core principles](https://roe.dev/blog/using-ai-in-open-source).

#### Never let an LLM speak for you

- All comments, issues, and pull request descriptions should be written in your own voice
- We value clear, human communication over perfect grammar or spelling
- Avoid copy-pasting AI-generated summaries that don't reflect your own understanding

#### Never let an LLM think for you

- Feel free to use AI tools to generate code or explore ideas
- Only submit contributions you fully understand and can explain
- Contributions should reflect your own reasoning and problem-solving

Our aim is ensuring quality and maintaining the joy of collaborating and communicating with real people. If you have ideas for improving our policy on AI in the Nuxt community, we'd love to hear them! ❤️

### Create a Module

If you've built something with Nuxt that's cool, why not [extract it into a module](/docs/4.x/guide/modules), so it can be shared with others? We have [many excellent modules already](/modules), but there's always room for more.

If you need help while building it, feel free to [check in with us](/docs/4.x/community/getting-help).

### Make an RFC

We highly recommend [creating a module](/docs/4.x/community/contribution#create-a-module) first to test out big new features and gain community adoption.

If you have done this already, or it's not appropriate to create a new module, then please start by creating a new discussion. Make sure it explains your thinking as clearly as possible. Include code examples or function signatures for new APIs. Reference existing issues or pain points with examples.

If we think this should be an RFC, we'll change the category to RFC and broadcast it more widely for feedback.

An RFC will then move through the following stages:

- `rfc: active` - currently open for comment
- `rfc: approved` - approved by the Nuxt team
- `rfc: ready to implement` - an issue has been created and assigned to implement
- `rfc: shipped` - implemented
- `rfc: archived` - not approved, but archived for future reference

### Conventions Across Ecosystem

The following conventions are *required* within the `nuxt/` organization and recommended for other maintainers in the ecosystem.

#### Module Conventions

Modules should follow the [Nuxt module template](https://github.com/nuxt/starter/tree/module). See [module guide](/docs/4.x/guide/modules) for more information.

#### Use Core `unjs/` Libraries

We recommend the following libraries which are used throughout the ecosystem:

- [pathe](https://github.com/unjs/pathe) - universal path utilities (replacement for node `path`)
- [ufo](https://github.com/unjs/ufo) - URL parsing and joining utilities
- [obuild](https://github.com/unjs/obuild) - rolldown-powered build system
- ... check out the rest of the [unjs/](https://github.com/unjs) organization for many more!

#### Use ESM Syntax and Default to `type: module`

Most of the Nuxt ecosystem can consume ESM directly. In general we advocate that you avoid using CJS-specific code, such as `__dirname` and `require` statements. You can [read more about ESM](/docs/4.x/guide/concepts/esm).

#### What's Corepack

[Corepack](https://github.com/nodejs/corepack) makes sure you are using the correct version for package manager when you run corresponding commands. Projects might have `packageManager` field in their `package.json`.

Under projects with configuration as shown below, Corepack will install `v7.5.0` of `pnpm` (if you don't have it already) and use it to run your commands.

```jsonc [package.json]
{
  "packageManager": "pnpm@7.5.0"
}
```

#### Use ESLint

We use [ESLint](https://eslint.org) for both linting and formatting with [`@nuxt/eslint`](https://github.com/nuxt/eslint).

##### IDE Setup

We recommend using [VS Code](https://code.visualstudio.com) along with the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint). If you would like, you can enable auto-fix and formatting when you save the code you are editing:

```json [settings.json]
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}
```

#### No Prettier

Since ESLint is already configured to format the code, there is no need to duplicate the functionality with Prettier. To format the code, you can run `yarn lint --fix`, `pnpm lint --fix`, `bun run lint --fix`, or `deno run lint --fix` or referring the [ESLint section](/docs/4.x/community/contribution#use-eslint) for IDE Setup.

If you have Prettier installed in your editor, we recommend you disable it when working on the project to avoid conflict.

#### Package Manager

We recommend `pnpm` as a package manager for modules, libraries and apps.

It is important to enable Corepack to ensure you are on the same version of the package manager as the project. Corepack is built-in to new node versions for seamless package manager integration.

To enable it, run

```bash [Terminal]
corepack enable
```

You only need to do this one time, after Node.js is installed on your computer.

## Documentation Style Guide

Documentation is an essential part of Nuxt. We aim to be an intuitive framework - and a big part of that is making sure that both the developer experience and the docs are perfect across the ecosystem. 👌

Here are some tips that may help improve your documentation:

- Avoid subjective words like *simply*, *just*, *obviously...* when possible.<br />

Keep in mind your readers can have different backgrounds and experiences. Therefore, these words don't convey meaning and can be harmful.<caution icon="i-lucide-circle-x">

Simply make sure the function returns a promise.

</caution>

<tip icon="i-lucide-circle-check">

Make sure the function returns a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).

</tip>
- Prefer [active voice](https://developers.google.com/tech-writing/one/active-voice).<caution icon="i-lucide-circle-x">

An error will be thrown by Nuxt.

</caution>

<tip icon="i-lucide-circle-check">

Nuxt will throw an error.

</tip>

<read-more to="/docs/4.x/community/framework-contribution#documentation-guide">

Learn how to contribute to the documentation.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/create-error.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/create-error.md

# createError

> Create an error object with additional metadata.

You can use this function to create an error object with additional metadata. It is usable in both the Vue and Nitro portions of your app, and is meant to be thrown.

## Parameters

- `err`: `string | { cause, data, message, name, stack, status, statusText, fatal }`

You can pass either a string or an object to the `createError` function. If you pass a string, it will be used as the error `message`, and the `status` will default to `500`. If you pass an object, you can set multiple properties of the error, such as `status`, `message`, and other error properties.

## In Vue App

If you throw an error created with `createError`:

- on server-side, it will trigger a full-screen error page which you can clear with `clearError`.
- on client-side, it will throw a non-fatal error for you to handle. If you need to trigger a full-screen error page, then you can do this by setting `fatal: true`.

### Example

```vue [app/pages/movies/[slug].vue]
<script setup lang="ts">
const route = useRoute()
const { data } = await useFetch(`/api/movies/${route.params.slug}`)
if (!data.value) {
  throw createError({ status: 404, statusText: 'Page Not Found' })
}
</script>
```

## In API Routes

Use `createError` to trigger error handling in server API routes.

### Example

```ts [server/api/error.ts]
export default eventHandler(() => {
  throw createError({
    status: 404,
    statusText: 'Page Not Found',
  })
})
```

In API routes, using `createError` by passing an object with a short `statusText` is recommended because it can be accessed on the client side. Otherwise, a `message` passed to `createError` on an API route will not propagate to the client. Alternatively, you can use the `data` property to pass data back to the client. In any case, always consider avoiding to put dynamic user input to the message to avoid potential security issues.

<read-more to="/docs/4.x/getting-started/error-handling">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/recipes/custom-routing.md

# Source: https://nuxt.com/raw/docs/4.x/guide/recipes/custom-routing.md

# Custom Routing

> In Nuxt, your routing is defined by the structure of your files inside the pages directory. However, since it uses vue-router under the hood, Nuxt offers you several ways to add custom routes in your project.

## Adding custom routes

In Nuxt, your routing is defined by the structure of your files inside the [app/pages directory](/docs/4.x/directory-structure/app/pages). However, since it uses [vue-router](https://router.vuejs.org) under the hood, Nuxt offers you several ways to add custom routes in your project.

### Router Config

Using [router options](/docs/4.x/guide/recipes/custom-routing#router-options), you can optionally override or extend your routes using a function that accepts the scanned routes and returns customized routes.

If it returns `null` or `undefined`, Nuxt will fall back to the default routes (useful to modify input array).

```ts [router.options.ts]
import type { RouterConfig } from '@nuxt/schema'

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions#routes
  routes: _routes => [
    {
      name: 'home',
      path: '/',
      component: () => import('~/pages/home.vue'),
    },
  ],
} satisfies RouterConfig
```

<note>

Nuxt will not augment any new routes you return from the `routes` function with metadata defined in `definePageMeta` of the component you provide. If you want that to happen, you should use the `pages:extend` hook which is [called at build-time](/docs/4.x/api/advanced/hooks#nuxt-hooks-build-time).

</note>

### Pages Hook

You can add, change or remove pages from the scanned routes with the `pages:extend` nuxt hook.

For example, to prevent creating routes for any `.ts` files:

```ts [nuxt.config.ts]
import type { NuxtPage } from '@nuxt/schema'

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (pages) {
      // add a route
      pages.push({
        name: 'profile',
        path: '/profile',
        file: '~/extra-pages/profile.vue',
      })

      // remove routes
      function removePagesMatching (pattern: RegExp, pages: NuxtPage[] = []) {
        const pagesToRemove: NuxtPage[] = []
        for (const page of pages) {
          if (page.file && pattern.test(page.file)) {
            pagesToRemove.push(page)
          } else {
            removePagesMatching(pattern, page.children)
          }
        }
        for (const page of pagesToRemove) {
          pages.splice(pages.indexOf(page), 1)
        }
      }
      removePagesMatching(/\.ts$/, pages)
    },
  },
})
```

### Nuxt Module

If you plan to add a whole set of pages related with a specific functionality, you might want to use a [Nuxt module](/modules).

The [Nuxt kit](/docs/4.x/guide/going-further/kit) provides a few ways [to add routes](/docs/4.x/api/kit/pages):

- [`extendPages`](/docs/4.x/api/kit/pages#extendpages) (callback: pages => void)
- [`extendRouteRules`](/docs/4.x/api/kit/pages#extendrouterules) (route: string, rule: NitroRouteConfig, options: ExtendRouteRulesOptions)

## Router Options

On top of customizing options for [`vue-router`](https://router.vuejs.org/api/interfaces/routeroptions), Nuxt offers [additional options](/docs/4.x/api/nuxt-config#router) to customize the router.

### Using `router.options`

This is the recommended way to specify [router options](/docs/4.x/api/nuxt-config#router).

```ts [app/router.options.ts]
import type { RouterConfig } from '@nuxt/schema'

export default {
} satisfies RouterConfig
```

It is possible to add more router options files by adding files within the `pages:routerOptions` hook. Later items in the array override earlier ones.

<callout>

Adding a router options file in this hook will switch on page-based routing, unless `optional` is set, in which case it will only apply when page-based routing is already enabled.

</callout>

```ts [nuxt.config.ts]
import { createResolver } from '@nuxt/kit'

export default defineNuxtConfig({
  hooks: {
    'pages:routerOptions' ({ files }) {
      const resolver = createResolver(import.meta.url)
      // add a route
      files.push({
        path: resolver.resolve('./runtime/router-options'),
        optional: true,
      })
    },
  },
})
```

### Using `nuxt.config`

**Note:** Only JSON serializable [options](/docs/4.x/api/nuxt-config#router) are configurable:

- `linkActiveClass`
- `linkExactActiveClass`
- `end`
- `sensitive`
- `strict`
- `hashMode`
- `scrollBehaviorType`

```ts [nuxt.config]
export default defineNuxtConfig({
  router: {
    options: {},
  },
})
```

### Hash Mode (SPA)

You can enable hash history in SPA mode using the `hashMode` [config](/docs/4.x/api/nuxt-config#router). In this mode, router uses a hash character (#) before the actual URL that is internally passed. When enabled, the **URL is never sent to the server** and **SSR is not supported**.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ssr: false,
  router: {
    options: {
      hashMode: true,
    },
  },
})
```

### Scroll Behavior for hash links

You can optionally customize the scroll behavior for hash links. When you set the [config](/docs/4.x/api/nuxt-config#router) to be `smooth` and you load a page with a hash link (e.g. `https://example.com/blog/my-article#comments`), you will see that the browser smoothly scrolls to this anchor.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  router: {
    options: {
      scrollBehaviorType: 'smooth',
    },
  },
})
```

#### Custom History (advanced)

You can optionally override history mode using a function that accepts the base URL and returns the history mode. If it returns `null` or `undefined`, Nuxt will fallback to the default history.

```ts [router.options.ts]
import type { RouterConfig } from '@nuxt/schema'
import { createMemoryHistory } from 'vue-router'

export default {
  // https://router.vuejs.org/api/interfaces/routeroptions
  history: base => import.meta.client ? createMemoryHistory(base) : null, /* default */
} satisfies RouterConfig
```

---

# Source: https://nuxt.com/raw/docs/3.x/guide/recipes/custom-usefetch.md

# Source: https://nuxt.com/raw/docs/4.x/guide/recipes/custom-usefetch.md

# Custom useFetch in Nuxt

> How to create a custom fetcher for calling your external API in Nuxt.

When working with Nuxt, you might be making the frontend and fetching an external API, and you might want to set some default options for fetching from your API.

The [`$fetch`](/docs/4.x/api/utils/dollarfetch) utility function (used by the [`useFetch`](/docs/4.x/api/composables/use-fetch) composable) is intentionally not globally configurable. This is important so that fetching behavior throughout your application remains consistent, and other integrations (like modules) can rely on the behavior of core utilities like `$fetch`.

However, Nuxt provides a way to create a custom fetcher for your API (or multiple fetchers if you have multiple APIs to call).

## Custom `$fetch`

Let's create a custom `$fetch` instance with a [Nuxt plugin](/docs/4.x/directory-structure/app/plugins).

<note>

`$fetch` is a configured instance of [ofetch](https://github.com/unjs/ofetch) which supports adding the base URL of your Nuxt server as well as direct function calls during SSR (avoiding HTTP roundtrips).

</note>

Let's pretend here that:

- The main API is [https://api.nuxt.com](https://api.nuxt.com)
- We are storing the JWT token in a session with [nuxt-auth-utils](https://github.com/atinux/nuxt-auth-utils)
- If the API responds with a `401` status code, we redirect the user to the `/login` page

```ts [app/plugins/api.ts]
export default defineNuxtPlugin((nuxtApp) => {
  const { session } = useUserSession()

  const api = $fetch.create({
    baseURL: 'https://api.nuxt.com',
    onRequest ({ request, options, error }) {
      if (session.value?.token) {
        // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
        options.headers.set('Authorization', `Bearer ${session.value?.token}`)
      }
    },
    async onResponseError ({ response }) {
      if (response.status === 401) {
        await nuxtApp.runWithContext(() => navigateTo('/login'))
      }
    },
  })

  // Expose to useNuxtApp().$api
  return {
    provide: {
      api,
    },
  }
})
```

With this Nuxt plugin, `$api` is exposed from `useNuxtApp()` to make API calls directly from the Vue components:

```vue [app/app.vue]
<script setup>
const { $api } = useNuxtApp()
const { data: modules } = await useAsyncData('modules', () => $api('/modules'))
</script>
```

<callout>

Wrapping with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) **avoid double data fetching when doing server-side rendering** (server & client on hydration).

</callout>

## Custom `useFetch`/`useAsyncData`

Now that `$api` has the logic we want, let's create a `useAPI` composable to replace the usage of `useAsyncData` + `$api`:

```ts [app/composables/useAPI.ts]
import type { UseFetchOptions } from 'nuxt/app'

export function useAPI<T> (
  url: string | (() => string),
  options?: UseFetchOptions<T>,
) {
  return useFetch(url, {
    ...options,
    $fetch: useNuxtApp().$api as typeof $fetch,
  })
}
```

Let's use the new composable and have a nice and clean component:

```vue [app/app.vue]
<script setup>
const { data: modules } = await useAPI('/modules')
</script>
```

If you want to customize the type of any error returned, you can also do so:

```ts
import type { FetchError } from 'ofetch'
import type { UseFetchOptions } from 'nuxt/app'

interface CustomError {
  message: string
  status: number
}

export function useAPI<T> (
  url: string | (() => string),
  options?: UseFetchOptions<T>,
) {
  return useFetch<T, FetchError<CustomError>>(url, {
    ...options,
    $fetch: useNuxtApp().$api,
  })
}
```

<note>

This example demonstrates how to use a custom `useFetch`, but the same structure is identical for a custom `useAsyncData`.

</note>

<link-example to="/docs/4.x/examples/advanced/use-custom-fetch-composable">



</link-example>

<video-accordion title="Watch a video about custom $fetch and Repository Pattern in Nuxt" video-id="jXH8Tr-exhI">



</video-accordion>

<note>

We are currently discussing to find a cleaner way to let you create a custom fetcher, see [https://github.com/nuxt/nuxt/issues/14736](https://github.com/nuxt/nuxt/issues/14736).

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/features/data-fetching.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/data-fetching.md

# Source: https://nuxt.com/raw/docs/4.x/examples/features/data-fetching.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/data-fetching.md

# Data Fetching

> Nuxt provides composables to handle data fetching within your application.

Nuxt comes with two composables and a built-in library to perform data-fetching in browser or server environments: `useFetch`, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and `$fetch`.

In a nutshell:

- [`$fetch`](/docs/4.x/api/utils/dollarfetch) is the simplest way to make a network request.
- [`useFetch`](/docs/4.x/api/composables/use-fetch) is a wrapper around `$fetch` that fetches data only once in [universal rendering](/docs/4.x/guide/concepts/rendering#universal-rendering).
- [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is similar to `useFetch` but offers more fine-grained control.

Both `useFetch` and `useAsyncData` share a common set of options and patterns that we will detail in the last sections.

## The need for `useFetch` and `useAsyncData`

Nuxt is a framework which can run isomorphic (or universal) code in both server and client environments. If the [`$fetch` function](/docs/4.x/api/utils/dollarfetch) is used to perform data fetching in the setup function of a Vue component, this may cause data to be fetched twice, once on the server (to render the HTML) and once again on the client (when the HTML is hydrated). This can cause hydration issues, increase the time to interactivity and cause unpredictable behavior.

The [`useFetch`](/docs/4.x/api/composables/use-fetch) and [`useAsyncData`](/docs/4.x/api/composables/use-async-data) composables solve this problem by ensuring that if an API call is made on the server, the data is forwarded to the client in the payload.

The payload is a JavaScript object accessible through [`useNuxtApp().payload`](/docs/4.x/api/composables/use-nuxt-app#payload). It is used on the client to avoid refetching the same data when the code is executed in the browser [during hydration](/docs/4.x/guide/concepts/rendering#universal-rendering).

<tip>

Use the [Nuxt DevTools](https://devtools.nuxt.com) to inspect this data in the **Payload tab**.

</tip>

```vue [app/app.vue]
<script setup lang="ts">
const { data } = await useFetch('/api/data')

async function handleFormSubmit () {
  const res = await $fetch('/api/submit', {
    method: 'POST',
    body: {
      // My form data
    },
  })
}
</script>

<template>
  <div v-if="data == undefined">
    No data
  </div>
  <div v-else>
    <form @submit="handleFormSubmit">
      <!-- form input tags -->
    </form>
  </div>
</template>
```

In the example above, `useFetch` would make sure that the request would occur in the server and is properly forwarded to the browser. `$fetch` has no such mechanism and is a better option to use when the request is solely made from the browser.

### Suspense

Nuxt uses Vue's [`<Suspense>`](https://vuejs.org/guide/built-ins/suspense) component under the hood to prevent navigation before every async data is available to the view. The data fetching composables can help you leverage this feature and use what suits best on a per-call basis.

<note>

You can add the [`<NuxtLoadingIndicator>`](/docs/4.x/api/components/nuxt-loading-indicator) to add a progress bar between page navigations.

</note>

## `$fetch`

Nuxt includes the [ofetch](https://github.com/unjs/ofetch) library, and is auto-imported as the `$fetch` alias globally across your application.

```vue [pages/todos.vue]twoslash
<script setup lang="ts">
async function addTodo () {
  const todo = await $fetch('/api/todos', {
    method: 'POST',
    body: {
      // My todo data
    },
  })
}
</script>
```

<warning>

Beware that using only `$fetch` will not provide [network calls de-duplication and navigation prevention](/docs/4.x/getting-started/data-fetching#the-need-for-usefetch-and-useasyncdata). <br />


It is recommended to use `$fetch` for client-side interactions (event-based) or combined with [`useAsyncData`](/docs/4.x/getting-started/data-fetching#useasyncdata) when fetching the initial component data.

</warning>

<read-more to="/docs/4.x/api/utils/dollarfetch">

Read more about `$fetch`.

</read-more>

### Pass Client Headers to the API

When calling `useFetch` on the server, Nuxt will use [`useRequestFetch`](/docs/4.x/api/composables/use-request-fetch) to proxy client headers and cookies (with the exception of headers not meant to be forwarded, like `host`).

```vue
<script setup lang="ts">
const { data } = await useFetch('/api/echo')
</script>
```

```ts
// /api/echo.ts
export default defineEventHandler(event => parseCookies(event))
```

Alternatively, the example below shows how to use [`useRequestHeaders`](/docs/4.x/api/composables/use-request-headers) to access and send cookies to the API from a server-side request (originating on the client). Using an isomorphic `$fetch` call, we ensure that the API endpoint has access to the same `cookie` header originally sent by the user's browser. This is only necessary if you aren't using `useFetch`.

```vue
<script setup lang="ts">
const headers = useRequestHeaders(['cookie'])

async function getCurrentUser () {
  return await $fetch('/api/me', { headers })
}
</script>
```

<tip>

You can also use [`useRequestFetch`](/docs/4.x/api/composables/use-request-fetch) to proxy headers to the call automatically.

</tip>

<caution>

Be very careful before proxying headers to an external API and just include headers that you need. Not all headers are safe to be bypassed and might introduce unwanted behavior. Here is a list of common headers that are NOT to be proxied:

- `host`, `accept`
- `content-length`, `content-md5`, `content-type`
- `x-forwarded-host`, `x-forwarded-port`, `x-forwarded-proto`
- `cf-connecting-ip`, `cf-ray`

</caution>

## `useFetch`

The [`useFetch`](/docs/4.x/api/composables/use-fetch) composable uses `$fetch` under-the-hood to make SSR-safe network calls in the setup function.

```vue [app/app.vue]twoslash
<script setup lang="ts">
const { data: count } = await useFetch('/api/count')
</script>

<template>
  <p>Page visits: {{ count }}</p>
</template>
```

This composable is a wrapper around the [`useAsyncData`](/docs/4.x/api/composables/use-async-data) composable and `$fetch` utility.

<video-accordion title="Watch a video from Alexander Lichter to avoid using useFetch the wrong way" video-id="njsGVmcWviY">



</video-accordion>

<read-more to="/docs/4.x/api/composables/use-fetch">



</read-more>

<link-example to="/docs/4.x/examples/features/data-fetching">



</link-example>

## `useAsyncData`

The `useAsyncData` composable is responsible for wrapping async logic and returning the result once it is resolved.

<tip>

`useFetch(url)` is nearly equivalent to `useAsyncData(url, () => event.$fetch(url))`. <br />


It's developer experience sugar for the most common use case. (You can find out more about `event.fetch` at [`useRequestFetch`](/docs/4.x/api/composables/use-request-fetch).)

</tip>

<video-accordion title="Watch a video from Alexander Lichter to dig deeper into the difference between useFetch and useAsyncData" video-id="0X-aOpSGabA">



</video-accordion>

There are some cases when using the [`useFetch`](/docs/4.x/api/composables/use-fetch) composable is not appropriate, for example when a CMS or a third-party provide their own query layer. In this case, you can use [`useAsyncData`](/docs/4.x/api/composables/use-async-data) to wrap your calls and still keep the benefits provided by the composable.

```vue [app/pages/users.vue]
<script setup lang="ts">
const { data, error } = await useAsyncData('users', () => myGetFunction('users'))

// This is also possible:
const { data, error } = await useAsyncData(() => myGetFunction('users'))
</script>
```

<note>

The first argument of [`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a unique key used to cache the response of the second argument, the querying function. This key can be ignored by directly passing the querying function, the key will be auto-generated.
<br />

 <br />


Since the autogenerated key only takes into account the file and line where `useAsyncData` is invoked, it is recommended to always create your own key to avoid unwanted behavior, like when you are creating your own custom composable wrapping `useAsyncData`.
<br />

 <br />


Setting a key can be useful to share the same data between components using [`useNuxtData`](/docs/4.x/api/composables/use-nuxt-data) or to [refresh specific data](/docs/4.x/api/utils/refresh-nuxt-data#refresh-specific-data).

</note>

```vue [app/pages/users/[id].vue]
<script setup lang="ts">
const { id } = useRoute().params

const { data, error } = await useAsyncData(`user:${id}`, () => {
  return myGetFunction('users', { id })
})
</script>
```

The `useAsyncData` composable is a great way to wrap and wait for multiple `$fetch` requests to be completed, and then process the results.

```vue
<script setup lang="ts">
const { data: discounts, status } = await useAsyncData('cart-discount', async (_nuxtApp, { signal }) => {
  const [coupons, offers] = await Promise.all([
    $fetch('/cart/coupons', { signal }),
    $fetch('/cart/offers', { signal }),
  ])

  return { coupons, offers }
})
// discounts.value.coupons
// discounts.value.offers
</script>
```

<note>

`useAsyncData` is for fetching and caching data, not triggering side effects like calling Pinia actions, as this can cause unintended behavior such as repeated executions with nullish values. If you need to trigger side effects, use the [`callOnce`](/docs/4.x/api/utils/call-once) utility to do so.

```vue
<script setup lang="ts">
const offersStore = useOffersStore()

// you can't do this
await useAsyncData(() => offersStore.getOffer(route.params.slug))
</script>
```

</note>

<read-more to="/docs/4.x/api/composables/use-async-data">

Read more about `useAsyncData`.

</read-more>

## Return Values

`useFetch` and `useAsyncData` have the same return values listed below.

- `data`: the result of the asynchronous function that is passed in.
- `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function.
- `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.
- `error`: an error object if the data fetching failed.
- `status`: a string indicating the status of the data request (`"idle"`, `"pending"`, `"success"`, `"error"`).

<note>

`data`, `error` and `status` are Vue refs accessible with `.value` in `<script setup>`

</note>

By default, Nuxt waits until a `refresh` is finished before it can be executed again.

<note>

If you have not fetched data on the server (for example, with `server: false`), then the data *will not* be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.

</note>

## Options

[`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch) return the same object type and accept a common set of options as their last argument. They can help you control the composables behavior, such as navigation blocking, caching or execution.

### Lazy

By default, data fetching composables will wait for the resolution of their asynchronous function before navigating to a new page by using Vue's Suspense. This feature can be ignored on client-side navigation with the `lazy` option. In that case, you will have to manually handle loading state using the `status` value.

```vue [app/app.vue]twoslash
<script setup lang="ts">
const { status, data: posts } = useFetch('/api/posts', {
  lazy: true,
})
</script>

<template>
  <!-- you will need to handle a loading state -->
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>
```

You can alternatively use [`useLazyFetch`](/docs/4.x/api/composables/use-lazy-fetch) and `useLazyAsyncData` as convenient methods to perform the same.

```vuetwoslash
<script setup lang="ts">
const { status, data: posts } = useLazyFetch('/api/posts')
</script>
```

<read-more to="/docs/4.x/api/composables/use-lazy-fetch">

Read more about `useLazyFetch`.

</read-more>

<read-more to="/docs/4.x/api/composables/use-lazy-async-data">

Read more about `useLazyAsyncData`.

</read-more>

<video-accordion title="Watch a video from Vue School on blocking vs. non-blocking (lazy) requests" video-id="1022000555" platform="vimeo">



</video-accordion>

### Client-only fetching

By default, data fetching composables will perform their asynchronous function on both client and server environments. Set the `server` option to `false` to only perform the call on the client-side. On initial load, the data will not be fetched before hydration is complete so you have to handle a pending state, though on subsequent client-side navigation the data will be awaited before loading the page.

Combined with the `lazy` option, this can be useful for data that is not needed on the first render (for example, non-SEO sensitive data).

```tstwoslash
/* This call is performed before hydration */
const articles = await useFetch('/api/article')

/* This call will only be performed on the client */
const { status, data: comments } = useFetch('/api/comments', {
  lazy: true,
  server: false,
})
```

The `useFetch` composable is meant to be invoked in setup method or called directly at the top level of a function in lifecycle hooks, otherwise you should use [`$fetch` method](/docs/4.x/getting-started/data-fetching#fetch).

### Minimize payload size

The `pick` option helps you to minimize the payload size stored in your HTML document by only selecting the fields that you want returned from the composables.

```vue
<script setup lang="ts">
/* only pick the fields used in your template */
const { data: mountain } = await useFetch('/api/mountains/everest', {
  pick: ['title', 'description'],
})
</script>

<template>
  <h1>{{ mountain.title }}</h1>
  <p>{{ mountain.description }}</p>
</template>
```

If you need more control or map over several objects, you can use the `transform` function to alter the result of the query.

```ts
const { data: mountains } = await useFetch('/api/mountains', {
  transform: (mountains) => {
    return mountains.map(mountain => ({ title: mountain.title, description: mountain.description }))
  },
})
```

<note>

Both `pick` and `transform` don't prevent the unwanted data from being fetched initially. But they will prevent unwanted data from being added to the payload transferred from server to client.

</note>

<video-accordion title="Watch a video from Vue School on minimizing payload size" video-id="1026410430" platform="vimeo">



</video-accordion>

### Caching and refetching

#### Keys

[`useFetch`](/docs/4.x/api/composables/use-fetch) and [`useAsyncData`](/docs/4.x/api/composables/use-async-data) use keys to prevent refetching the same data.

- [`useFetch`](/docs/4.x/api/composables/use-fetch) uses the provided URL as a key. Alternatively, a `key` value can be provided in the `options` object passed as a last argument.
- [`useAsyncData`](/docs/4.x/api/composables/use-async-data) uses its first argument as a key if it is a string. If the first argument is the handler function that performs the query, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.

<tip>

To get the cached data by key, you can use [`useNuxtData`](/docs/4.x/api/composables/use-nuxt-data)

</tip>

<video-accordion title="Watch a video from Vue School on caching data with the key option" video-id="1026410044" platform="vimeo">



</video-accordion>

#### Shared State and Option Consistency

When multiple components use the same key with `useAsyncData` or `useFetch`, they will share the same `data`, `error` and `status` refs. This ensures consistency across components but requires some options to be consistent.

The following options **must be consistent** across all calls with the same key:

- `handler` function
- `deep` option
- `transform` function
- `pick` array
- `getCachedData` function
- `default` value

```ts
// ❌ This will trigger a development warning
const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })
```

The following options **can safely differ** without triggering warnings:

- `server`
- `lazy`
- `immediate`
- `dedupe`
- `watch`

```ts
// ✅ This is allowed
const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
```

If you need independent instances, use different keys:

```ts
// These are completely independent instances
const { data: users1 } = useAsyncData('users-1', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }))
const { data: users2 } = useAsyncData('users-2', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }))
```

#### Reactive Keys

You can use computed refs, plain refs or getter functions as keys, allowing for dynamic data fetching that automatically updates when dependencies change:

```ts
// Using a computed property as a key
const userId = ref('123')
const { data: user } = useAsyncData(
  computed(() => `user-${userId.value}`),
  () => fetchUser(userId.value),
)

// When userId changes, the data will be automatically refetched
// and the old data will be cleaned up if no other components use it
userId.value = '456'
```

#### Refresh and execute

If you want to fetch or refresh data manually, use the `execute` or `refresh` function provided by the composables.

```vuetwoslash
<script setup lang="ts">
const { data, error, execute, refresh } = await useFetch('/api/users')
</script>

<template>
  <div>
    <p>{{ data }}</p>
    <button @click="() => refresh()">
      Refresh data
    </button>
  </div>
</template>
```

The `execute` function is an alias for `refresh` that works in exactly the same way but is more semantic for cases when the fetch is [not immediate](/docs/4.x/getting-started/data-fetching#not-immediate).

<tip>

To globally refetch or invalidate cached data, see [`clearNuxtData`](/docs/4.x/api/utils/clear-nuxt-data) and [`refreshNuxtData`](/docs/4.x/api/utils/refresh-nuxt-data).

</tip>

#### Clear

If you want to clear the data provided, for whatever reason, without needing to know the specific key to pass to `clearNuxtData`, you can use the `clear` function provided by the composables.

```vuetwoslash
<script setup lang="ts">
const { data, clear } = await useFetch('/api/users')

const route = useRoute()
watch(() => route.path, (path) => {
  if (path === '/') {
    clear()
  }
})
</script>
```

#### Watch

To re-run your fetching function each time other reactive values in your application change, use the `watch` option. You can use it for one or multiple *watchable* elements.

```vuetwoslash
<script setup lang="ts">
const id = ref(1)

const { data, error, refresh } = await useFetch('/api/users', {
  /* Changing the id will trigger a refetch */
  watch: [id],
})
</script>
```

Note that **watching a reactive value won't change the URL fetched**. For example, this will keep fetching the same initial ID of the user because the URL is constructed at the moment the function is invoked.

```vue
<script setup lang="ts">
const id = ref(1)

const { data, error, refresh } = await useFetch(`/api/users/${id.value}`, {
  watch: [id],
})
</script>
```

If you need to change the URL based on a reactive value, you may want to use a [computed URL](/docs/4.x/getting-started/data-fetching#computed-url) instead.

When reactive fetch options are provided, they'll be automatically watched and trigger refetches. In some cases, it can be useful to opt-out of this behavior by specifying `watch: false`.

```ts
const id = ref(1)

// Won't automatically refetch when id changes
const { data, execute } = await useFetch('/api/users', {
  query: { id }, // id is watched by default
  watch: false, // disables automatic watching of id
})

// doesn't trigger refetch
id.value = 2
```

#### Computed URL

Sometimes you may need to compute a URL from reactive values, and refresh the data each time these change. Instead of juggling your way around, you can attach each param as a reactive value. Nuxt will automatically use the reactive value and re-fetch each time it changes.

```vue
<script setup lang="ts">
const id = ref(null)

const { data, status } = useLazyFetch('/api/user', {
  query: {
    user_id: id,
  },
})
</script>
```

In the case of more complex URL construction, you may use a callback as a [computed getter](https://vuejs.org/guide/essentials/computed) that returns the URL string.

Every time a dependency changes, the data will be fetched using the newly constructed URL. Combine this with [not-immediate](/docs/4.x/getting-started/data-fetching#not-immediate), and you can wait until the reactive element changes before fetching.

```vue
<script setup lang="ts">
const id = ref(null)

const { data, status } = useLazyFetch(() => `/api/users/${id.value}`, {
  immediate: false,
})

const pending = computed(() => status.value === 'pending')
</script>

<template>
  <div>
    <!-- disable the input while fetching -->
    <input
      v-model="id"
      type="number"
      :disabled="pending"
    >

    <div v-if="status === 'idle'">
      Type an user ID
    </div>

    <div v-else-if="pending">
      Loading ...
    </div>

    <div v-else>
      {{ data }}
    </div>
  </div>
</template>
```

If you need to force a refresh when other reactive values change, you can also [watch other values](/docs/4.x/getting-started/data-fetching#watch).

### Not immediate

The `useFetch` composable will start fetching data the moment is invoked. You may prevent this by setting `immediate: false`, for example, to wait for user interaction.

With that, you will need both the `status` to handle the fetch lifecycle, and `execute` to start the data fetch.

```vue
<script setup lang="ts">
const { data, error, execute, status } = await useLazyFetch('/api/comments', {
  immediate: false,
})
</script>

<template>
  <div v-if="status === 'idle'">
    <button @click="execute">
      Get data
    </button>
  </div>

  <div v-else-if="status === 'pending'">
    Loading comments...
  </div>

  <div v-else>
    {{ data }}
  </div>
</template>
```

For finer control, the `status` variable can be:

- `idle` when the fetch hasn't started
- `pending` when a fetch has started but not yet completed
- `error` when the fetch fails
- `success` when the fetch is completed successfully

## Passing Headers and Cookies

When we call `$fetch` in the browser, user headers like `cookie` will be directly sent to the API.

Normally, during server-side-rendering, due to security considerations, the `$fetch` wouldn't include the user's browser cookies, nor pass on cookies from the fetch response.

However, when calling `useFetch` with a relative URL on the server, Nuxt will use [`useRequestFetch`](/docs/4.x/api/composables/use-request-fetch) to proxy headers and cookies (with the exception of headers not meant to be forwarded, like `host`).

### Pass Cookies From Server-side API Calls on SSR Response

If you want to pass on/proxy cookies in the other direction, from an internal request back to the client, you will need to handle this yourself.

```ts [app/composables/fetch.ts]
import { appendResponseHeader } from 'h3'
import type { H3Event } from 'h3'

export const fetchWithCookie = async (event: H3Event, url: string) => {
  /* Get the response from the server endpoint */
  const res = await $fetch.raw(url)
  /* Get the cookies from the response */
  const cookies = res.headers.getSetCookie()
  /* Attach each cookie to our incoming Request */
  for (const cookie of cookies) {
    appendResponseHeader(event, 'set-cookie', cookie)
  }
  /* Return the data of the response */
  return res._data
}
```

```vue
<script setup lang="ts">
// This composable will automatically pass cookies to the client
const event = useRequestEvent()

const { data: result } = await useAsyncData(() => fetchWithCookie(event!, '/api/with-cookie'))

onMounted(() => console.log(document.cookie))
</script>
```

## Options API Support

Nuxt provides a way to perform `asyncData` fetching within the Options API. You must wrap your component definition within `defineNuxtComponent` for this to work.

```vue
<script>
export default defineNuxtComponent({
  /* Use the fetchKey option to provide a unique key */
  fetchKey: 'hello',
  async asyncData () {
    return {
      hello: await $fetch('/api/hello'),
    }
  },
})
</script>
```

<note>

Using `<script setup>` or `<script setup lang="ts">` are the recommended way of declaring Vue components in Nuxt.

</note>

<read-more to="/docs/4.x/api/utils/define-nuxt-component">



</read-more>

## Serializing Data From Server to Client

When using `useAsyncData` and `useLazyAsyncData` to transfer data fetched on server to the client (as well as anything else that utilizes [the Nuxt payload](/docs/4.x/api/composables/use-nuxt-app#payload)), the payload is serialized with [`devalue`](https://github.com/sveltejs/devalue). This allows us to transfer not just basic JSON but also to serialize and revive/deserialize more advanced kinds of data, such as regular expressions, Dates, Map and Set, `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError` - and more.

It is also possible to define your own serializer/deserializer for types that are not supported by Nuxt. You can read more in the [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#payload) docs.

<note>

Note that this *does not apply* to data passed from your server routes when fetched with `$fetch` or `useFetch` - see the next section for more information.

</note>

## Serializing Data From API Routes

When fetching data from the `server` directory, the response is serialized using `JSON.stringify`. However, since serialization is limited to only JavaScript primitive types, Nuxt does its best to convert the return type of `$fetch` and [`useFetch`](/docs/4.x/api/composables/use-fetch) to match the actual value.

<read-more to="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description" icon="i-simple-icons-mdnwebdocs" target="_blank">

Learn more about `JSON.stringify` limitations.

</read-more>

### Example

```ts [server/api/foo.ts]
export default defineEventHandler(() => {
  return new Date()
})
```

```vue [app/app.vue]
<script setup lang="ts">
// Type of `data` is inferred as string even though we returned a Date object
const { data } = await useFetch('/api/foo')
</script>
```

### Custom serializer function

To customize the serialization behavior, you can define a `toJSON` function on your returned object. If you define a `toJSON` method, Nuxt will respect the return type of the function and will not try to convert the types.

```ts [server/api/bar.ts]
export default defineEventHandler(() => {
  const data = {
    createdAt: new Date(),

    toJSON () {
      return {
        createdAt: {
          year: this.createdAt.getFullYear(),
          month: this.createdAt.getMonth(),
          day: this.createdAt.getDate(),
        },
      }
    },
  }
  return data
})
```

```vue [app/app.vue]
<script setup lang="ts">
// Type of `data` is inferred as
// {
//   createdAt: {
//     year: number
//     month: number
//     day: number
//   }
// }
const { data } = await useFetch('/api/bar')
</script>
```

### Using an alternative serializer

Nuxt does not currently support an alternative serializer to `JSON.stringify`. However, you can return your payload as a normal string and utilize the `toJSON` method to maintain type safety.

In the example below, we use [superjson](https://github.com/flightcontrolhq/superjson) as our serializer.

```ts [server/api/superjson.ts]
import superjson from 'superjson'

export default defineEventHandler(() => {
  const data = {
    createdAt: new Date(),

    // Workaround the type conversion
    toJSON () {
      return this
    },
  }

  // Serialize the output to string, using superjson
  return superjson.stringify(data) as unknown as typeof data
})
```

```vue [app/app.vue]
<script setup lang="ts">
import superjson from 'superjson'

// `date` is inferred as { createdAt: Date } and you can safely use the Date object methods
const { data } = await useFetch('/api/superjson', {
  transform: (value) => {
    return superjson.parse(value as unknown as string)
  },
})
</script>
```

## Recipes

### Consuming SSE (Server-Sent Events) via POST request

<tip>

If you're consuming SSE via GET request, you can use [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) or VueUse composable [`useEventSource`](https://vueuse.org/core/useeventsource/).

</tip>

When consuming SSE via POST request, you need to handle the connection manually. Here's how you can do it:

```ts
// Make a POST request to the SSE endpoint
const response = await $fetch<ReadableStream>('/chats/ask-ai', {
  method: 'POST',
  body: {
    query: 'Hello AI, how are you?',
  },
  responseType: 'stream',
})

// Create a new ReadableStream from the response with TextDecoderStream to get the data as text
const reader = response.pipeThrough(new TextDecoderStream()).getReader()

// Read the chunk of data as we get it
while (true) {
  const { value, done } = await reader.read()

  if (done) { break }

  console.log('Received:', value)
}
```

### Making parallel requests

When requests don't rely on each other, you can make them in parallel with `Promise.all()` to boost performance.

```ts
const { data } = await useAsyncData((_nuxtApp, { signal }) => {
  return Promise.all([
    $fetch('/api/comments/', { signal }),
    $fetch('/api/author/12', { signal }),
  ])
})

const comments = computed(() => data.value?.[0])
const author = computed(() => data.value?.[1])
```

<video-accordion title="Watch a video from Vue School on parallel data fetching" video-id="1024262536" platform="vimeo">



</video-accordion>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/debugging.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/debugging.md

# Debugging

> In Nuxt, you can get started with debugging your application directly in the browser as well as in your IDE.

## Sourcemaps

Sourcemaps are enabled for your server build by default, and for the client build in dev mode, but you can enable them more specifically in your configuration.

```ts
export default defineNuxtConfig({
  // or sourcemap: true
  sourcemap: {
    server: true,
    client: true,
  },
})
```

## Debugging with Node Inspector

You can use [Node inspector](https://nodejs.org/en/learn/getting-started/debugging) to debug Nuxt server-side.

```bash
nuxt dev --inspect
```

This will start Nuxt in `dev` mode with debugger active. If everything is working correctly a Node.js icon will appear on your Chrome DevTools and you can attach to the debugger.

<important>

Note that the Node.js and Chrome processes need to be run on the same platform. This doesn't work inside of Docker.

</important>

## Debugging in Your IDE

It is possible to debug your Nuxt app in your IDE while you are developing it.

### Example VS Code Debug Configuration

You may need to update the config below with a path to your web browser. For more information, visit the [VS Code documentation about debug configuration](https://code.visualstudio.com/docs/debugtest/debugging#_launch-configurations).

```json5
{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "client: chrome",
      "url": "http://localhost:3000",
      // this should point to your Nuxt `srcDir`, which is `app` by default
      "webRoot": "${workspaceFolder}/app"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "server: nuxt",
      "outputCapture": "std",
      "program": "${workspaceFolder}/node_modules/nuxt/bin/nuxt.mjs",
      "args": [
        "dev"
      ],
    }
  ],
  "compounds": [
    {
      "name": "fullstack: nuxt",
      "configurations": [
        "server: nuxt",
        "client: chrome"
      ]
    }
  ]
}
```

If you prefer your usual browser extensions, add this to the *chrome* configuration above:

```json5
"userDataDir": false,
```

### Example JetBrains IDEs Debug Configuration

You can also debug your Nuxt app in JetBrains IDEs such as IntelliJ IDEA, WebStorm, or PhpStorm.

1. Create a new file in your project root directory and name it `nuxt.run.xml`.
2. Open the `nuxt.run.xml` file and paste the following debug configuration:

```html
<component name="ProjectRunConfigurationManager">
  <configuration default="false" name="client: chrome" type="JavascriptDebugType" uri="http://localhost:3000" useFirstLineBreakpoints="true">
    <method v="2" />
  </configuration>

  <configuration default="false" name="server: nuxt" type="NodeJSConfigurationType" application-parameters="dev" path-to-js-file="$PROJECT_DIR$/node_modules/nuxt/bin/nuxt.mjs" working-dir="$PROJECT_DIR$">
    <method v="2" />
  </configuration>

  <configuration default="false" name="fullstack: nuxt" type="CompoundRunConfigurationType">
    <toRun name="client: chrome" type="JavascriptDebugType" />
    <toRun name="server: nuxt" type="NodeJSConfigurationType" />
    <method v="2" />
  </configuration>
</component>
```

### Other IDEs

If you have another IDE and would like to contribute sample configuration, feel free to [open a PR](https://github.com/nuxt/nuxt/edit/main/docs/2.guide/3.going-further/9.debugging.md)!

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/define-lazy-hydration-component.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/define-lazy-hydration-component.md

# defineLazyHydrationComponent

> Define a lazy hydration component with a specific strategy.

`defineLazyHydrationComponent` is a compiler macro that helps you create a component with a specific lazy hydration strategy. Lazy hydration defers hydration until components become visible or until the browser has completed more critical tasks. This can significantly reduce the initial performance cost, especially for non-essential components.

## Usage

### Visibility Strategy

Hydrates the component when it becomes visible in the viewport.

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./components/MyComponent.vue'),
)
</script>

<template>
  <div>
    <!--
      Hydration will be triggered when
      the element(s) is 100px away from entering the viewport.
    -->
    <LazyHydrationMyComponent :hydrate-on-visible="{ rootMargin: '100px' }" />
  </div>
</template>
```

The `hydrateOnVisible` prop is optional. You can pass an object to customize the behavior of the `IntersectionObserver` under the hood.

<read-more title="IntersectionObserver options" to="https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver">

Read more about the options for `hydrate-on-visible`.

</read-more>

<note>

Under the hood, this uses Vue's built-in [`hydrateOnVisible` strategy](https://vuejs.org/guide/components/async#hydrate-on-visible).

</note>

### Idle Strategy

Hydrates the component when the browser is idle. This is suitable if you need the component to load as soon as possible, but not block the critical rendering path.

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'idle',
  () => import('./components/MyComponent.vue'),
)
</script>

<template>
  <div>
    <!-- Hydration will be triggered when the browser is idle or after 2000ms. -->
    <LazyHydrationMyComponent :hydrate-on-idle="2000" />
  </div>
</template>
```

The `hydrateOnIdle` prop is optional. You can pass a positive number to specify the maximum timeout.

Idle strategy is for components that can be hydrated when the browser is idle.

<note>

Under the hood, this uses Vue's built-in [`hydrateOnIdle` strategy](https://vuejs.org/guide/components/async#hydrate-on-idle).

</note>

### Interaction Strategy

Hydrates the component after a specified interaction (e.g., click, mouseover).

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'interaction',
  () => import('./components/MyComponent.vue'),
)
</script>

<template>
  <div>
    <!--
      Hydration will be triggered when
      the element(s) is hovered over by the pointer.
    -->
    <LazyHydrationMyComponent hydrate-on-interaction="mouseover" />
  </div>
</template>
```

The `hydrateOnInteraction` prop is optional. If you do not pass an event or a list of events, it defaults to hydrating on `pointerenter`, `click`, and `focus`.

<note>

Under the hood, this uses Vue's built-in [`hydrateOnInteraction` strategy](https://vuejs.org/guide/components/async#hydrate-on-interaction).

</note>

### Media Query Strategy

Hydrates the component when the window matches a media query.

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'mediaQuery',
  () => import('./components/MyComponent.vue'),
)
</script>

<template>
  <div>
    <!--
      Hydration will be triggered when
      the window width is greater than or equal to 768px.
    -->
    <LazyHydrationMyComponent hydrate-on-media-query="(min-width: 768px)" />
  </div>
</template>
```

<note>

Under the hood, this uses Vue's built-in [`hydrateOnMediaQuery` strategy](https://vuejs.org/guide/components/async#hydrate-on-media-query).

</note>

### Time Strategy

Hydrates the component after a specified delay (in milliseconds).

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'time',
  () => import('./components/MyComponent.vue'),
)
</script>

<template>
  <div>
    <!-- Hydration is triggered after 1000ms. -->
    <LazyHydrationMyComponent :hydrate-after="1000" />
  </div>
</template>
```

Time strategy is for components that can wait a specific amount of time.

### If Strategy

Hydrates the component based on a boolean condition.

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'if',
  () => import('./components/MyComponent.vue'),
)

const isReady = ref(false)

function myFunction () {
  // Trigger custom hydration strategy...
  isReady.value = true
}
</script>

<template>
  <div>
    <!-- Hydration is triggered when isReady becomes true. -->
    <LazyHydrationMyComponent :hydrate-when="isReady" />
  </div>
</template>
```

If strategy is best for components that might not always need to be hydrated.

### Never Hydrate

Never hydrates the component.

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'never',
  () => import('./components/MyComponent.vue'),
)
</script>

<template>
  <div>
    <!-- This component will never be hydrated by Vue. -->
    <LazyHydrationMyComponent />
  </div>
</template>
```

### Listening to Hydration Events

All delayed hydration components emit a `@hydrated` event when they are hydrated.

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./components/MyComponent.vue'),
)

function onHydrate () {
  console.log('Component has been hydrated!')
}
</script>

<template>
  <div>
    <LazyHydrationMyComponent
      :hydrate-on-visible="{ rootMargin: '100px' }"
      @hydrated="onHydrated"
    />
  </div>
</template>
```

## Parameters

<warning>

To ensure that the compiler correctly recognizes this macro, avoid using external variables. The following approach will prevent the macro from being properly recognized:

```vue
<script setup lang="ts">
const strategy = 'visible'
const source = () => import('./components/MyComponent.vue')
const LazyHydrationMyComponent = defineLazyHydrationComponent(strategy, source)
</script>
```

</warning>

### `strategy`

- **Type**: `'visible' | 'idle' | 'interaction' | 'mediaQuery' | 'if' | 'time' | 'never'`
- **Required**: `true`

<table>
<thead>
  <tr>
    <th>
      Strategy
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        visible
      </code>
    </td>
    
    <td>
      Hydrates when the component becomes visible in the viewport.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        idle
      </code>
    </td>
    
    <td>
      Hydrates when the browser is idle or after a delay.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        interaction
      </code>
    </td>
    
    <td>
      Hydrates upon user interaction (e.g., click, hover).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mediaQuery
      </code>
    </td>
    
    <td>
      Hydrates when the specified media query condition is met.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        if
      </code>
    </td>
    
    <td>
      Hydrates when a specified boolean condition is met.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        time
      </code>
    </td>
    
    <td>
      Hydrates after a specified time delay.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        never
      </code>
    </td>
    
    <td>
      Prevents Vue from hydrating the component.
    </td>
  </tr>
</tbody>
</table>

### `source`

- **Type**: `() => Promise<Component>`
- **Required**: `true`

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/define-nuxt-component.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/define-nuxt-component.md

# defineNuxtComponent

> defineNuxtComponent() is a helper function for defining type safe components with Options API.

<note>

`defineNuxtComponent()` is a helper function for defining type safe Vue components using options API similar to [`defineComponent()`](https://vuejs.org/api/general#definecomponent). `defineNuxtComponent()` wrapper also adds support for `asyncData` and `head` component options.

</note>

<note>

Using `<script setup lang="ts">` is the recommended way of declaring Vue components in Nuxt.

</note>

<read-more to="/docs/getting-started/data-fetching">



</read-more>

## `asyncData()`

If you choose not to use `setup()` in your app, you can use the `asyncData()` method within your component definition:

```vue [app/pages/index.vue]
<script lang="ts">
export default defineNuxtComponent({
  asyncData () {
    return {
      data: {
        greetings: 'hello world!',
      },
    }
  },
})
</script>
```

## `head()`

If you choose not to use `setup()` in your app, you can use the `head()` method within your component definition:

```vue [app/pages/index.vue]
<script lang="ts">
export default defineNuxtComponent({
  head (nuxtApp) {
    return {
      title: 'My site',
    }
  },
})
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/define-nuxt-plugin.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/define-nuxt-plugin.md

# defineNuxtPlugin

> defineNuxtPlugin() is a helper function for creating Nuxt plugins.

`defineNuxtPlugin` is a helper function for creating Nuxt plugins with enhanced functionality and type safety. This utility normalizes different plugin formats into a consistent structure that works seamlessly within Nuxt's plugin system.

```ts [plugins/hello.ts]twoslash
export default defineNuxtPlugin((nuxtApp) => {
  // Doing something with nuxtApp
})
```

<read-more to="/docs/4.x/directory-structure/app/plugins#creating-plugins">



</read-more>

## Type

```ts [Signature]
export function defineNuxtPlugin<T extends Record<string, unknown>> (plugin: Plugin<T> | ObjectPlugin<T>): Plugin<T> & ObjectPlugin<T>

type Plugin<T> = (nuxt: NuxtApp) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }

interface ObjectPlugin<T> {
  name?: string
  enforce?: 'pre' | 'default' | 'post'
  dependsOn?: string[]
  order?: number
  parallel?: boolean
  setup?: Plugin<T>
  hooks?: Partial<RuntimeNuxtHooks>
  env?: {
    islands?: boolean
  }
}
```

## Parameters

**plugin**: A plugin can be defined in two ways:

1. **Function Plugin**: A function that receives the [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance and can return a promise with a potential object with a [`provide`](/docs/4.x/directory-structure/app/plugins#providing-helpers) property if you want to provide a helper on [`NuxtApp`](/docs/4.x/guide/going-further/internals#the-nuxtapp-interface) instance.
2. **Object Plugin**: An object that can include various properties to configure the plugin's behavior, such as `name`, `enforce`, `dependsOn`, `order`, `parallel`, `setup`, `hooks`, and `env`.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Optional name for the plugin, useful for debugging and dependency management.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        enforce
      </code>
    </td>
    
    <td>
      <code>
        'pre'
      </code>
      
       | <code>
        'default'
      </code>
      
       | <code>
        'post'
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Controls when the plugin runs relative to other plugins.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dependsOn
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Array of plugin names this plugin depends on. Ensures proper execution order.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        order
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      This allows more granular control over plugin order and should only be used by advanced users. <strong>
        It overrides the value of <code>
          enforce
        </code>
        
         and is used to sort plugins.
      </strong>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parallel
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Whether to execute the plugin in parallel with other parallel plugins.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setup
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Plugin
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          T
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      The main plugin function, equivalent to a function plugin.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hooks
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Partial
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          RuntimeNuxtHooks
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Nuxt app runtime hooks to register directly.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        env
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          {
        </span>
        
        <span class="sZSNi">
          islands
        </span>
        
        <span class="sDfIl">
          ?:
        </span>
        
        <span class="sZSNi">
          boolean
        </span>
        
        <span class="sDfIl">
          }
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Set this value to <code>
        false
      </code>
      
       if you don't want the plugin to run when rendering server-only or island components.
    </td>
  </tr>
</tbody>
</table>

<video-accordion title="Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins" video-id="2aXZyXB1QGQ">



</video-accordion>

## Examples

### Basic Usage

The example below demonstrates a simple plugin that adds global functionality:

```ts [plugins/hello.ts]twoslash
export default defineNuxtPlugin((nuxtApp) => {
  // Add a global method
  return {
    provide: {
      hello: (name: string) => `Hello ${name}!`,
    },
  }
})
```

### Object Syntax Plugin

The example below shows the object syntax with advanced configuration:

```ts [plugins/advanced.ts]twoslash
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre',
  async setup (nuxtApp) {
    // Plugin setup logic
    const data = await $fetch('/api/config')

    return {
      provide: {
        config: data,
      },
    }
  },
  hooks: {
    'app:created' () {
      console.log('App created!')
    },
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/define-nuxt-route-middleware.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/define-nuxt-route-middleware.md

# defineNuxtRouteMiddleware

> Create named route middleware using defineNuxtRouteMiddleware helper function.

Route middleware are stored in the [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) of your Nuxt application (unless [set otherwise](/docs/4.x/api/nuxt-config#middleware)).

## Type

```ts [Signature]
export function defineNuxtRouteMiddleware (middleware: RouteMiddleware): RouteMiddleware

interface RouteMiddleware {
  (to: RouteLocationNormalized, from: RouteLocationNormalized): ReturnType<NavigationGuard>
}
```

## Parameters

### `middleware`

- **Type**: `RouteMiddleware`

A function that takes two Vue Router's route location objects as parameters: the next route `to` as the first, and the current route `from` as the second.

Learn more about available properties of `RouteLocationNormalized` in the **Vue Router docs**.

## Examples

### Showing Error Page

You can use route middleware to throw errors and show helpful error messages:

```ts [app/middleware/error.ts]
export default defineNuxtRouteMiddleware((to) => {
  if (to.params.id === '1') {
    throw createError({ status: 404, statusText: 'Page Not Found' })
  }
})
```

The above route middleware will redirect a user to the custom error page defined in the `~/error.vue` file, and expose the error message and code passed from the middleware.

### Redirection

Use [`useState`](/docs/4.x/api/composables/use-state) in combination with `navigateTo` helper function inside the route middleware to redirect users to different routes based on their authentication status:

```ts [app/middleware/auth.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  const auth = useState('auth')

  if (!auth.value.isAuthenticated) {
    return navigateTo('/login')
  }

  if (to.path !== '/dashboard') {
    return navigateTo('/dashboard')
  }
})
```

Both [navigateTo](/docs/4.x/api/utils/navigate-to) and [abortNavigation](/docs/4.x/api/utils/abort-navigation) are globally available helper functions that you can use inside `defineNuxtRouteMiddleware`.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/define-page-meta.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/define-page-meta.md

# definePageMeta

> Define metadata for your page components.

`definePageMeta` is a compiler macro that you can use to set metadata for your **page** components located in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory (unless [set otherwise](/docs/4.x/api/nuxt-config#pages)). This way you can set custom metadata for each static or dynamic route of your Nuxt application.

```vue [app/pages/some-page.vue]
<script setup lang="ts">
definePageMeta({
  layout: 'default',
})
</script>
```

<read-more to="/docs/4.x/directory-structure/app/pages#page-metadata">



</read-more>

## Type

```ts [Signature]
export function definePageMeta (meta: PageMeta): void

interface PageMeta {
  validate?: ((route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>)
  redirect?: RouteRecordRedirectOption
  name?: string
  path?: string
  props?: RouteRecordRaw['props']
  alias?: string | string[]
  groups?: string[]
  pageTransition?: boolean | TransitionProps
  layoutTransition?: boolean | TransitionProps
  viewTransition?: boolean | 'always'
  key?: false | string | ((route: RouteLocationNormalizedLoaded) => string)
  keepalive?: boolean | KeepAliveProps
  layout?: false | LayoutKey | Ref<LayoutKey> | ComputedRef<LayoutKey>
  middleware?: MiddlewareKey | NavigationGuard | Array<MiddlewareKey | NavigationGuard>
  scrollToTop?: boolean | ((to: RouteLocationNormalizedLoaded, from: RouteLocationNormalizedLoaded) => boolean)
  [key: string]: unknown
}
```

## Parameters

### `meta`

- **Type**: `PageMeta`<br />

An object accepting the following page metadata:<br />

**name**
  - **Type**: `string`<br />
  
  You may define a name for this page's route. By default, name is generated based on path inside the [`app/pages/` directory](/docs/4.x/directory-structure/app/pages).<br />

**path**
  - **Type**: `string`<br />
  
  You may define a [custom regular expression](/docs/4.x/api/utils/define-page-meta#using-a-custom-regular-expression) if you have a more complex pattern than can be expressed with the file name.<br />

**props**
  - **Type**: [`RouteRecordRaw['props']`](https://router.vuejs.org/guide/essentials/passing-props)<br />
  
  Allows accessing the route `params` as props passed to the page component.<br />

**alias**
  - **Type**: `string | string[]`<br />
  
  Aliases for the record. Allows defining extra paths that will behave like a copy of the record. Allows having paths shorthands like `/users/:id` and `/u/:id`. All `alias` and `path` values must share the same params.<br />

**groups**
  - **Type**: `string[]`<br />
  
  Route groups the page belongs to, based on the folder structure. Automatically populated for pages within [route groups](/docs/4.x/guide/directory-structure/app/pages#route-groups).<br />

**keepalive**
  - **Type**: `boolean` | [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)<br />
  
  Set to `true` when you want to preserve page state across route changes or use the [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive) for a fine-grained control.<br />

**key**
  - **Type**: `false` | `string` | `((route: RouteLocationNormalizedLoaded) => string)`<br />
  
  Set `key` value when you need more control over when the `<NuxtPage>` component is re-rendered.<br />

**layout**
  - **Type**: `false` | `LayoutKey` | `Ref<LayoutKey>` | `ComputedRef<LayoutKey>`<br />
  
  Set a static or dynamic name of the layout for each route. This can be set to `false` in case the default layout needs to be disabled.<br />

**layoutTransition**
  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)<br />
  
  Set name of the transition to apply for current layout. You can also set this value to `false` to disable the layout transition.<br />

**middleware**
  - **Type**: `MiddlewareKey` | [`NavigationGuard`](https://router.vuejs.org/api/interfaces/navigationguard) | `Array<MiddlewareKey | NavigationGuard>`<br />
  
  Define anonymous or named middleware directly within `definePageMeta`. Learn more about [route middleware](/docs/4.x/directory-structure/app/middleware).<br />

**pageTransition**
  - **Type**: `boolean` | [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)<br />
  
  Set name of the transition to apply for current page. You can also set this value to `false` to disable the page transition.<br />

**viewTransition**
  - **Type**: `boolean | 'always'`<br />
  
  **Experimental feature, only available when enabled in your nuxt.config file**<br />
  
  
  Enable/disable View Transitions for the current page.
  If set to true, Nuxt will not apply the transition if the users browser matches `prefers-reduced-motion: reduce` (recommended). If set to `always`, Nuxt will always apply the transition.<br />

**redirect**
  - **Type**: [`RouteRecordRedirectOption`](https://router.vuejs.org/guide/essentials/redirect-and-alias)<br />
  
  Where to redirect if the route is directly matched. The redirection happens before any navigation guard and triggers a new navigation with the new target location.<br />

**validate**
  - **Type**: `(route: RouteLocationNormalized) => boolean | Promise<boolean> | Partial<NuxtError> | Promise<Partial<NuxtError>>`<br />
  
  Validate whether a given route can validly be rendered with this page. Return true if it is valid, or false if not. If another match can't be found, this will mean a 404. You can also directly return an object with `status`/`statusText` to respond immediately with an error (other matches will not be checked).<br />

**scrollToTop**
  - **Type**: `boolean | (to: RouteLocationNormalized, from: RouteLocationNormalized) => boolean`<br />
  
  Tell Nuxt to scroll to the top before rendering the page or not. If you want to overwrite the default scroll behavior of Nuxt, you can do so in `~/router.options.ts` (see [custom routing](/docs/4.x/guide/recipes/custom-routing#using-routeroptions)) for more info.<br />

**[key: string]**
  - **Type**: `any`<br />
  
  Apart from the above properties, you can also set **custom** metadata. You may wish to do so in a type-safe way by [augmenting the type of the `meta` object](/docs/4.x/directory-structure/app/pages/#typing-custom-metadata).

## Examples

### Basic Usage

The example below demonstrates:

- how `key` can be a function that returns a value;
- how `keepalive` property makes sure that the `<modal>` component is not cached when switching between multiple components;
- adding `pageType` as a custom property:

```vue [app/pages/some-page.vue]
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,

  keepalive: {
    exclude: ['modal'],
  },

  pageType: 'Checkout',
})
</script>
```

### Defining Middleware

The example below shows how the middleware can be defined using a `function` directly within the `definePageMeta` or set as a `string` that matches the middleware file name located in the `app/middleware/` directory:

```vue [app/pages/some-page.vue]
<script setup lang="ts">
definePageMeta({
  // define middleware as a function
  middleware: [
    function (to, from) {
      const auth = useState('auth')

      if (!auth.value.authenticated) {
        return navigateTo('/login')
      }

      if (to.path !== '/checkout') {
        return navigateTo('/checkout')
      }
    },
  ],

  // ... or a string
  middleware: 'auth',

  // ... or multiple strings
  middleware: ['auth', 'another-named-middleware'],
})
</script>
```

### Using a Custom Regular Expression

A custom regular expression is a good way to resolve conflicts between overlapping routes, for instance:

The two routes "/test-category" and "/1234-post" match both `[postId]-[postSlug].vue` and `[categorySlug].vue` page routes.

To make sure that we are only matching digits (`\d+`) for `postId` in the `[postId]-[postSlug]` route, we can add the following to the `[postId]-[postSlug].vue` page template:

```vue [app/pages/[postId]-[postSlug].vue]
<script setup lang="ts">
definePageMeta({
  path: '/:postId(\\d+)-:postSlug',
})
</script>
```

For more examples see [Vue Router's Matching Syntax](https://router.vuejs.org/guide/essentials/route-matching-syntax).

### Defining Layout

You can define the layout that matches the layout's file name located (by default) in the [`app/layouts/` directory](/docs/4.x/directory-structure/app/layouts). You can also disable the layout by setting the `layout` to `false`:

```vue [app/pages/some-page.vue]
<script setup lang="ts">
definePageMeta({
  // set custom layout
  layout: 'admin',

  // ... or disable a default layout
  layout: false,
})
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/define-route-rules.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/define-route-rules.md

# defineRouteRules

> Define route rules for hybrid rendering at the page level.

<read-more icon="i-lucide-star" to="/docs/4.x/guide/going-further/experimental-features#inlinerouterules">

This feature is experimental and in order to use it you must enable the `experimental.inlineRouteRules` option in your `nuxt.config`.

</read-more>

## Usage

```vue [app/pages/index.vue]
<script setup lang="ts">
defineRouteRules({
  prerender: true,
})
</script>

<template>
  <h1>Hello world!</h1>
</template>
```

Will be translated to:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
  },
})
```

<note>

When running [`nuxt build`](/docs/4.x/api/commands/build), the home page will be pre-rendered in `.output/public/index.html` and statically served.

</note>

## Notes

- A rule defined in `~/pages/foo/bar.vue` will be applied to `/foo/bar` requests.
- A rule in `~/pages/foo/[id].vue` will be applied to `/foo/**` requests.

For more control, such as if you are using a custom `path` or `alias` set in the page's [`definePageMeta`](/docs/4.x/api/utils/define-page-meta), you should set `routeRules` directly within your `nuxt.config`.

<read-more icon="i-lucide-medal" to="/docs/4.x/guide/concepts/rendering#hybrid-rendering">

Read more about the `routeRules`.

</read-more>

---

# Source: https://nuxt.com/raw/deploy/deno-deploy.md

# Deno Deploy

> Deploy your Nuxt Application to Deno Deploy infrastructure.

<important>

Deno deploy preset is experimental.

</important>

## Deploy with the CLI

You can use [deployctl](https://deno.com/deploy/docs/deployctl) to deploy your app.

Login to [Deno Deploy](https://dash.deno.com/account#access-tokens) to obtain a `DENO_DEPLOY_TOKEN` access token, and set it as an environment variable.

```bash
# Build with the deno_deploy preset
npm run build --preset=deno_deploy

# Make sure to run the deployctl command from the output directory
cd .output
deployctl deploy --project=my-project server/index.ts --token=<DENO_DEPLOY_TOKEN>
```

## Deploy within CI/CD using GitHub Actions

Link your GitHub repository to your Deno Deploy project and choose the "GitHub Actions" deployment mode. You can do this in your project settings on [https://dash.deno.com](https://dash.deno.com).

Create a GitHub action file in your repository:

```yaml [.github/workflows/deno_deploy.yml]
name: deno-deploy
on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
jobs:
  deploy:
    steps:
      - uses: actions/checkout@v3
      - run: corepack enable
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: pnpm
      - run: pnpm install
      - run: pnpm build
        env:
          NITRO_PRESET: deno_deploy
      - name: Deploy to Deno Deploy
        uses: denoland/deployctl@v1
        with:
          project: <my-project>
          entrypoint: server/index.ts
          root: .output
```

<important>

Make sure to rename `<my-project>` with your project name.

</important>

## Templates

<card-group>
<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Nuxt Deno KV" to="https://github.com/Atinux/nuxt-deno-kv">

A collaborative todo-list app built with Deno KV and Nuxt.

</card>
</card-group>

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/deno-deploy">

Head over **Nitro documentation** to learn more about the deno-deploy deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/deployment.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/deployment.md

# Deployment

> Learn how to deploy your Nuxt application to any hosting provider.

A Nuxt application can be deployed on a Node.js server, pre-rendered for static hosting, or deployed to serverless or edge (CDN) environments.

<tip>

If you are looking for a list of cloud providers that support Nuxt, see the [Hosting providers](/deploy) section.

</tip>

## Node.js Server

Discover the Node.js server preset with Nitro to deploy on any Node hosting.

- **Default output format** if none is specified or auto-detected <br />
- Loads only the required chunks to render the request for optimal cold start timing <br />
- Useful for deploying Nuxt apps to any Node.js hosting

### Entry Point

When running `nuxt build` with the Node server preset, the result will be an entry point that launches a ready-to-run Node server.

```bash [Terminal]
node .output/server/index.mjs
```

This will launch your production Nuxt server that listens on port 3000 by default.

It respects the following runtime environment variables:

- `NITRO_PORT` or `PORT` (defaults to `3000`)
- `NITRO_HOST` or `HOST` (defaults to `'0.0.0.0'`)
- `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.

### PM2

[PM2](https://pm2.keymetrics.io/) (Process Manager 2) is a fast and easy solution for hosting your Nuxt application on your server or VM.

To use `pm2`, use an `ecosystem.config.cjs`:

```ts [ecosystem.config.cjs]
module.exports = {
  apps: [
    {
      name: 'NuxtAppName',
      port: '3000',
      exec_mode: 'cluster',
      instances: 'max',
      script: './.output/server/index.mjs',
    },
  ],
}
```

### Cluster Mode

You can use `NITRO_PRESET=node_cluster` in order to leverage multi-process performance using Node.js [cluster](https://nodejs.org/dist/latest/docs/api/cluster.html) module.

By default, the workload gets distributed to the workers with the round robin strategy.

### Learn More

<read-more to="https://nitro.build/deploy/runtimes/node" title="the Nitro documentation for node-server preset">



</read-more>

<video-accordion title="Watch Daniel Roe's short video on the topic" video-id="0x1H6K5yOfs">



</video-accordion>

## Static Hosting

There are two ways to deploy a Nuxt application to any static hosting services:

- Static site generation (SSG) with `ssr: true` pre-renders routes of your application at build time. (This is the default behavior when running `nuxt generate`.) It will also generate `/200.html` and `/404.html` single-page app fallback pages, which can render dynamic routes or 404 errors on the client (though you may need to configure this on your static host).
- Alternatively, you can prerender your site with `ssr: false` (static single-page app). This will produce HTML pages with an empty `<div id="__nuxt"></div>` where your Vue app would normally be rendered. You will lose many SEO benefits of prerendering your site, so it is suggested instead to use [`<ClientOnly>`](/docs/4.x/api/components/client-only) to wrap the portions of your site that cannot be server rendered (if any).

<read-more to="/docs/4.x/getting-started/prerendering" title="Nuxt prerendering">



</read-more>

### Client-side Only Rendering

If you don't want to pre-render your routes, another way of using static hosting is to set the `ssr` property to `false` in the `nuxt.config` file. The `nuxt generate` command will then output an `.output/public/index.html` entrypoint and JavaScript bundles like a classic client-side Vue.js application.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  ssr: false,
})
```

## Hosting Providers

Nuxt can be deployed to several cloud providers with a minimal amount of configuration:

<read-more to="/deploy">



</read-more>

## Presets

In addition to Node.js servers and static hosting services, a Nuxt project can be deployed with several well-tested presets and minimal amount of configuration.

You can explicitly set the desired preset in the [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file:

```ts [nuxt.config.ts]twoslash
// @errors: 2353
export default defineNuxtConfig({
  nitro: {
    preset: 'node-server',
  },
})
```

... or use the `NITRO_PRESET` environment variable when running `nuxt build`:

```bash [Terminal]
NITRO_PRESET=node-server nuxt build
```

🔎 Check [the Nitro deployment](https://nitro.build/deploy) for all possible deployment presets and providers.

## CDN Proxy

In most cases, Nuxt can work with third-party content that is not generated or created by Nuxt itself. But sometimes such content can cause problems, especially Cloudflare's "Minification and Security Options".

Accordingly, you should make sure that the following options are unchecked / disabled in Cloudflare. Otherwise, unnecessary re-rendering or hydration errors could impact your production application.

1. Speed > Optimization > Content Optimization > Disable "Rocket Loader™"
2. Speed > Optimization > Image Optimization > Disable "Mirage"
3. Scrape Shield > Disable "Email Address Obfuscation"

With these settings, you can be sure that Cloudflare won't inject scripts into your Nuxt application that may cause unwanted side effects.

<tip>

Their location on the Cloudflare dashboard sometimes changes so don't hesitate to look around.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/dev-only.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/dev-only.md

# <DevOnly>

> Render components only during development with the <DevOnly> component.

Nuxt provides the `<DevOnly>` component to render a component only during development.

The content will not be included in production builds.

```vue [app/pages/example.vue]
<template>
  <div>
    <Sidebar />
    <DevOnly>
      <!-- this component will only be rendered during development -->
      <LazyDebugBar />

      <!-- if you ever require to have a replacement during production -->
      <!-- be sure to test these using `nuxt preview` -->
      <template #fallback>
        <div><!-- empty div for flex.justify-between --></div>
      </template>
    </DevOnly>
  </div>
</template>
```

## Slots

- `#fallback`: if you ever require to have a replacement during production.

```vue
<template>
  <div>
    <Sidebar />
    <DevOnly>
      <!-- this component will only be rendered during development -->
      <LazyDebugBar />
      <!-- be sure to test these using `nuxt preview` -->
      <template #fallback>
        <div><!-- empty div for flex.justify-between --></div>
      </template>
    </DevOnly>
  </div>
</template>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/dev.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/dev.md

# nuxt dev

> The dev command starts a development server with hot module replacement at http://localhost:3000

```bash [Terminal]
npx nuxt dev [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [--envName] [-e, --extends=<layer-name>] [--clear] [--no-f, --no-fork] [-p, --port] [-h, --host] [--clipboard] [-o, --open] [--https] [--publicURL] [--qr] [--public] [--tunnel] [--sslCert] [--sslKey]
```

The `dev` command starts a development server with hot module replacement at [http://localhost:3000](https://localhost:3000)

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --envName
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The environment to use when resolving configuration overrides (default is <code>
        production
      </code>
      
       when building, and <code>
        development
      </code>
      
       when running the dev server)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --clear
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Clear console on restart
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --no-f, --no-fork
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Disable forked mode
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -p, --port
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Port to listen on (default: <code>
        NUXT_PORT || NITRO_PORT || PORT || nuxtOptions.devServer.port
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -h, --host
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Host to listen on (default: <code>
        NUXT_HOST || NITRO_HOST || HOST || nuxtOptions.devServer?.host
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --clipboard
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Copy the URL to the clipboard
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -o, --open
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Open the URL in the browser
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --https
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Enable HTTPS
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --publicURL
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Displayed public URL (used for QR code)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --qr
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Display The QR code of public URL when available
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --public
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Listen to all network interfaces
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tunnel
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Open a tunnel using <a href="https://github.com/unjs/untun" rel="nofollow">
        https://github.com/unjs/untun
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --sslCert
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      (DEPRECATED) Use <code>
        --https.cert
      </code>
      
       instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --sslKey
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      (DEPRECATED) Use <code>
        --https.key
      </code>
      
       instead.
    </td>
  </tr>
</tbody>
</table>

The port and host can also be set via NUXT_PORT, PORT, NUXT_HOST or HOST environment variables.

Additionally to the above options, `@nuxt/cli` can pass options through to `listhen`, e.g. `--no-qr` to turn off the dev server QR code. You can find the list of `listhen` options in the [unjs/listhen](https://github.com/unjs/listhen) docs.

This command sets `process.env.NODE_ENV` to `development`.

<note>

If you are using a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/devtools.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/devtools.md

# nuxt devtools

> The devtools command allows you to enable or disable Nuxt DevTools on a per-project basis.

```bash [Terminal]
npx nuxt devtools <COMMAND> [ROOTDIR] [--cwd=<directory>]
```

Running `nuxt devtools enable` will install the Nuxt DevTools globally, and also enable it within the particular project you are using. It is saved as a preference in your user-level `.nuxtrc`. If you want to remove devtools support for a particular project, you can run `nuxt devtools disable`.

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        COMMAND
      </code>
    </td>
    
    <td>
      Command to run (options: <enable|disable>)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

<read-more icon="i-simple-icons-nuxtdotjs" target="\_blank" to="https://devtools.nuxt.com">

Read more about the **Nuxt DevTools**.

</read-more>

---

# Source: https://nuxt.com/raw/deploy/digitalocean.md

# DigitalOcean

> Deploy your Nuxt Application to DigitalOcean infrastructure.

Nuxt supports deploying on the [DigitalOcean App Platform](https://docs.digitalocean.com/products/app-platform/) with minimal configuration.

## Setup

1. Create a new DigitalOcean app following the [guide](https://docs.digitalocean.com/products/app-platform/how-to/create-apps/).
2. Next, you'll need to configure environment variables. In your app settings, ensure the following [app-level environment variables](https://docs.digitalocean.com/products/app-platform/how-to/use-environment-variables/):```bash
SERVER_PRESET=digital-ocean
```
3. You will need to ensure you set an `engines.node` field in your app's `package.json` to ensure DigitalOcean uses a supported version of Node.js:```json [package.json]
{
  "engines": {
      "node": "20.x"
  }
}
```
4. You'll also need to add a run command so DigitalOcean knows what command to run after a build. You can do so by adding a start script to your `package.json`:```json [package.json]
{
  "scripts": {
      "start": "node .output/server/index.mjs"
  }
}
```
5. Finally, you'll need to add this start script to your DigitalOcean app's run command. Go to `Components > Settings > Commands`, click "Edit", then add `npm run start`

<tip>

Your Nuxt app should be live at a DigitalOcean generated URL and you can now follow [the rest of the DigitalOcean deployment guide](https://docs.digitalocean.com/products/app-platform/how-to/manage-deployments/).

</tip>

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/digitalocean">

Head over **Nitro documentation** to learn more about the digitalocean deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure.md

# Nuxt Directory Structure

> Learn about the directory structure of a Nuxt application and how to use it.

Nuxt applications have a specific directory structure that is used to organize the code. This structure is designed to be easy to understand and to be used in a consistent way.

## Root Directory

The root directory of a Nuxt application is the directory that contains the `nuxt.config.ts` file. This file is used to configure the Nuxt application.

## App Directory

The `app/` directory is the main directory of the Nuxt application. It contains the following subdirectories:

- [`assets/`](/docs/4.x/directory-structure/app/assets): website's assets that the build tool (Vite or webpack) will process
- [`components/`](/docs/4.x/directory-structure/app/components): Vue components of the application
- [`composables/`](/docs/4.x/directory-structure/app/composables): add your Vue composables
- [`layouts/`](/docs/4.x/directory-structure/app/layouts): Vue components that wrap around your pages and avoid re-rendering between pages
- [`middleware/`](/docs/4.x/directory-structure/app/middleware): run code before navigating to a particular route
- [`pages/`](/docs/4.x/directory-structure/app/pages): file-based routing to create routes within your web application
- [`plugins/`](/docs/4.x/directory-structure/app/plugins): use Vue plugins and more at the creation of your Nuxt application
- [`utils/`](/docs/4.x/directory-structure/app/utils): add functions throughout your application that can be used in your components, composables, and pages.

This directory also includes specific files:

- [`app.config.ts`](/docs/4.x/directory-structure/app/app-config): a reactive configuration within your application
- [`app.vue`](/docs/4.x/directory-structure/app/app): the root component of your Nuxt application
- [`error.vue`](/docs/4.x/directory-structure/app/error): the error page of your Nuxt application

## Public Directory

The [`public/`](/docs/4.x/directory-structure/public) directory is the directory that contains the public files of the Nuxt application. Files contained within this directory are served at the root and are not modified by the build process.

This is suitable for files that have to keep their names (e.g. `robots.txt`) *or* likely won't change (e.g. `favicon.ico`).

## Server Directory

The [`server/`](/docs/4.x/directory-structure/server) directory is the directory that contains the server-side code of the Nuxt application. It contains the following subdirectories:

- [`api/`](/docs/4.x/directory-structure/server#server-routes): contains the API routes of the application.
- [`routes/`](/docs/4.x/directory-structure/server#server-routes): contains the server routes of the application (e.g. dynamic `/sitemap.xml`).
- [`middleware/`](/docs/4.x/directory-structure/server#server-middleware): run code before a server route is processed
- [`plugins/`](/docs/4.x/directory-structure/server#server-plugins): use plugins and more at the creation of the Nuxt server
- [`utils/`](/docs/4.x/directory-structure/server#server-utilities): add functions throughout your application that can be used in your server  code.

## Shared Directory

The [`shared/`](/docs/4.x/directory-structure/shared) directory is the directory that contains the shared code of the Nuxt application and Nuxt server. This code can be used in both the Vue app and the Nitro server.

## Content Directory

The [`content/`](/docs/4.x/directory-structure/content) directory is enabled by the [Nuxt Content](https://content.nuxt.com) module. It is used to create a file-based CMS for your application using Markdown files.

## Modules Directory

The [`modules/`](/docs/4.x/directory-structure/modules) directory is the directory that contains the local modules of the Nuxt application. Modules are used to extend the functionality of the Nuxt application.

## Layers Directory

The [`layers/`](/docs/4.x/directory-structure/layers) directory allows you to organize and share reusable code, components, composables, and configurations. Layers within this directory are automatically registered in your project.

## Nuxt Files

- [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file is the main configuration file for the Nuxt application.
- [`.nuxtrc`](/docs/4.x/directory-structure/nuxtrc) file is another syntax for configuring the Nuxt application (useful for global configurations).
- [`.nuxtignore`](/docs/4.x/directory-structure/nuxtignore) file is used to ignore files in the root directory during the build phase.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/dollarfetch.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/dollarfetch.md

# $fetch

> Nuxt uses ofetch to expose globally the $fetch helper for making HTTP requests.

Nuxt uses [ofetch](https://github.com/unjs/ofetch) to expose globally the `$fetch` helper for making HTTP requests within your Vue app or API routes.

<tip icon="i-lucide-rocket">

During server-side rendering, calling `$fetch` to fetch your internal [API routes](/docs/4.x/directory-structure/server) will directly call the relevant function (emulating the request), **saving an additional API call**.

</tip>

<note color="blue" icon="i-lucide-info">

Using `$fetch` in components without wrapping it with [`useAsyncData`](/docs/4.x/api/composables/use-async-data) causes fetching the data twice: initially on the server, then again on the client-side during hydration, because `$fetch` does not transfer state from the server to the client. Thus, the fetch will be executed on both sides because the client has to get the data again.

</note>

## Usage

We recommend using [`useFetch`](/docs/4.x/api/composables/use-fetch) or [`useAsyncData`](/docs/4.x/api/composables/use-async-data) + `$fetch` to prevent double data fetching when fetching the component data.

```vue [app/app.vue]
<script setup lang="ts">
// During SSR data is fetched twice, once on the server and once on the client.
const dataTwice = await $fetch('/api/item')

// During SSR data is fetched only on the server side and transferred to the client.
const { data } = await useAsyncData('item', () => $fetch('/api/item'))

// You can also useFetch as shortcut of useAsyncData + $fetch
const { data } = await useFetch('/api/item')
</script>
```

<read-more to="/docs/4.x/getting-started/data-fetching">



</read-more>

You can use `$fetch` in any methods that are executed only on client-side.

```vue [app/pages/contact.vue]
<script setup lang="ts">
async function contactForm () {
  await $fetch('/api/contact', {
    method: 'POST',
    body: { hello: 'world' },
  })
}
</script>

<template>
  <button @click="contactForm">
    Contact
  </button>
</template>
```

<tip>

`$fetch` is the preferred way to make HTTP calls in Nuxt instead of [@nuxt/http](https://github.com/nuxt/http) and [@nuxtjs/axios](https://github.com/nuxt-community/axios-module) that are made for Nuxt 2.

</tip>

<note>

If you use `$fetch` to call an (external) HTTPS URL with a self-signed certificate in development, you will need to set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment.

</note>

### Passing Headers and Cookies

When we call `$fetch` in the browser, user headers like `cookie` will be directly sent to the API.

However, during Server-Side Rendering, due to security risks such as **Server-Side Request Forgery (SSRF)** or **Authentication Misuse**, the `$fetch` wouldn't include the user's browser cookies, nor pass on cookies from the fetch response.

<code-group>

```vue [app/pages/index.vue]
<script setup lang="ts">
// This will NOT forward headers or cookies during SSR
const { data } = await useAsyncData(() => $fetch('/api/cookies'))
</script>
```

```ts [server/api/cookies.ts]
export default defineEventHandler((event) => {
  const foo = getCookie(event, 'foo')
  // ... Do something with the cookie
})
```

</code-group>

If you need to forward headers and cookies on the server, you must manually pass them:

```vue [app/pages/index.vue]
<script setup lang="ts">
// This will forward the user's headers and cookies to `/api/cookies`
const requestFetch = useRequestFetch()
const { data } = await useAsyncData(() => requestFetch('/api/cookies'))
</script>
```

However, when calling `useFetch` with a relative URL on the server, Nuxt will use [`useRequestFetch`](/docs/4.x/api/composables/use-request-fetch) to proxy headers and cookies (with the exception of headers not meant to be forwarded, like `host`).

---

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/ecosystem.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/ecosystem.md

# Publish & Share Your Module

> Join the Nuxt module ecosystem and publish your module to npm.

The [Nuxt module ecosystem](/modules) represents more than 35 million monthly NPM downloads and provides extended functionalities and integrations with all sort of tools. You can be part of this ecosystem!

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/exploring-nuxt-modules-ecosystem-and-module-types?friend=nuxt">

Watch Vue School video about Nuxt module types.

</tip>

## Understand Module Types

**Official modules** are modules prefixed (scoped) with `@nuxt/` (e.g. [`@nuxt/content`](https://content.nuxt.com)). They are made and maintained actively by the Nuxt team. Like with the framework, contributions from the community are more than welcome to help make them better!

**Community modules** are modules prefixed (scoped) with `@nuxtjs/` (e.g. [`@nuxtjs/tailwindcss`](https://tailwindcss.nuxtjs.org)). They are proven modules made and maintained by community members. Again, contributions are welcome from anyone.

**Third-party and other community modules** are modules (often) prefixed with `nuxt-`. Anyone can make them, using this prefix allows these modules to be discoverable on npm. This is the best starting point to draft and try an idea!

**Private or personal modules** are modules made for your own use case or company. They don't need to follow any naming rules to work with Nuxt and are often seen scoped under an npm organization (e.g. `@my-company/nuxt-auth`)

## List Your Module

Any community modules are welcome to be listed on [the module list](/modules). To be listed, [open an issue in the nuxt/modules](https://github.com/nuxt/modules/issues/new?template=module_request.yml) repository. The Nuxt team can help you to apply best practices before listing.

## Join nuxt-modules

By moving your modules to [nuxt-modules](https://github.com/nuxt-modules), there is always someone else to help, and this way, we can join forces to make one perfect solution.

If you have an already published and working module, and want to transfer it to `nuxt-modules`, [open an issue in nuxt/modules](https://github.com/nuxt/modules/issues/new).

By joining `nuxt-modules` we can rename your community module under the `@nuxtjs/` scope and provide a subdomain (e.g. `my-module.nuxtjs.org`) for its documentation.

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/env.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/env.md

# .env

> A .env file specifies your build/dev-time environment variables.

<important>

This file should be added to your [`.gitignore`](/docs/4.x/directory-structure/gitignore) file to avoid pushing secrets to your repository.

</important>

## Dev, Build and Generate Time

Nuxt CLI has built-in [dotenv](https://github.com/motdotla/dotenv) support in development mode and when running [`nuxt build`](/docs/4.x/api/commands/build) and [`nuxt generate`](/docs/4.x/api/commands/generate).

In addition to any process environment variables, if you have a `.env` file in your project root directory, it will be automatically loaded **at dev, build and generate time**. Any environment variables set there will be accessible within your `nuxt.config` file and modules.

```ini [.env]
MY_ENV_VARIABLE=hello
```

<note>

Note that removing a variable from `.env` or removing the `.env` file entirely will not unset values that have already been set.

</note>

## Custom File

If you want to use a different file - for example, to use `.env.local` or `.env.production` - you can do so by passing the `--dotenv` flag when using the Nuxt CLI.

```bash [Terminal]
npx nuxt dev --dotenv .env.local
```

When updating `.env` in development mode, the Nuxt instance is automatically restarted to apply new values to the `process.env`.

<important>

In your application code, you should use [Runtime Config](/docs/4.x/guide/going-further/runtime-config) instead of plain env variables.

</important>

## Production

**After your server is built**, you are responsible for setting environment variables when you run the server.

Your `.env` files will not be read at this point. How you do this is different for every environment.

This design decision was made to ensure compatibility across various deployment environments, some of which may not have a traditional file system available, such as serverless platforms or edge networks like Cloudflare Workers.

Since `.env` files are not used in production, you must explicitly set environment variables using the tools and methods provided by your hosting environment. Here are some common approaches:

- You can pass the environment variables as arguments using the terminal:<br />

`$ DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs`
- You can set environment variables in shell configuration files like `.bashrc` or `.profile`.
- Many cloud service providers, such as Vercel, Netlify, and AWS, provide interfaces for setting environment variables via their dashboards, CLI tools or configuration files.

<important>

`runtimeConfig` <span>

won't pick up environment variables that don't start with `NUXT_` in production

</span>

 ([https://nuxt.com/docs/4.x/guide/going-further/runtime-config#environment-variables](https://nuxt.com/docs/4.x/guide/going-further/runtime-config#environment-variables)).

</important>

## Production Preview

For local production preview purpose, we recommend using [`nuxt preview`](/docs/4.x/api/commands/preview) since using this command, the `.env` file will be loaded into `process.env` for convenience. Note that this command requires dependencies to be installed in the package directory.

Or you could pass the environment variables as arguments using the terminal. For example, on Linux or macOS:

```bash [Terminal]
DATABASE_HOST=mydatabaseconnectionstring node .output/server/index.mjs
```

Note that for a purely static site, it is not possible to set runtime configuration config after your project is prerendered.

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

<note>

If you want to use environment variables set at build time but do not care about updating these down the line (or only need to update them reactively *within* your app) then `appConfig` may be a better choice. You can define `appConfig` both within your `nuxt.config` (using environment variables) and also within an `~/app.config.ts` file in your project.

<read-more to="/docs/4.x/directory-structure/app/app-config">



</read-more>
</note>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/error-handling.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/error-handling.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/error-handling.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/error-handling.md

# Error Handling

> Learn how to catch and handle errors in Nuxt.

Nuxt is a full-stack framework, which means there are several sources of unpreventable user runtime errors that can happen in different contexts:

- Errors during the Vue rendering lifecycle (SSR & CSR)
- Server and client startup errors (SSR + CSR)
- Errors during Nitro server lifecycle ([`server/`](/docs/4.x/directory-structure/server) directory)
- Errors downloading JS chunks

<tip>

**SSR** stands for **Server-Side Rendering** and **CSR** for **Client-Side Rendering**.

</tip>

## Vue Errors

You can hook into Vue errors using [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured).

In addition, Nuxt provides a [`vue:error`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook that will be called if any errors propagate up to the top level.

If you are using an error reporting framework, you can provide a global handler through [`vueApp.config.errorHandler`](https://vuejs.org/api/application#app-config-errorhandler). It will receive all Vue errors, even if they are handled.

```ts [plugins/error-handler.ts]twoslash
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.config.errorHandler = (error, instance, info) => {
    // handle error, e.g. report to a service
  }

  // Also possible
  nuxtApp.hook('vue:error', (error, instance, info) => {
    // handle error, e.g. report to a service
  })
})
```

<note>

Note that the `vue:error` hook is based on [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured) lifecycle hook.

</note>

## Startup Errors

Nuxt will call the `app:error` hook if there are any errors in starting your Nuxt application.

This includes:

- running [Nuxt plugins](/docs/4.x/directory-structure/app/plugins)
- processing `app:created` and `app:beforeMount` hooks
- rendering your Vue app to HTML (during SSR)
- mounting the app (on client-side), though you should handle this case with `onErrorCaptured` or with `vue:error`
- processing the `app:mounted` hook

## Nitro Server Errors

You cannot currently define a server-side handler for these errors, but can render an error page, see the [Render an Error Page](/docs/4.x/getting-started/error-handling#error-page) section.

## Errors with JS Chunks

You might encounter chunk loading errors due to a network connectivity failure or a new deployment (which invalidates your old, hashed JS chunk URLs). Nuxt provides built-in support for handling chunk loading errors by performing a hard reload when a chunk fails to load during route navigation.

You can change this behavior by setting `experimental.emitRouteChunkError` to `false` (to disable hooking into these errors at all) or to `manual` if you want to handle them yourself. If you want to handle chunk loading errors manually, you can check out the [the automatic implementation](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/plugins/chunk-reload.client.ts) for ideas.

## Error Page

<note>

When Nuxt encounters a fatal error (any unhandled error on the server, or an error created with `fatal: true` on the client) it will either render a JSON response (if requested with `Accept: application/json` header) or trigger a full-screen error page.

</note>

An error may occur during the server lifecycle when:

- processing your Nuxt plugins
- rendering your Vue app into HTML
- a server API route throws an error

It can also occur on the client side when:

- processing your Nuxt plugins
- before mounting the application (`app:beforeMount` hook)
- mounting your app if the error was not handled with `onErrorCaptured` or `vue:error` hook
- the Vue app is initialized and mounted in browser (`app:mounted`).

<read-more to="/docs/4.x/api/advanced/hooks">

Discover all the Nuxt lifecycle hooks.

</read-more>

Customize the default error page by adding `~/error.vue` in the source directory of your application, alongside `app.vue`.

```vue [error.vue]
<script setup lang="ts">
import type { NuxtError } from '#app'

const props = defineProps({
  error: Object as () => NuxtError,
})

const handleError = () => clearError({ redirect: '/' })
</script>

<template>
  <div>
    <h2>{{ error?.status }}</h2>
    <button @click="handleError">
      Clear errors
    </button>
  </div>
</template>
```

<read-more to="/docs/4.x/directory-structure/app/error">

Read more about `error.vue` and its uses.

</read-more>

For custom errors we highly recommend using `onErrorCaptured` composable that can be called in a page/component setup function or `vue:error` runtime nuxt hook that can be configured in a nuxt plugin.

```ts [plugins/error-handler.ts]twoslash
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('vue:error', (err) => {
    //
  })
})
```

When you are ready to remove the error page, you can call the [`clearError`](/docs/4.x/api/utils/clear-error) helper function, which takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).

<important>

Make sure to check before using anything dependent on Nuxt plugins, such as `$route` or `useRouter`, as if a plugin threw an error, then it won't be re-run until you clear the error.

</important>

<note>

Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/4.x/getting-started/error-handling#useerror) in middleware to check if an error is being handled.

</note>

<note>

If you are running on Node 16 and you set any cookies when rendering your error page, they will [overwrite cookies previously set](https://github.com/nuxt/nuxt/pull/20585). We recommend using a newer version of Node as Node 16 reached end-of-life in September 2023.

</note>

## Error Utils

### `useError`

```ts [TS Signature]
function useError (): Ref<Error | { url, status, statusText, message, description, data }>
```

This function will return the global Nuxt error that is being handled.

<read-more to="/docs/4.x/api/composables/use-error">

Read more about `useError` composable.

</read-more>

### `createError`

```ts [TS Signature]
function createError (err: string | { cause, data, message, name, stack, status, statusText, fatal }): Error
```

Create an error object with additional metadata. You can pass a string to be set as the error `message` or an object containing error properties. It is usable in both the Vue and Server portions of your app, and is meant to be thrown.

If you throw an error created with `createError`:

- on server-side, it will trigger a full-screen error page which you can clear with [`clearError`](/docs/4.x/getting-started/error-handling#clearerror).
- on client-side, it will throw a non-fatal error for you to handle. If you need to trigger a full-screen error page, then you can do this by setting `fatal: true`.

```vue [pages/movies/[slug].vue]twoslash
<script setup lang="ts">
const route = useRoute()
const { data } = await useFetch(`/api/movies/${route.params.slug}`)

if (!data.value) {
  throw createError({
    status: 404,
    statusText: 'Page Not Found',
  })
}
</script>
```

<tip>

The `statusText` property is intended for short, HTTP-compliant status texts (e.g., "Not Found"). It should only contain horizontal tabs, spaces, and visible ASCII characters (`[\t\u0020-\u007E]`).

For any detailed descriptions, multi-line messages, or content with non-ASCII characters, you should always use the `message` property instead.

</tip>

<read-more to="/docs/4.x/api/utils/create-error">

Read more about `createError` util.

</read-more>

### `showError`

```ts [TS Signature]
function showError (err: string | Error | { status, statusText }): Error
```

You can call this function at any point on client-side, or (on server side) directly within middleware, plugins or `setup()` functions. It will trigger a full-screen error page which you can clear with [`clearError`](/docs/4.x/getting-started/error-handling#clearerror).

It is recommended instead to use `throw createError()`.

<read-more to="/docs/4.x/api/utils/show-error">

Read more about `showError` util.

</read-more>

### `clearError`

```ts [TS Signature]
function clearError (options?: { redirect?: string }): Promise<void>
```

This function will clear the currently handled Nuxt error. It also takes an optional path to redirect to (for example, if you want to navigate to a 'safe' page).

<read-more to="/docs/4.x/api/utils/clear-error">

Read more about `clearError` util.

</read-more>

## Render Error in Component

Nuxt also provides a [`<NuxtErrorBoundary>`](/docs/4.x/api/components/nuxt-error-boundary) component that allows you to handle client-side errors within your app, without replacing your entire site with an error page.

This component is responsible for handling errors that occur within its default slot. On client-side, it will prevent the error from bubbling up to the top level, and will render the `#error` slot instead.

The `#error` slot will receive `error` as a prop. (If you set `error = null` it will trigger re-rendering the default slot; you'll need to ensure that the error is fully resolved first or the error slot will just be rendered a second time.)

<tip>

If you navigate to another route, the error will be cleared automatically.

</tip>

```vue [app/pages/index.vue]
<template>
  <!-- some content -->
  <NuxtErrorBoundary @error="someErrorLogger">
    <!-- You use the default slot to render your content -->
    <template #error="{ error, clearError }">
      You can display the error locally here: {{ error }}
      <button @click="clearError">
        This will clear the error.
      </button>
    </template>
  </NuxtErrorBoundary>
</template>
```

<link-example to="/docs/4.x/examples/advanced/error-handling">



</link-example>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/error.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/error.md

# error.vue

> The error.vue file is the error page in your Nuxt application.

During the lifespan of your application, some errors may appear unexpectedly at runtime. In such case, we can use the `error.vue` file to override the default error files and display the error nicely.

```vue [error.vue]
<script setup lang="ts">
import type { NuxtError } from '#app'

const props = defineProps<{ error: NuxtError }>()
</script>

<template>
  <div>
    <h1>{{ error.status }}</h1>
    <NuxtLink to="/">Go back home</NuxtLink>
  </div>
</template>
```

<note>

Although it is called an 'error page' it's not a route and shouldn't be placed in your `~/pages` directory. For the same reason, you shouldn't use `definePageMeta` within this page. That being said, you can still use layouts in the error file, by utilizing the [`NuxtLayout`](/docs/4.x/api/components/nuxt-layout) component and specifying the name of the layout.

</note>

The error page has a single prop - `error` which contains an error for you to handle.

The `error` object provides the following fields:

```ts
interface NuxtError {
  status: number
  fatal: boolean
  unhandled: boolean
  statusText?: string
  data?: unknown
  cause?: unknown
  // legacy/deprecated equivalent of `status`
  statusCode: number
  // legacy/deprecated equivalent of `statusText`
  statusMessage?: string
}
```

If you have an error with custom fields they will be lost; you should assign them to `data` instead:

```ts
throw createError({
  status: 404,
  statusText: 'Page Not Found',
  data: {
    myCustomField: true,
  },
})
```

---

# Source: https://nuxt.com/raw/blog/eslint-module.md

# Refreshed Nuxt ESLint Integrations

> We revamped our ESLint integrations to support ESLint v9 with the flat config, as well as a new module with many more capabilities.

## TL;DR

We revamped our ESLint integrations to support ESLint v9 with the new flat config. Along the way, we have explored many new possibilities to make it more personalized, powerful, and with better developer experience.

You can run the following command to install the new [`@nuxt/eslint`](https://eslint.nuxt.com/packages/module) module:

```bash [Terminal]
npx nuxi module add eslint
```

Continue reading the story or learn more with [the documentation](https://eslint.nuxt.com/packages/module).

## Background

[ESLint](https://eslint.org/) has become an essential tool for today's web development. It helps you to catch errors and enforce a consistent coding style in your project. At Nuxt, we do our best to provide an out-of-the-box experience for ESLint, making it easy to use, configure and follow the best practices we recommend.

Since, both Nuxt and ESLint have evolved a lot. Historically, we ended up with [a few different packages and integrations for ESLint in Nuxt](https://eslint.nuxt.com/guide/faq#package-disambiguation), and it wasn't always obvious which one to use for what purpose. We have received a lot of feedback from our community.

To improve the situation and also make it future-proof, we recently refreshed our ESLint integrations to support [ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/) with the [flat config](https://eslint.org/docs/latest/use/configure/configuration-files). It opens up many more capabilities for customizing your ESLint setup, providing a more straightforward and unified experience.

## Nuxt ESLint Monorepo

We moved ESLint-related packages scattered across different repositories into a single monorepo: [`nuxt/eslint`](https://github.com/nuxt/eslint), with a dedicated new documentation site: [eslint.nuxt.com](https://eslint.nuxt.com/).

To help understand the differences between each package and what to use, we also have a [FAQ](https://eslint.nuxt.com/guide/faq) page comparing them and explaining their scopes.

This monorepo now includes:

- `@nuxt/eslint` - The new, all-in-one ESLint module for Nuxt 3, supporting project-aware ESLint flat config and more.
- `@nuxt/eslint-config` - The unopinionated but customizable shared ESLint config for Nuxt 3. Supports both [the flat config format](https://eslint.org/docs/latest/use/configure/configuration-files) and [the legacy format](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated).
- `@nuxt/eslint-plugin` - The ESLint plugin for Nuxt 3 provides Nuxt-specific rules and configurations.
- Two packages for Nuxt 2 in maintenance mode.

## ESLint Flat Config

Before diving into new Nuxt integrations, let me introduce you to the concept of [ESLint flat config](https://eslint.org/docs/latest/use/configure/configuration-files).

Flat config is a configuration format introduced in ESLint `v8.21.0` as experimental, and became the default format in [ESLint v9](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/).

A quick reference to differentiate:

- **Flat config**: `eslint.config.js` `eslint.config.mjs` etc.
- **Legacy config**: `.eslintrc` `.eslintrc.json` `.eslintrc.js` etc.

### Why Flat Config?

[This blog post from ESLint](https://eslint.org/blog/2022/08/new-config-system-part-1/) explains the motivation behind the flat config system in detail. In short, the legacy `eslintrc` format was designed in the early time of JavaScript, when ES modules and modern JavaScript features were not yet standardized. Many implicit conventions involved, and the `extends` feature makes the final config result hard to understand and predict. Which also makes shared configs hard to maintain and debug.

```jsonc [.eslintrc]
{
  "extends": [
    // Solve from `import("@nuxtjs/eslint-config").then(mod => mod.default)`
    "@nuxtjs",
    // Solve from `import("eslint-config-vue").then(mod => mod.default.configs["vue3-recommended"])`
    "plugin:vue/vue3-recommended",
  ],
  "rules": {
    // ...
  }
}
```

The new flat config moves the plugins and configs resolution from ESLint's internal convention to the native ES module resolution. This in turn makes it more explicit and transparent, allowing you to even import it from other modules. Since the flat config is just a JavaScript module, it also opens the door for much more customization.

## Nuxt Presets for Flat Config

In the latest [`@nuxt/eslint-config` package](https://eslint.nuxt.com/packages/config#flat-config-format), we leverage the flexibility we have to provide a factory function that allows you to customize the config presets easily in a more high-level way. Here is an example of how you can use it:

```ts [eslint.config.js]
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt()
```

`@nuxt/eslint-config` starts with an unopinionated base config, which means we only include rules for best practices of TypeScript, Vue and Nuxt, and leave the rest like code style, formatting, etc for you to decide. You can also run [Prettier](https://prettier.io/) alongside for formatting with the defaults.

The config also allows you to opt-in to more opinionated features as needed. For example, if you want ESLint to take care of the formatting as well, you can turn it on by passing `features.stylistic` to the factory function (powered by [ESLint Stylistic](https://eslint.style/)):

```ts [eslint.config.js]
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    stylistic: true
  }
})
```

Or tweak your preferences with an options object ([learn more with the options here](https://eslint.style/guide/config-presets#configuration-factory)):

```ts [eslint.config.js]
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    stylistic: {
      semi: false,
      indent: 2, // 4 or 'tab'
      quotes: 'single',
      // ... and more
    }
  }
})
```

And if you are [authoring a Nuxt Module](https://nuxt.com/docs/guide/going-further/modules), you can turn on `features.tooling` to enable the rules for the Nuxt module development:

```ts [eslint.config.js]
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    tooling: true
  }
})
```

...and so on. The factory function in flat config allows the presets to cover the complexity of the underlying ESLint configuration, and provide high-level and user-friendly abstractions for end users to customize. All this without requiring users to worry about the internal details.

While this approach offers you a Prettier-like experience with minimal configurations (because it's powered by ESLint), you still get the full flexibility to customize and override fine-grained rules and plugins as needed.

We also made a [`FlatConfigComposer`](https://github.com/antfu/eslint-flat-config-utils#composer) utility from [`eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils) to make it even easier to override and extend the flat config. The factory function in `@nuxt/eslint-config/flat` returns a `FlatConfigComposer` instance:

```ts [eslint.config.js]
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  // ...options for Nuxt integration
})
  .append(
    // ...append other flat config items
  )
  .prepend(
    // ...prepend other flat config items before the base config
  )
  // override a specific config item based on their name
  .override(
    'nuxt/typescript', // specify the name of the target config, or index
    {
      rules: {
        // ...override the rules
        '@typescript-eslint/no-unsafe-assignment': 'off'
      }
    }
  )
  // an so on, operations are chainable
```

With this approach, we get the best of both worlds: the simplicity and high-level abstraction for easy to use, and the power for customization and fine-tuning.

## Nuxt ESLint Module

Taking this even further, we made the new, all-in-one [`@nuxt/eslint` module](https://eslint.nuxt.com/packages/module) for Nuxt 3. It leverages Nuxt's context to generate project-aware and type-safe ESLint configurations for your project.

### Project-aware Rules

We know that Vue's Style Guide suggests the use of [multi-word names for components](https://vuejs.org/style-guide/rules-essential.html#use-multi-word-component-names) to avoid conflicts with existing and future HTML elements. Thus, in [`eslint-plugin-vue`](https://github.com/vuejs/eslint-plugin-vue), we have the rule [`vue/multi-word-component-names`](https://eslint.vuejs.org/rules/multi-word-component-names.html) enabled by default. It's a good practice to follow, but we know that in a Nuxt project, not all `.vue` files are registered as components. Files like `app.vue`, `pages/index.vue`, `layouts/default.vue`, etc. are not available as components in other Vue files, and the rule will be irrelevant to them.

Usually, we could turn off the rule for those files like:

```js [eslint.config.js]
export default [
  {
    files: ['*.vue'],
    rules: {
      'vue/multi-word-component-names': 'error'
    }
  },
  {
    files: ['app.vue', 'error.vue', 'pages/**/*.vue', 'layouts/**/*.vue'],
    rules: {
      // disable the rule for these files
      'vue/multi-word-component-names': 'off'
    }
  }
]
```

It should work for the majority of the cases. However, we know that in Nuxt you can [customize the path for each directory](https://nuxt.com/docs/api/nuxt-config#dir), and [layers](https://nuxt.com/docs/getting-started/layers) allow you to have multiple sources for each directory. This means the linter rules will be less accurate and potentially cause users extra effort to keep them aligned **manually**.

Similarly, we want to have [`vue/no-multiple-template-root`](https://eslint.vuejs.org/rules/no-multiple-template-root.html) enabled only for `pages` and `layouts`, etc. As the cases grow, it becomes unrealistic to ask users to maintain the rules manually.

That's where the magic of `@nuxt/eslint` comes in! It leverages Nuxt's context to generate the configurations and rules specific to your project structure. Very similar to the [`.nuxt/tsconfig.json`](http://nuxt.com/docs/guide/concepts/typescript#auto-generated-types) Nuxt provides, you now also have the project-aware `.nuxt/eslint.config.mjs` to extend from.

To use it, you can add the module to your Nuxt project:

```bash [Terminal]
npx nuxi module add eslint
```

### Config Inspector DevTools Integrations

During the migrations and research for the new flat config, I came up with the idea to make an interactive UI inspector for the flat config and make the configurations more transparent and easier to understand. We have integrated it into [Nuxt DevTools](https://github.com/nuxt/devtools) when you have the `@nuxt/eslint` module installed so you easily access it whenever you need it.

![Screenshot of ESLint Config Inspector running as a tab in Nuxt DevTools](/assets/blog/nuxt-eslint-inspector.png)

The inspector allows you to see the final resolved configurations, rules and plugins that have been enabled, and do quick matches to see how rules and configurations have applied to specific files. It's great for debugging and learning how ESLint works in your project.

We are delighted that the ESLint team also finds it useful and is interested in having it for the broader ESLint community. We later joined the effort and made it [the official ESLint Config Inspector](https://github.com/eslint/config-inspector) (it's built with Nuxt, by the way). You can read [this announcement post](https://eslint.org/blog/2024/04/eslint-config-inspector/) for more details.

### Type Generation for Rules

One of the main pain points of configuring ESLint was the leak of type information for the rules and configurations. It's hard to know what options are available for a specific rule, and it would require you to jump around the documentation for every rule to figure that out.

Thanks again for the new flat config being dynamic with so many possibilities. We figured out a new tool, [`eslint-typegen`](https://github.com/antfu/eslint-typegen), that we could generate the corresponding types from rules configuration schema for each rule **based on the actual plugins you are using**. This means it's a universal solution that works for any ESLint plugins, and the types are always accurate and up-to-date.

In the `@nuxt/eslint` module, this feature is integrated out-of-box, so that you will get this awesome experience right away:

![Screenshot of VS Code that showcases the type check and autocomplete with ESLint rules config](/assets/blog/nuxt-eslint-typegen.png)

### Dev Server Checker

With the new module, we took the chance to merge the [`@nuxtjs/eslint-module`](https://github.com/nuxt-modules/eslint) and the dev server checker for ESLint into the new `@nuxt/eslint` module as an opt-in feature.

<note>

You might not need this feature most of the time, as your editor integration should already provide ESLint diagnostics right in your editor. However, for some teams that work with different editors and want to ensure ESLint is always running, being able to run ESLint within the dev server might be helpful in some cases.

</note>

To enable it, you can set the `checker` option to `true` in the module options:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nuxt/eslint'
  ],
  eslint: {
    checker: true // <---
  }
})
```

Whenever you get some ESLint errors, you will see a warning in the console and the browser. To learn more about this feature, you can check the [documentation](https://eslint.nuxt.com/packages/module#dev-server-checker).

### Module Hooks

Since we are now in the Nuxt module with the codegen capabilities and the project-aware configurations, we can actually do a lot more interesting things with this. One is that we can allow modules to contribute to the ESLint configurations as well. Imagine that in the future, when you install a Nuxt module like `@nuxtjs/i18n` it can automatically enable specific ESLint rules for i18n-related files, or when you install something like `@pinia/nuxt` it can install the Pinia ESLint plugin to enforce the best practices for Pinia, etc.

As an experiment, we made a module [`nuxt-eslint-auto-explicit-import`](https://github.com/antfu/nuxt-eslint-auto-explicit-import) that can do auto inserts for the auto-imports registered in your Nuxt project with a preconfigured ESLint preset. So that you can get the same nice developer experience with auto-imports on using APIs, but still have the auto-inserted explicit imports in your codebase.

This is still in the early stages, and we are still exploring the possibilities and best practices. But we are very excited about the potential and the opportunities it opens up. We will collaborate with the community to see how we can make the most out of it. If you have any ideas or feedback, please do not hesitate to share them with us!

## Ecosystem

At Nuxt, we care a lot about the ecosystem and the community as always. During our explorations to adopt the new flat config and improve the developer experience, we made quite a few tools to reach that goal. All of them are general-purposed and can be used outside of Nuxt:

- [`@eslint/config-inspector`](https://github.com/eslint/config-inspector) - The official ESLint Config Inspector, provides interactive UI for your configs.
- [`eslint-typegen`](https://github.com/antfu/eslint-typegen) - Generate TypeScript types for ESLint rules based on the actual plugins you are using.
- [`eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils) - Utilities for managing and composing ESLint flat configs.

We are committed to supporting the broader community and collaborating with developers to improve these tools and expand their possibilities. We are excited to see how these tools can benefit the ESLint ecosystem and contribute to the overall developer experience.

## The Future

<tip>

The flat config format is still fairly new, and ESLint v9 was just released a couple of weeks ago. Plugins and the community are gradually catching up to the new format. It's still in the phase of exploration and experimentation.

</tip>

Looking ahead, we are eager to see how the ESLint ecosystem will continue to evolve and how we can leverage new capabilities and possibilities to further enhance Nuxt's developer experience. We are dedicated to providing a seamless and powerful development environment for Nuxt users, and we will continue to explore new ideas and collaborate with the community to achieve this goal.

---

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/esm.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/esm.md

# ES Modules

> Nuxt uses native ES modules.

This guide helps explain what ES Modules are and how to make a Nuxt app (or upstream library) compatible with ESM.

## Background

### CommonJS Modules

CommonJS (CJS) is a format introduced by Node.js that allows sharing functionality between isolated JavaScript modules ([read more](https://nodejs.org/api/modules.html)).
You might be already familiar with this syntax:

```js
const a = require('./a')

module.exports.a = a
```

Bundlers like webpack and Rollup support this syntax and allow you to use modules written in CommonJS in the browser.

### ESM Syntax

Most of the time, when people talk about ESM vs. CJS, they are talking about a different syntax for writing [modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).

```js
import a from './a'

export { a }
```

Before ECMAScript Modules (ESM) became a standard (it took more than 10 years!), tooling like
[webpack](https://webpack.js.org/guides/ecma-script-modules/) and even languages like TypeScript started supporting so-called **ESM syntax**.
However, there are some key differences with actual spec; here's [a helpful explainer](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/).

### What is 'Native' ESM?

You may have been writing your app using ESM syntax for a long time. After all, it's natively supported by the browser, and in Nuxt 2 we compiled all the code you wrote to the appropriate format (CJS for server, ESM for browser).

When adding modules to your package, things were a little different. A sample library might expose both CJS and ESM versions, and let us pick which one we wanted:

```json
{
  "name": "sample-library",
  "main": "dist/sample-library.cjs.js",
  "module": "dist/sample-library.esm.js"
}
```

So in Nuxt 2, the bundler (webpack) would pull in the CJS file ('main') for the server build and use the ESM file ('module') for the client build.

<note>

The `module` field is a convention used by bundlers like webpack and Rollup, but is not recognized by Node.js itself. Node.js only uses the [`exports`](https://nodejs.org/api/packages.html#exports) and [`main`](https://nodejs.org/api/packages.html#main) fields for module resolution.

</note>

However, in recent Node.js LTS releases, it is now possible to [use native ESM module](https://nodejs.org/api/esm.html) within Node.js. That means that Node.js itself can process JavaScript using ESM syntax, although it doesn't do it by default. The two most common ways to enable ESM syntax are:

- set `"type": "module"` within your `package.json` and keep using `.js` extension
- use the `.mjs` file extensions (recommended)

This is what we do for Nuxt Nitro; we output a `.output/server/index.mjs` file. That tells Node.js to treat this file as a native ES module.

### What Are Valid Imports in a Node.js Context?

When you `import` a module rather than `require` it, Node.js resolves it differently. For example, when you import `sample-library`, Node.js will look for the `exports` entry in that library's `package.json`, or fall back to the `main` entry if `exports` is not defined.

This is also true of dynamic imports, like `const b = await import('sample-library')`.

Node supports the following kinds of imports (see [docs](https://nodejs.org/api/packages.html#determining-module-system)):

1. files ending in `.mjs` - these are expected to use ESM syntax
2. files ending in `.cjs` - these are expected to use CJS syntax
3. files ending in `.js` - these are expected to use CJS syntax unless their `package.json` has `"type": "module"`

### What Kinds of Problems Can There Be?

For a long time module authors have been producing ESM-syntax builds but using conventions like `.esm.js` or `.es.js`, which they have added to the `module` field in their `package.json`. This hasn't been a problem until now because they have only been used by bundlers like webpack, which don't especially care about the file extension.

However, if you try to import a package with an `.esm.js` file in a Node.js ESM context, it won't work, and you'll get an error like:

```bash [Terminal]
(node:22145) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
/path/to/index.js:1

export default {}
^^^^^^

SyntaxError: Unexpected token 'export'
    at wrapSafe (internal/modules/cjs/loader.js:1001:16)
    at Module._compile (internal/modules/cjs/loader.js:1049:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    ....
    at async Object.loadESM (internal/process/esm_loader.js:68:5)
```

You might also get this error if you have a named import from an ESM-syntax build that Node.js thinks is CJS:

```bash [Terminal]
file:///path/to/index.mjs:5
import { named } from 'sample-library'
         ^^^^^
SyntaxError: Named export 'named' not found. The requested module 'sample-library' is a CommonJS module, which may not support all module.exports as named exports.

CommonJS modules can always be imported via the default export, for example using:

import pkg from 'sample-library';
const { named } = pkg;

    at ModuleJob._instantiate (internal/modules/esm/module_job.js:120:21)
    at async ModuleJob.run (internal/modules/esm/module_job.js:165:5)
    at async Loader.import (internal/modules/esm/loader.js:177:24)
    at async Object.loadESM (internal/process/esm_loader.js:68:5)
```

## Troubleshooting ESM Issues

If you encounter these errors, the issue is almost certainly with the upstream library. They need to [fix their library](/docs/4.x/guide/concepts/esm#library-author-guide) to support being imported by Node.

### Transpiling Libraries

In the meantime, you can tell Nuxt not to try to import these libraries by adding them to `build.transpile`:

```tstwoslash
export default defineNuxtConfig({
  build: {
    transpile: ['sample-library'],
  },
})
```

You may find that you *also* need to add other packages that are being imported by these libraries.

### Aliasing Libraries

In some cases, you may also need to manually alias the library to the CJS version, for example:

```tstwoslash
export default defineNuxtConfig({
  alias: {
    'sample-library': 'sample-library/dist/sample-library.cjs.js',
  },
})
```

### Default Exports

A dependency with CommonJS format, can use `module.exports` or `exports` to provide a default export:

```js [node_modules/cjs-pkg/index.js]
module.exports = { test: 123 }
// or
exports.test = 123
```

This normally works well if we `require` such dependency:

```js [test.cjs]
const pkg = require('cjs-pkg')

console.log(pkg) // { test: 123 }
```

[Node.js in native ESM mode](https://nodejs.org/api/esm.html#interoperability-with-commonjs), [typescript with `esModuleInterop` enabled](https://www.typescriptlang.org/tsconfig/#esModuleInterop) and bundlers such as webpack, provide a compatibility mechanism so that we can default import such library.
This mechanism is often referred to as "interop require default":

```js
import pkg from 'cjs-pkg'

console.log(pkg) // { test: 123 }
```

However, because of the complexities of syntax detection and different bundle formats, there is always a chance that the interop default fails and we end up with something like this:

```js
import pkg from 'cjs-pkg'

console.log(pkg) // { default: { test: 123 } }
```

Also when using dynamic import syntax (in both CJS and ESM files), we always have this situation:

```js
import('cjs-pkg').then(console.log) // [Module: null prototype] { default: { test: '123' } }
```

In this case, we need to manually interop the default export:

```js
// Static import
import { default as pkg } from 'cjs-pkg'

// Dynamic import
import('cjs-pkg').then(m => m.default || m).then(console.log)
```

For handling more complex situations and more safety, we recommend and internally use [mlly](https://github.com/unjs/mlly) in Nuxt that can preserve named exports.

```js
import { interopDefault } from 'mlly'

// Assuming the shape is { default: { foo: 'bar' }, baz: 'qux' }
import myModule from 'my-module'

console.log(interopDefault(myModule)) // { foo: 'bar', baz: 'qux' }
```

## Library Author Guide

The good news is that it's relatively simple to fix issues of ESM compatibility. There are two main options:

1. **You can rename your ESM files to end with .mjs.**<br />

*This is the recommended and simplest approach.* You may have to sort out issues with your library's dependencies and possibly with your build system, but in most cases, this should fix the problem for you. It's also recommended to rename your CJS files to end with `.cjs`, for the greatest explicitness.
2. **You can opt to make your entire library ESM-only**.<br />

This would mean setting `"type": "module"` in your `package.json` and ensuring that your built library uses ESM syntax. However, you may face issues with your dependencies - and this approach means your library can *only* be consumed in an ESM context.

### Migration

The initial step from CJS to ESM is updating any usage of `require` to use `import` instead:

<code-group>

```ts [Before]
module.exports = function () { /* ... */ }

exports.hello = 'world'
```

```ts [After]
export default function () { /* ... */ }

export const hello = 'world'
```

</code-group>

<code-group>

```js [Before]
const myLib = require('my-lib')
```

```js [After]
import myLib from 'my-lib'
// or
const dynamicMyLib = await import('my-lib').then(lib => lib.default || lib)
```

</code-group>

In ESM Modules, unlike CJS, `require`, `require.resolve`, `__filename` and `__dirname` globals are not available
and should be replaced with `import()` and `import.meta.filename`.

<code-group>

```js [Before]
const { join } = require('node:path')

const newDir = join(__dirname, 'new-dir')
```

```js [After]
import { fileURLToPath } from 'node:url'

const newDir = fileURLToPath(new URL('./new-dir', import.meta.url))
```

</code-group>

<code-group>

```js [Before]
const someFile = require.resolve('./lib/foo.js')
```

```js [After]
import { resolvePath } from 'mlly'

const someFile = await resolvePath('my-lib', { url: import.meta.url })
```

</code-group>

### Best Practices

- Prefer named exports rather than default export. This helps reduce CJS conflicts. (see [Default exports](/docs/4.x/guide/concepts/esm#default-exports) section)
- Avoid depending on Node.js built-ins and CommonJS or Node.js-only dependencies as much as possible to make your library usable in Browsers and Edge Workers without needing Nitro polyfills.
- Use new `exports` field with conditional exports. ([read more](https://nodejs.org/api/packages.html#conditional-exports)).

```json
{
  "exports": {
    ".": {
      "import": "./dist/mymodule.mjs"
    }
  }
}
```

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/events.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/events.md

# Creating Custom Events

> Nuxt provides a powerful event system powered by hookable.

Using events is a great way to decouple your application and allow for more flexible and modular communication between different parts of your code. Events can have multiple listeners that do not depend on each other. For example, you may wish to send an email to your user each time an order has shipped. Instead of coupling your order processing code to your email code, you can emit an event which a listener can receive and use to dispatch an email.

The Nuxt event system is powered by [unjs/hookable](https://github.com/unjs/hookable), which is the same library that powers the Nuxt hooks system.

## Creating Events and Listeners

You can create your own custom events using the `hook` method:

```ts
const nuxtApp = useNuxtApp()

nuxtApp.hook('app:user:registered', (payload) => {
  console.log('A new user has registered!', payload)
})
```

To emit an event and notify any listeners, use `callHook`:

```ts
const nuxtApp = useNuxtApp()

await nuxtApp.callHook('app:user:registered', {
  id: 1,
  name: 'John Doe',
})
```

You can also use the payload object to enable two-way communication between the emitter and listeners. Since the payload is passed by reference, a listener can modify it to send data back to the emitter.

```ts
const nuxtApp = useNuxtApp()

nuxtApp.hook('app:user:registered', (payload) => {
  payload.message = 'Welcome to our app!'
})

const payload = {
  id: 1,
  name: 'John Doe',
}

await nuxtApp.callHook('app:user:registered', {
  id: 1,
  name: 'John Doe',
})

// payload.message will be 'Welcome to our app!'
```

<tip>

You can inspect all events using the **Nuxt DevTools** Hooks panel.

</tip>

<read-more to="/docs/4.x/guide/going-further/hooks">

Learn more about Nuxt's built-in hooks and how to extend them

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/examples.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/examples.md

# Examples

> Examples of Nuxt Kit utilities in use.

## Accessing Nuxt Vite Config

If you are building an integration that needs access to the runtime Vite or webpack config that Nuxt uses, it is possible to extract this using Kit utilities.

Some examples of projects doing this already:

- [histoire](https://github.com/histoire-dev/histoire/blob/main/packages/histoire-plugin-nuxt/src/index.ts)
- [nuxt-vitest](https://github.com/danielroe/nuxt-vitest/blob/main/packages/nuxt-vitest/src/config.ts)
- [@storybook-vue/nuxt](https://github.com/storybook-vue/storybook-nuxt/blob/main/packages/storybook-nuxt/src/preset.ts)

Here is a brief example of how you might access the Vite config from a project; you could implement a similar approach to get the webpack configuration.

```js
import { buildNuxt, loadNuxt } from '@nuxt/kit'

// https://github.com/nuxt/nuxt/issues/14534
async function getViteConfig () {
  const nuxt = await loadNuxt({ cwd: process.cwd(), dev: false, overrides: { ssr: false } })
  return new Promise((resolve, reject) => {
    nuxt.hook('vite:extend', (config) => {
      resolve(config)
      throw new Error('_stop_')
    })
    buildNuxt(nuxt).catch((err) => {
      if (!err.toString().includes('_stop_')) {
        reject(err)
      }
    })
  }).finally(() => nuxt.close())
}

const viteConfig = await getViteConfig()
console.log(viteConfig)
```

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/experimental-features.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/experimental-features.md

# Experimental Features

> Enable Nuxt experimental features to unlock new possibilities.

Nuxt includes experimental features that you can enable in your configuration file.

Internally, Nuxt uses `@nuxt/schema` to define these experimental features. You can refer to the [API documentation](/docs/4.x/guide/going-further/experimental-features) or the [source code](https://github.com/nuxt/nuxt/blob/main/packages/schema/src/config/experimental.ts) for more information.

<note>

Note that these features are experimental and could be removed or modified in the future.

</note>

## alwaysRunFetchOnKeyChange

Whether to run `useFetch` when the key changes, even if it is set to `immediate: false` and it has not been triggered yet.

`useFetch` and `useAsyncData` will always run when the key changes if `immediate: true` or if it has been already triggered.

This flag is disabled by default, but you can enable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: true,
  },
})
```

## appManifest

Use app manifests to respect route rules on client-side.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    appManifest: false,
  },
})
```

## asyncContext

Enable native async context to be accessible for nested composables in Nuxt and in Nitro. This opens the possibility to use composables inside async composables and reduce the chance to get the `Nuxt instance is unavailable` error.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    asyncContext: true,
  },
})
```

<read-more to="https://github.com/nuxt/nuxt/pull/20918" icon="i-simple-icons-github" target="_blank">

See full explanation on the GitHub pull-request.

</read-more>

## asyncEntry

Enables generation of an async entry point for the Vue bundle, aiding module federation support.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    asyncEntry: true,
  },
})
```

## externalVue

Externalizes `vue`, `@vue/*` and `vue-router` when building.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    externalVue: false,
  },
})
```

<warning>

This feature will likely be removed in a near future.

</warning>

## extractAsyncDataHandlers

Extracts handler functions from `useAsyncData` and `useLazyAsyncData` calls into separate chunks for improved code splitting and caching efficiency.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true,
  },
})
```

This feature transforms inline handler functions into dynamically imported chunks:

```vue
<!-- Before -->
<script setup>
const { data } = await useAsyncData('user', async () => {
  return await $fetch('/api/user')
})
</script>
```

```vue
<!-- After transformation -->
<script setup>
const { data } = await useAsyncData('user', () =>
  import('/generated-chunk.js').then(r => r.default()),
)
</script>
```

The benefit of this transformation is that we can split out data fetching logic — while still allowing the code to be loaded if required.

<important>

This feature is only recommended for **static builds** with payload extraction, and where data does not need to be re-fetched at runtime.

</important>

## emitRouteChunkError

Emits `app:chunkError` hook when there is an error loading vite/webpack chunks. Default behavior is to perform a reload of the new route on navigation to a new route when a chunk fails to load.

By default, Nuxt will also perform a reload of the new route when a chunk fails to load when navigating to a new route (`automatic`).

Setting `automatic-immediate` will lead Nuxt to perform a reload of the current route right when a chunk fails to load (instead of waiting for navigation). This is useful for chunk errors that are not triggered by navigation, e.g., when your Nuxt app fails to load a [lazy component](/docs/4.x/directory-structure/app/components#dynamic-imports). A potential downside of this behavior is undesired reloads, e.g., when your app does not need the chunk that caused the error.

You can disable automatic handling by setting this to `false`, or handle chunk errors manually by setting it to `manual`.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    emitRouteChunkError: 'automatic', // or 'automatic-immediate', 'manual' or false
  },
})
```

## enforceModuleCompatibility

Whether Nuxt should throw an error (and fail to load) if a Nuxt module is incompatible.

This feature is disabled by default.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    enforceModuleCompatibility: true,
  },
})
```

## restoreState

Allows Nuxt app state to be restored from `sessionStorage` when reloading the page after a chunk error or manual [`reloadNuxtApp()`](/docs/4.x/api/utils/reload-nuxt-app) call.

To avoid hydration errors, it will be applied only after the Vue app has been mounted, meaning there may be a flicker on initial load.

<important>

Consider carefully before enabling this as it can cause unexpected behavior,
and consider providing explicit keys to [`useState`](/docs/4.x/api/composables/use-state) as auto-generated keys may not match across builds.

</important>

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    restoreState: true,
  },
})
```

## inlineRouteRules

Define route rules at the page level using [`defineRouteRules`](/docs/4.x/api/utils/define-route-rules).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    inlineRouteRules: true,
  },
})
```

Matching route rules will be created, based on the page's `path`.

<read-more to="/docs/4.x/api/utils/define-route-rules" icon="i-lucide-square-function">

Read more in `defineRouteRules` utility.

</read-more>

<read-more to="/docs/4.x/guide/concepts/rendering#hybrid-rendering" icon="i-lucide-medal">



</read-more>

## renderJsonPayloads

Allows rendering of JSON payloads with support for revivifying complex types.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: false,
  },
})
```

## noVueServer

Disables Vue server renderer endpoint within Nitro.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    noVueServer: true,
  },
})
```

## parseErrorData

Whether to parse `error.data` when rendering a server error page.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    parseErrorData: false,
  },
})
```

## payloadExtraction

Enables extraction of payloads of pages generated with `nuxt generate`.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
})
```

Payload extraction also works for routes using ISR (Incremental Static Regeneration) or SWR (Stale-While-Revalidate) caching strategies. This allows CDNs to cache payload files alongside HTML, improving client-side navigation performance for cached routes.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    payloadExtraction: true,
  },
  routeRules: {
    // Payload files will be generated for these cached routes
    '/products/**': { isr: 3600 },
    '/blog/**': { swr: true },
  },
})
```

## clientFallback

Enables the experimental [`<NuxtClientFallback>`](/docs/4.x/api/components/nuxt-client-fallback) component for rendering content on the client if there's an error in SSR.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    clientFallback: true,
  },
})
```

## crossOriginPrefetch

Enables cross-origin prefetch using the Speculation Rules API.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})
```

<read-more to="https://wicg.github.io/nav-speculation/prefetch.html" icon="i-simple-icons-w3c" target="_blank">

Read more about the **Speculation Rules API**.

</read-more>

## viewTransition

Enables View Transition API integration with client-side router.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})
```

<link-example target="_blank" to="https://stackblitz.com/edit/nuxt-view-transitions?file=app.vue">



</link-example>

<read-more to="https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API" icon="i-simple-icons-mdnwebdocs" target="_blank">

Read more about the **View Transition API**.

</read-more>

## writeEarlyHints

Enables writing of early hints when using node server.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    writeEarlyHints: true,
  },
})
```

## componentIslands

Enables experimental component islands support with [`<NuxtIsland>`](/docs/4.x/api/components/nuxt-island) and `.island.vue` files.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    componentIslands: true, // false or 'local+remote'
  },
})
```

<read-more to="/docs/4.x/directory-structure/app/components#server-components">



</read-more>

<read-more to="https://github.com/nuxt/nuxt/issues/19772" icon="i-simple-icons-github" target="_blank">

You can follow the server components roadmap on GitHub.

</read-more>

## localLayerAliases

Resolve `~`, `~~`, `@` and `@@` aliases located within layers with respect to their layer source and root directories.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    localLayerAliases: false,
  },
})
```

## typedPages

Enable the new experimental typed router using [`unplugin-vue-router`](https://github.com/posva/unplugin-vue-router).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    typedPages: true,
  },
})
```

Out of the box, this will enable typed usage of [`navigateTo`](/docs/4.x/api/utils/navigate-to), [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link), [`router.push()`](/docs/4.x/api/composables/use-router) and more.

You can even get typed params within a page by using `const route = useRoute('route-name')`.

<important>

If you use `pnpm` without `shamefully-hoist=true`, you will need to have `unplugin-vue-router` installed as a devDependency in order for this feature to work.

</important>

<video-accordion title="Watch a video from Daniel Roe explaining type-safe routing in Nuxt" video-id="SXk-L19gTZk">



</video-accordion>

## watcher

Set an alternative watcher that will be used as the watching service for Nuxt.

Nuxt uses `chokidar-granular` by default, which will ignore top-level directories
(like `node_modules` and `.git`) that are excluded from watching.

You can set this instead to `parcel` to use `@parcel/watcher`, which may improve
performance in large projects or on Windows platforms.

You can also set this to `chokidar` to watch all files in your source directory.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    watcher: 'chokidar-granular', // 'chokidar' or 'parcel' are also options
  },
})
```

## sharedPrerenderData

Nuxt automatically shares payload *data* between pages that are prerendered. This can result in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and fetch the same data in different pages.

You can disable this feature if needed.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    sharedPrerenderData: false,
  },
})
```

<video-accordion title="Watch a video from Alexander Lichter about the experimental sharedPrerenderData" video-id="1jUupYHVvrU">



</video-accordion>

It is particularly important when enabling this feature to make sure that any unique key of your data
is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch
data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch`
should do this automatically for you.)

```ts
// This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
// to the data fetched, but Nuxt can't know that because it's not reflected in the key.
const route = useRoute()
const { data } = await useAsyncData(async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
// Instead, you should use a key that uniquely identifies the data fetched.
const { data } = await useAsyncData(route.params.slug, async (_nuxtApp, { signal }) => {
  return await $fetch(`/api/my-page/${route.params.slug}`, { signal })
})
```

## clientNodeCompat

With this feature, Nuxt will automatically polyfill Node.js imports in the client build using [`unenv`](https://github.com/unjs/unenv).

<note>

To make globals like `Buffer` work in the browser, you need to manually inject them.

```ts
import { Buffer } from 'node:buffer'

globalThis.Buffer ||= Buffer
```

</note>

## scanPageMeta

Nuxt exposing some route metadata defined in `definePageMeta` at build-time to modules (specifically `alias`, `name`, `path`, `redirect`, `props` and `middleware`).

This only works with static or strings/arrays rather than variables or conditional assignment. See [original issue](https://github.com/nuxt/nuxt/issues/24770) for more information and context.

By default page metadata is only scanned after all routes have been registered in `pages:extend`. Then another hook, `pages:resolved` will be called.

You can disable this feature if it causes issues in your project.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: false,
  },
})
```

## cookieStore

Enables CookieStore support to listen for cookie updates (if supported by the browser) and refresh `useCookie` ref values.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    cookieStore: false,
  },
})
```

<read-more to="https://developer.mozilla.org/en-US/docs/Web/API/CookieStore" icon="i-simple-icons-mdnwebdocs" target="_blank">

Read more about the **CookieStore**.

</read-more>

## buildCache

Caches Nuxt build artifacts based on a hash of the configuration and source files.

This only works for source files within `srcDir` and `serverDir` for the Vue/Nitro parts of your app.

This flag is disabled by default, but you can enable it:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    buildCache: true,
  },
})
```

When enabled, changes to the following files will trigger a full rebuild:

```bash [Directory structure]
.nuxtrc
.npmrc
package.json
package-lock.json
yarn.lock
pnpm-lock.yaml
tsconfig.json
bun.lock
bun.lockb
```

In addition, any changes to files within `srcDir` will trigger a rebuild of the Vue client/server bundle. Nitro will always be rebuilt (though work is in progress to allow Nitro to announce its cacheable artifacts and their hashes).

<note>

A maximum of 10 cache tarballs are kept.

</note>

## checkOutdatedBuildInterval

Set the time interval (in ms) to check for new builds. Disabled when `experimental.appManifest` is `false`.

Set to `false` to disable.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    checkOutdatedBuildInterval: 3600000, // 1 hour, or false to disable
  },
})
```

## extraPageMetaExtractionKeys

The `definePageMeta()` macro is a useful way to collect build-time meta about pages. Nuxt itself provides a set list of supported keys which is used to power some of the internal features such as redirects, page aliases and custom paths.

This option allows passing additional keys to extract from the page metadata when using `scanPageMeta`.

```vue
<script lang="ts" setup>
definePageMeta({
  foo: 'bar',
})
</script>
```

```ts
export default defineNuxtConfig({
  experimental: {
    extraPageMetaExtractionKeys: ['foo'],
  },
  hooks: {
    'pages:resolved' (ctx) {
      // ✅ foo is available
    },
  },
})
```

This allows modules to access additional metadata from the page metadata in the build context. If you are using this within a module, it's recommended also to [augment the `NuxtPage` types with your keys](/docs/4.x/directory-structure/app/pages#typing-custom-metadata).

## navigationRepaint

Wait for a single animation frame before navigation, which gives an opportunity for the browser to repaint, acknowledging user interaction.

It can reduce INP when navigating on prerendered routes.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    navigationRepaint: false,
  },
})
```

## normalizeComponentNames

Nuxt updates auto-generated Vue component names to match the full component name you would use to auto-import the component.

If you encounter issues, you can disable this feature.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    normalizeComponentNames: false,
  },
})
```

By default, if you haven't set it manually, Vue will assign a component name that matches
the filename of the component.

```bash [Directory structure]
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
```

In this case, the component name would be `MyComponent`, as far as Vue is concerned. If you wanted to use `<KeepAlive>` with it, or identify it in the Vue DevTools, you would need to use this component.

But in order to auto-import it, you would need to use `SomeFolderMyComponent`.

By setting `experimental.normalizeComponentNames`, these two values match, and Vue will generate a component name that matches the Nuxt pattern for component naming.

## spaLoadingTemplateLocation

When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/spa-loading-template.html`).

It can be set to `within`, which will render it like this:

```html
<div id="__nuxt">
  <!-- spa loading template -->
</div>
```

Alternatively, you can render the template alongside the Nuxt app root by setting it to `body`:

```html
<div id="__nuxt"></div>
<!-- spa loading template -->
```

This avoids a white flash when hydrating a client-only page.

## browserDevtoolsTiming

Enables performance markers for Nuxt hooks in browser devtools. This adds performance markers that you can track in the Performance tab of Chromium-based browsers, which is useful for debugging and optimizing performance.

This is enabled by default in development mode. If you need to disable this feature, it is possible to do so:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    browserDevtoolsTiming: false,
  },
})
```

<read-more to="https://github.com/nuxt/nuxt/pull/29922" icon="i-simple-icons-github" target="_blank" color="gray">

See PR #29922 for implementation details.

</read-more>

<read-more to="https://developer.chrome.com/docs/devtools/performance/extension#tracks" icon="i-simple-icons-googlechrome" target="_blank" color="gray">

Learn more about Chrome DevTools Performance API.

</read-more>

## debugModuleMutation

Records mutations to `nuxt.options` in module context, helping to debug configuration changes made by modules during the Nuxt initialization phase.

This is enabled by default when `debug` mode is enabled. If you need to disable this feature, it is possible to do so:

To enable it explicitly:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    debugModuleMutation: true,
  },
})
```

<read-more to="https://github.com/nuxt/nuxt/pull/30555" icon="i-simple-icons-github" target="_blank" color="gray">

See PR #30555 for implementation details.

</read-more>

## lazyHydration

This enables hydration strategies for `<Lazy>` components, which improves performance by deferring hydration of components until they're needed.

Lazy hydration is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    lazyHydration: false,
  },
})
```

<read-more to="/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration" icon="i-simple-icons-github" color="gray">

Read more about lazy hydration.

</read-more>

## templateImportResolution

Disable resolving imports into Nuxt templates from the path of the module that added the template.

By default, Nuxt attempts to resolve imports in templates relative to the module that added them. Setting this to `false` disables this behavior, which may be useful if you're experiencing resolution conflicts in certain environments.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    templateImportResolution: false,
  },
})
```

<read-more to="https://github.com/nuxt/nuxt/pull/31175" icon="i-simple-icons-github" target="_blank" color="gray">

See PR #31175 for implementation details.

</read-more>

## templateRouteInjection

By default the route object returned by the auto-imported `useRoute()` composable is kept in sync with the current page in view in `<NuxtPage>`. This is not true for `vue-router`'s exported `useRoute` or for the default `$route` object available in your Vue templates.

By enabling this option a mixin will be injected to keep the `$route` template object in sync with Nuxt's managed `useRoute()`.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    templateRouteInjection: false,
  },
})
```

## decorators

This option enables enabling decorator syntax across your entire Nuxt/Nitro app, powered by [esbuild](https://github.com/evanw/esbuild/releases/tag/v0.21.3).

For a long time, TypeScript has had support for decorators via `compilerOptions.experimentalDecorators`. This implementation predated the TC39 standardization process. Now, decorators are a [Stage 3 Proposal](https://github.com/tc39/proposal-decorators), and supported without special configuration in TS 5.0+ (see [https://github.com/microsoft/TypeScript/pull/52582](https://github.com/microsoft/TypeScript/pull/52582) and [https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#decorators)).

Enabling `experimental.decorators` enables support for the TC39 proposal, **NOT** for TypeScript's previous `compilerOptions.experimentalDecorators` implementation.

<warning>

Note that there may be changes before this finally lands in the JS standard.

</warning>

### Usage

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    decorators: true,
  },
})
```

```ts [app/app.vue]
function something (_method: () => unknown) {
  return () => 'decorated'
}

class SomeClass {
  @something
  public someMethod () {
    return 'initial'
  }
}

const value = new SomeClass().someMethod()
// this will return 'decorated'
```

## defaults

This allows specifying the default options for core Nuxt components and composables.

These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        componentName: 'NuxtLink',
        prefetch: true,
        prefetchOn: {
          visibility: true,
        },
      },
      useAsyncData: {
        deep: true,
      },
    },
  },
})
```

## purgeCachedData

Whether to clean up Nuxt static and asyncData caches on route navigation.

Nuxt will automatically purge cached data from `useAsyncData` and `nuxtApp.static.data`. This helps prevent memory leaks and ensures fresh data is loaded when needed, but it is possible to disable it.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    purgeCachedData: false,
  },
})
```

<read-more to="https://github.com/nuxt/nuxt/pull/31379" icon="i-simple-icons-github" target="_blank" color="gray">

See PR #31379 for implementation details.

</read-more>

## granularCachedData

Whether to call and use the result from `getCachedData` when refreshing data for `useAsyncData` and `useFetch` (whether by `watch`, `refreshNuxtData()`, or a manual `refresh()` call.

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
  },
})
```

<read-more to="https://github.com/nuxt/nuxt/pull/31373" icon="i-simple-icons-github" target="_blank" color="gray">

See PR #31373 for implementation details.

</read-more>

## headNext

Use head optimisations:

- Add the capo.js head plugin in order to render tags in of the head in a more performant way.
- Uses the hash hydration plugin to reduce initial hydration

This flag is enabled by default, but you can disable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    headNext: false,
  },
})
```

## pendingWhenIdle

For `useAsyncData` and `useFetch`, whether `pending` should be `true` when data has not yet started to be fetched.

This flag is disabled by default, but you can enable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: true,
  },
})
```

## entryImportMap

By default, Nuxt improves chunk stability by using an import map to resolve the entry chunk of the bundle.

This injects an import map at the top of your `<head>` tag:

```html
<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>
```

Within the script chunks emitted by Vite, imports will be from `#entry`. This means that changes to the entry will not invalidate chunks which are otherwise unchanged.

<note>

Nuxt smartly disables this feature if you have configured `vite.build.target` to include a browser that doesn't support import maps, or if you have configured `vite.build.rollupOptions.output.entryFileNames` to a value that does not include `[hash]`.

</note>

If you need to disable this feature you can do so:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    entryImportMap: false,
  },
  // or, better, simply tell vite your desired target
  // which nuxt will respect
  vite: {
    build: {
      target: 'safari13',
    },
  },
})
```

## typescriptPlugin

Enable enhanced TypeScript developer experience with the `@dxup/nuxt` module.

This experimental plugin provides improved TypeScript integration and development tooling for better DX when working with TypeScript in Nuxt applications.

This flag is disabled by default, but you can enable this feature:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true,
  },
})
```

<important>

To use this feature, you need to:

- Have `typescript` installed as a dependency
- Configure VS Code to use your workspace TypeScript version (see [VS Code documentation](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript))

</important>

<read-more to="https://github.com/KazariEX/dxup" icon="i-simple-icons-github" target="_blank">

Learn more about **@dxup/nuxt**.

</read-more>

## viteEnvironmentApi

Enable Vite 6's new [Environment API](https://vite.dev/guide/api-environment) for improved build configuration and plugin architecture.

When you set `future.compatibilityVersion` to `5`, this feature is enabled by default. You can also enable it explicitly for testing:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true,
  },
})
```

The Vite Environment API provides better consistency between development and production builds, more granular control over environment-specific configuration, and improved performance.

<important>

Enabling this feature changes how Vite plugins are registered and configured. See the [Vite Environment API migration guide](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for details on updating your plugins.

</important>

<read-more to="https://vite.dev/guide/api-environment" target="_blank">

Learn more about Vite's Environment API.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/features.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/features.md

# Features

> Enable or disable optional Nuxt features to unlock new possibilities.

Some features of Nuxt are available on an opt-in basis, or can be disabled based on your needs.

## `features`

### devLogs

Stream server logs to the client as you are developing. These logs can be handled in the `dev:ssr-logs` hook.

By default, this is enabled in development (when test mode is not active).

If set to `silent`, the logs will not be printed to the browser console.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  features: {
    devLogs: true,
  },
})
```

### inlineStyles

Inlines styles when rendering HTML. This is currently available only when using Vite.

You can also pass a function that receives the path of a Vue component and returns a boolean indicating whether to inline the styles for that component.

It defaults to `(id) => id.includes('.vue')`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  features: {
    inlineStyles: false, // or a function to determine inlining
  },
})
```

### noScripts

Turn off rendering of Nuxt scripts and JavaScript resource hints. Can also be configured granularly within `routeRules`.

You can also disable scripts more granularly within `routeRules`.

If set to 'production' or `true`, JavaScript will be disabled in production mode only. If set to 'all', JavaScript will be disabled in both development and production modes.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  features: {
    noScripts: true, // or 'production' | 'all' | false
  },
})
```

## `future`

There is also a `future` namespace for early opting-in to new features that will become default in a future (possibly major) version of the framework.

### compatibilityVersion

This enables early access to Nuxt features or flags.

Setting `compatibilityVersion` to `5` changes defaults throughout your Nuxt configuration to opt in to Nuxt v5 behaviour, including enabling the [Vite Environment API](/docs/4.x/guide/going-further/experimental-features#viteenvironmentapi).

```ts
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5,
  },
})
```

<read-more to="/docs/4.x/getting-started/upgrade#testing-nuxt-5">

Learn more about testing Nuxt 5.

</read-more>

### multiApp

This enables early access to the experimental multi-app support. You can follow the [tracker issue #21635](https://github.com/nuxt/nuxt/issues/21635) to see the progress of multi-app support in Nuxt.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  future: {
    multiApp: true,
  },
})
```

### typescriptBundlerResolution

This enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and [Vite](https://vite.dev/guide/performance#reduce-resolve-operations).

It improves type support when using modern libraries with `exports`.

See [the original TypeScript pull request](https://github.com/microsoft/TypeScript/pull/51669).

You can set it to false to use the legacy 'Node' mode, which is the default for TypeScript.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  future: {
    typescriptBundlerResolution: false,
  },
})
```

---

# Source: https://nuxt.com/raw/deploy/firebase.md

# Firebase

> Deploy your Nuxt Application to Firebase infrastructure.

## Firebase App Hosting (recommended)

<note>

You will need to be on the [**Blaze plan**](https://firebase.google.com/pricing) (Pay as you go) to get started.

</note>

<read-more to="https://firebase.google.com/docs/app-hosting" title="Firebase App Hosting">



</read-more>

### Project Setup

1. Go to the Firebase [console](https://console.firebase.google.com/) and set up a new project.
2. Select **Build > App Hosting** from the sidebar.

  - You may need to upgrade your billing plan at this step.
3. Click **Get Started**.

  - Choose a region.
  - Import a GitHub repository (you’ll need to link your GitHub account).
  - Configure deployment settings (project root directory and branch), and enable automatic rollouts.
  - Choose a unique ID for your backend.
4. Click Finish & Deploy to create your first rollout.

When you deploy with Firebase App Hosting, the App Hosting preset will be run automatically at build time.

## Firebase Functions (deprecated)

<important>

This deployment method is deprecated and is not recommended. Firebase App Hosting is the recommended way to deploy Nuxt apps on Firebase.

</important>

To use the more recent and recommended generation of Firebase functions, set the `firebase.gen` option to `2`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    firebase: {
      gen: 2
    }
  }
})
```

<note>

If you cannot use configuration for any reason, alternatively you can use `NITRO_FIREBASE_GEN=2` environment variable.

</note>

If you already have a deployed version of your website and want to upgrade to 2nd gen, [see the Migration process on Firebase docs](https://firebase.google.com/docs/functions/2nd-gen-upgrade). Namely, the CLI will ask you to delete your existing functions before deploying the new ones.

<tip target="_blank" to="https://firebase.google.com/docs/functions/version-comparison">

Comparison between 1st and 2nd generation functions

</tip>

## Project Setup

You may instead prefer to set up your project with the Firebase CLI, which will fetch your project ID for you, add required dependencies (see above) and even set up automated deployments via GitHub Actions (for hosting only). [Learn about installing the firebase CLI](https://firebase.google.com/docs/cli#windows-npm).

1. Install the latest version of the Firebase CLI.

```bash [Terminal]
npm install -g firebase-tools@latest
```

1. Initialize your Firebase Project

```bash [Terminal]
firebase login
firebase init hosting
```

<note>

When prompted, you can enter `.output/public` as the public directory. In the next step, **do not** configure your project as a single-page app.

</note>

Once complete, add the following to your `firebase.json` to enable server rendering in Cloud Functions:

```json [firebase.json]
{
  "functions": { "source": ".output/server" },
  "hosting": [
    {
      "site": "<your_project_id>",
      "public": ".output/public",
      "cleanUrls": true,
      "rewrites": [{ "source": "**", "function": "server" }]
    }
  ]
}
```

## Local Preview

You can preview a local version of your site if you need to test things out without deploying.

```bash
npm run build -- --preset=firebase
firebase emulators:start
```

## Build and Deploy

Deploy to Firebase Hosting by running a Nuxt build and then running the `firebase deploy` command.

```bash
npm run build -- --preset=firebase
firebase deploy
```

## Options

You can set options for Firebase functions in your `nuxt.config.ts` file:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    firebase: {
      gen: 2,
      httpsOptions: {
        region: 'europe-west1',
        maxInstances: 3,
      },
    },
  },
});
```

### Runtime Node.js Version

You can set a custom Node.js version in configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    firebase: {
      nodeVersion: '18' // Can be '16' or '18' or '20'
    },
  },
});
```

Firebase tools use the `engines.node` version in  `package.json` to determine which node version to use for your functions. Nuxt automatically writes to the `.output/server/package.json` with configured Node.js version.

You might also need to add a runtime key to your `firebase.json` file:

```json [firebase.json]
{
  "functions": {
    "source": ".output/server",
    "runtime": "nodejs20"
  }
}
```

<read-more to="https://firebase.google.com/docs/functions/manage-functions?gen=2nd#set_nodejs_version" target="_blank">

You can read more about this in **Firebase Docs**.

</read-more>

## Other Cloud Functions

You may be warned that other cloud functions will be deleted when you deploy your Nuxt project. This is because Nitro will deploy your entire project to firebase functions. If you want to deploy only your Nuxt project, you can use the `--only` flag:

```bash
firebase deploy --only functions:server,hosting
```

<read-more to="https://nitro.unjs.io/deploy/providers/firebase" target="_blank">

Head over to the **Nitro documentation** to learn more about the Firebase deployment preset.

</read-more>

## Using Cookies in Production

When using Firebase Hosting together with Cloud Functions or Cloud Run, cookies are generally stripped from incoming requests to allow for efficient CDN cache behavior. Only the specially-named `__session` cookie is permitted to pass through to your app.

<read-more to="https://firebase.google.com/docs/hosting/manage-cache#using_cookies" target="\_blank">

For more information, refer to the **Firebase documentation**.

</read-more>

## Working with Environment Variables

To set environment variables for your Firebase functions, you need to copy the `.env` file to the `.output/server` directory.
You can do this by adding a `postbuild` script to your `package.json`, that will automatically run after the build command:

```json [package.json]
{
  "scripts": {
    "postbuild": "cp .env .output/server/.env"
  }
}
```

<read-more to="https://firebase.google.com/docs/functions/config-env?gen=2nd#env-variables" target="\_blank">

For more information, refer to the **Firebase documentation**.

</read-more>

---

# Source: https://nuxt.com/raw/deploy/flightcontrol.md

# Flightcontrol

> Deploy your Nuxt Application to Flightcontrol infrastructure.

Nitro supports deploying to [AWS via Flightcontrol](https://flightcontrol.dev?ref=nuxt) with minimal configuration.

<tip>

**Zero Configuration ✨**

<br />

Integration with Flightcontrol is possible with zero configuration.

</tip>

## Set Up your Flightcontrol account

On a high level, the steps you will need to follow to deploy a project for the first time are:

1. Create an account at [Flightcontrol](https://app.flightcontrol.dev/signup?ref=nuxt)
2. Create an account at [AWS](https://portal.aws.amazon.com/billing/signup) (if you don't already have one)
3. Link your AWS account to the Flightcontrol
4. Authorize the Flightcontrol GitHub App to access your chosen repositories, public or private.
5. Create a Flightcontrol project with configuration via the Dashboard or with configuration via `flightcontrol.json`.

## Create a Project with Configuration via the Dashboard

1. Create a Flightcontrol project from the Dashboard. Select a repository for the source.
2. Select the `GUI` config type.
3. Select the Nuxt preset.
4. Select your preferred AWS server size.
5. Submit the new project form.

## Create a Project with Configuration via `flightcontrol.json`

1. Create a Flightcontrol project from your dashboard. Select a repository for the source.
2. Select the `flightcontrol.json` config type.
3. Add a new file at the root of your repository called `flightcontrol.json`. Here is an example configuration that creates an AWS fargate service for your app:

```json [flightcontrol.json]
{
  "$schema": "https://app.flightcontrol.dev/schema.json",
  "environments": [
    {
      "id": "production",
      "name": "Production",
      "region": "us-west-2",
      "source": {
        "branch": "main"
      },
      "services": [
        {
          "id": "nitro",
          "buildType": "nixpacks",
          "name": "My Nitro site",
          "type": "fargate",
          "domain": "www.yourdomain.com",
          "outputDirectory": ".output",
          "startCommand": "node .output/server/index.mjs",
          "cpu": 0.25,
          "memory": 0.5
        }
      ]
    }
  ]
}
```

1. Submit the new project form.

<read-more target="_blank" to="https://www.flightcontrol.dev/docs?ref=nuxt">

Learn more about Flightcontrol's configuration.

</read-more>

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/flightcontrol">

Head over **Nitro documentation** to learn more about the flightcontrol deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/community/framework-contribution.md

# Source: https://nuxt.com/raw/docs/4.x/community/framework-contribution.md

# Framework

> Some specific points about contributions to the framework repository.

Once you've read the [general contribution guide](/docs/4.x/community/contribution), here are some specific points to make about contributions to the [`nuxt/nuxt`](https://github.com/nuxt/nuxt) repository.

## Monorepo Guide

- `packages/kit`: Toolkit for authoring Nuxt modules, published as [`@nuxt/kit`](https://www.npmjs.com/package/@nuxt/kit).
- `packages/nuxt`: The core of Nuxt, published as [`nuxt`](https://www.npmjs.com/package/nuxt).
- `packages/schema`: Cross-version Nuxt typedefs and defaults, published as [`@nuxt/schema`](https://www.npmjs.com/package/@nuxt/schema).
- `packages/rspack`: The [Rspack](https://rspack.rs) bundler for Nuxt, published as [`@nuxt/rspack-builder`](https://www.npmjs.com/package/@nuxt/rspack-builder).
- `packages/vite`: The [Vite](https://vite.dev) bundler for Nuxt, published as [`@nuxt/vite-builder`](https://www.npmjs.com/package/@nuxt/vite-builder).
- `packages/webpack`: The [webpack](https://webpack.js.org) bundler for Nuxt, published as [`@nuxt/webpack-builder`](https://www.npmjs.com/package/@nuxt/webpack-builder).

## Setup

To contribute to Nuxt, you need to set up a local environment.

1. [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the [`nuxt/nuxt`](https://github.com/nuxt/nuxt)  repository to your own GitHub account and then [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it to your local device.
2. Ensure using the latest [Node.js](https://nodejs.org/en)
3. Enable [Corepack](https://github.com/nodejs/corepack) to have `pnpm` and `yarn````bash [Terminal]
corepack enable
```
4. Run `pnpm install --frozen-lockfile` to Install the dependencies with pnpm:
```bash [Terminal]
pnpm install --frozen-lockfile
```

<note>

If you are adding a dependency, please use `pnpm add`. <br />


The `pnpm-lock.yaml` file is the source of truth for all Nuxt dependencies.

</note>
5. Activate the passive development system
```bash [Terminal]
pnpm dev:prepare
```
6. Check out a branch where you can work and commit your changes:
```bash [Terminal]
git checkout -b my-new-branch
```

Then, test your changes against the [playground](/docs/4.x/community/framework-contribution#playground) and [test](/docs/4.x/community/framework-contribution#testing) your changes before submitting a pull request.

### Playground

While working on a pull request, you will likely want to check if your changes are working correctly.

You can modify the example app in `playground/`, and run:

```bash [Terminal]
pnpm dev
```

<important>

Please make sure not to commit it to your branch, but it could be helpful to add some example code to your PR description. This can help reviewers and other Nuxt users understand the feature you've built in-depth.

</important>

### Testing

Every new feature should have a corresponding unit test (if possible). The `test/` directory in this repository is currently a work in progress, but do your best to create a new test following the example of what's already there.

Before creating a PR or marking it as ready-to-review, ensure that all tests pass by running:

```bash [Terminal]
pnpm test
```

### Linting

You might have noticed already that we use ESLint to enforce a coding standard.

Before committing your changes, to verify that the code style is correct, run:

```bash [Terminal]
pnpm lint
```

<note>

You can use `pnpm lint --fix` to fix most of the style changes. <br />


If there are still errors left, you must correct them manually.

</note>

### Documentation

If you are adding a new feature or refactoring or changing the behavior of Nuxt in any other manner, you'll likely want to document the changes. Please include any changes to the docs in the same PR. You don't have to write documentation up on the first commit (but please do so as soon as your pull request is mature enough).

<important>

Make sure to make changes according to the [Documentation Style Guide](/docs/4.x/community/contribution#documentation-style-guide).

</important>

### Final Checklist

When submitting your PR, there is a simple template that you have to fill out. Please tick all appropriate "answers" in the checklists.

## Documentation Guide

If you spot an area where we can improve documentation or error messages, please do open a PR - even if it's just to fix a typo!

<important>

Make sure to make changes according to the [Documentation Style Guide](/docs/4.x/community/contribution#documentation-style-guide).

</important>

### Quick Edits

If you spot a typo or want to rephrase a sentence, you can click on the **Edit this page** link located on the right aside in the **Community** section.

Make the change directly in the GitHub interface and open a Pull Request.

### Longer Edits

The documentation content is inside the `docs/` directory of the [nuxt/nuxt](https://github.com/nuxt/nuxt) repository and written in markdown.

<note>

To preview the docs locally, follow the steps on [nuxt/nuxt.com](https://github.com/nuxt/nuxt.com) repository.

</note>

<note>

We recommend that you install the [MDC extension](https://marketplace.visualstudio.com/items?itemName=Nuxt.mdc) for VS Code.

</note>

### Linting Docs

Documentation is linted using [MarkdownLint](https://github.com/DavidAnson/markdownlint) and [case police](https://github.com/antfu/case-police) to keep the documentation cohesive.

```bash [Terminal]
pnpm lint:docs
```

<note>

You can also run `pnpm lint:docs:fix` to highlight and resolve any lint issues.

</note>

### Open a PR

Please make sure your PR title adheres to the [conventional commits](https://www.conventionalcommits.org) guidelines.

```bash [Example of PR title]
docs: update the section about the nuxt.config.ts file
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/generate.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/generate.md

# nuxt generate

> Pre-renders every route of the application and stores the result in plain HTML files.

```bash [Terminal]
npx nuxt generate [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--preset] [--dotenv] [--envName] [-e, --extends=<layer-name>]
```

The `generate` command pre-renders every route of your application and stores the result in plain HTML files that you can deploy on any static hosting services. The command triggers the `nuxt build` command with the `prerender` argument set to `true`

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --preset
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Nitro server preset
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --envName
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The environment to use when resolving configuration overrides (default is <code>
        production
      </code>
      
       when building, and <code>
        development
      </code>
      
       when running the dev server)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
</tbody>
</table>

<read-more to="/docs/4.x/getting-started/deployment#static-hosting">

Read more about pre-rendering and static hosting.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/community/getting-help.md

# Source: https://nuxt.com/raw/docs/4.x/community/getting-help.md

# Getting Help

> We're a friendly community of developers and we'd love to help.

At some point, you may find that there's an issue you need some help with.

But don't worry! We're a friendly community of developers and we'd love to help.

<card-group>
<card icon="i-simple-icons-discord" target="_blank" title="Discord" to="https://go.nuxt.com/discord">

Get real-time help, exchange with the core team and the community, and stay updated on the latest Nuxt news.

</card>

<card icon="i-simple-icons-nuxt" target="_blank" title="Nuxters" to="https://nuxters.nuxt.com">

Connect with other Nuxt enthusiasts.

</card>
</card-group>

## "I can't figure out how to (...)."

You've read through these docs and you think it should be possible, but it's not clear how. The best thing is to [open a GitHub Discussion](https://github.com/nuxt/nuxt/discussions).

Please don't feel embarrassed about asking a question that you think is easy - we've all been there! ❤️

Everyone you'll encounter is helping out because they care, not because they are paid to do so. The kindest thing to do is make it easy for them to help you. Here are some ideas:

- *Explain what your objective is, not just the problem you're facing.* "I need to ensure my form inputs are accessible, so I'm trying to get the ids to match between server and client."
- *Make sure you've first read the docs and used your favorite search engine*. Let people know by saying something like "I've Googled for 'nuxt script setup' but I couldn't find code examples anywhere."
- *Explain what you've tried.* Tell people the kind of solutions you've experimented with, and why. Often this can make people's advice more relevant to your situation.
- *Share your code.* People probably won't be able to help if they just see an error message or a screenshot - but that all changes if you share your code in a copy/pasteable format - preferably in the form of a minimal reproduction like a CodeSandbox.

And finally, just ask the question! There's no need to [ask permission to ask a question](https://dontasktoask.com) or [wait for someone to reply to your 'hello'](https://www.nohello.com). If you do, you might not get a response because people are waiting for the whole question before engaging.

## "Could there be a bug?"

Something isn't working the way that the docs say that it should. You're not sure if it's a bug. You've searched through the [open issues](https://github.com/nuxt/nuxt/issues) and [discussions](https://github.com/nuxt/nuxt/discussions) but you can't find anything. (if there is a closed issue, please create a new one)

We recommend taking a look at [how to report bugs](/docs/4.x/community/reporting-bugs). Nuxt is still in active development, and every issue helps make it better.

## "I need professional help"

If the community couldn't provide the help you need in the time-frame you have, NuxtLabs offers professional support with the [Nuxt Experts](https://nuxt.com/enterprise/support).

The objective of the Nuxt Expert is to provide support to the Vue ecosystem, while also creating freelance opportunities for those contributing to open-source solutions, thus helping to maintain the sustainability of the ecosystem.

The Nuxt experts are Vue, Nuxt and Vite chosen contributors providing professional support and consulting services.

---

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/getting-started.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/getting-started.md

# Create Your First Module

> Learn how to create your first Nuxt module using the official starter template.

## Create a Module

We recommend you get started with Nuxt modules using our [starter template](https://github.com/nuxt/starter/tree/module):

<code-group sync="pm">

```bash [npm]
npm create nuxt -- -t module my-module
```

```bash [yarn]
yarn create nuxt -t module my-module
```

```bash [pnpm]
pnpm create nuxt -t module my-module
```

```bash [bun]
bun create nuxt --template=module my-module
```

</code-group>

This will create a `my-module` project with all the boilerplate necessary to develop and publish your module.

**Next steps:**

1. Open `my-module` in your IDE of choice
2. Install dependencies using your favorite package manager
3. Prepare local files for development using `npm run dev:prepare`
4. Follow this document to learn more about Nuxt modules

## Use the Starter Template

Learn how to perform basic tasks with the module starter.

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/navigating-the-official-starter-template?friend=nuxt">

Watch Vue School video about Nuxt module starter template.

</tip>

### Develop Your Module

While your module source code lives inside the `src` directory, to develop a module you often need a Nuxt application to test it against. That's what the `playground` directory is for. It's a Nuxt application you can tinker with that is already configured to run with your module.

You can interact with the playground like with any Nuxt application.

- Launch its development server with `npm run dev`, it should reload itself as you make changes to your module in the `src` directory
- Build it with `npm run dev:build`

<note>

All other `nuxt` commands can be used against the `playground` directory (e.g. `nuxt <COMMAND> playground`). Feel free to declare additional `dev:*` scripts within your `package.json` referencing them for convenience.

</note>

### Run Tests

The module starter comes with a basic test suite:

- A linter powered by [ESLint](https://eslint.org), run it with `npm run lint`
- A test runner powered by [Vitest](https://vitest.dev), run it with `npm run test` or `npm run test:watch`

<tip>

Feel free to augment this default test strategy to better suit your needs.

</tip>

### Build Your Module

Nuxt modules come with their own builder provided by [`@nuxt/module-builder`](https://github.com/nuxt/module-builder#readme). This builder doesn't require any configuration on your end, supports TypeScript, and makes sure your assets are properly bundled to be distributed to other Nuxt applications.

You can build your module by running `npm run prepack`.

<tip>

While building your module can be useful in some cases, most of the time you won't need to build it on your own: the `playground` takes care of it while developing, and the release script also has you covered when publishing.

</tip>

### Publish to npm

<important>

Before publishing your module to npm, makes sure you have an [npmjs.com](https://www.npmjs.com) account and that you're authenticated to it locally with `npm login`.

</important>

While you can publish your module by bumping its version and using the `npm publish` command, the module starter comes with a release script that helps you make sure you publish a working version of your module to npm and more.

To use the release script, first, commit all your changes (we recommend you follow [Conventional Commits](https://www.conventionalcommits.org) to also take advantage of automatic version bump and changelog update), then run the release script with `npm run release`.

When running the release script, the following will happen:

- First, it will run your test suite by:

  - Running the linter (`npm run lint`)
  - Running unit, integration, and e2e tests (`npm run test`)
  - Building the module (`npm run prepack`)
- Then, if your test suite went well, it will proceed to publish your module by:

  - Bumping your module version and generating a changelog according to your Conventional Commits
  - Publishing the module to npm (for that purpose, the module will be built again to ensure its updated version number is taken into account in the published artifact)
  - Pushing a git tag representing the newly published version to your git remote origin

<tip>

As with other scripts, feel free to fine-tune the default `release` script in your `package.json` to better suit your needs.

</tip>

---

# Source: https://nuxt.com/raw/deploy/github-pages.md

# GitHub Pages

> Deploy your Nuxt Application to GitHub Pages infrastructure.

Nuxt supports deploying to [GitHub Pages](https://pages.github.com/) with minimal configuration.

<caution>

GitHub Pages only support static sites, Nuxt will pre-render your application to static HTML files.

</caution>

<caution>

If you are **not** using a custom domain, you need to set `NUXT_APP_BASE_URL` to your repository-slug for your build step.

**Example**: `https://<user>.github.io/<repository>/`: `NUXT_APP_BASE_URL=/<repository>/ npx nuxt build --preset github_pages`

</caution>

## Setup

Follow the steps to [create a GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site).

## Deployment

Here is an example GitHub Actions workflow to deploy your site to GitHub Pages using the `github_pages` preset:

```yaml [.github/workflows/deploy.yml]
# https://github.com/actions/deploy-pages#usage
name: Deploy to GitHub Pages
on:
  workflow_dispatch:
  push:
    branches:
      - main
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: corepack enable
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      # Pick your own package manager and build script
      - run: npm install
      - run: npx nuxt build --preset github_pages
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./.output/public
  # Deployment job
  deploy:
    # Add a dependency to the build job
    needs: build
    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write      # to deploy to Pages
      id-token: write   # to verify the deployment originates from an appropriate source
    # Deploy to the github_pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    # Specify runner + deployment step
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/github-pages">

Head over **Nitro documentation** to learn more about the github-pages deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/gitignore.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/gitignore.md

# .gitignore

> A .gitignore file specifies intentionally untracked files that git should ignore.

A `.gitignore` file specifies intentionally untracked files that git should ignore.

<read-more icon="i-simple-icons-git" target="_blank" title="the git documentation" to="https://git-scm.com/docs/gitignore">



</read-more>

We recommend having a `.gitignore` file that has **at least** the following entries present:

```bash [.gitignore]
# Nuxt dev/build outputs
.output
.data
.nuxt
.nitro
.cache
dist

# Node dependencies
node_modules

# Logs
logs
*.log

# Misc
.DS_Store

# Local env files
.env
.env.*
!.env.example
```

---

# Source: https://nuxt.com/raw/deploy/gitlab.md

# GitLab Pages

> Deploy your Nuxt Application to GitLab Pages.

Nuxt supports deploying on the [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages) with minimal configuration.

<caution>

GitLab Pages only support static sites, Nuxt will pre-render your application to static HTML files.

</caution>

<caution>

If you are **not** using a custom domain, you need to set `NUXT_APP_BASE_URL` to your repository-slug for your build step.

**Example**: `https://<group/user>.gitlab.io/<repository>/`: `NUXT_APP_BASE_URL=/<repository>/ npm run generate`

</caution>

## Deployment

1. Here is an example GitLab Pages workflow to deploy your site to GitLab Pages:

```yaml [.gitlab-ci.yml]
# Job name has to be `pages`. See https://docs.gitlab.com/ee/user/project/pages/#how-it-works
pages:
   image: node
   before_script:
      - npm ci --cache .npm --prefer-offline
   script:
      # Specify the steps involved to build your app here
      - npm run generate
   cache: # https://docs.gitlab.com/ee/ci/caching/#cache-nodejs-dependencies
      key:
         files:
         - package-lock.json
      paths:
         - .npm/
   artifacts:
      paths:
         # The directory that contains the built files to be published
         - .output/public
   # The directory that contains the built files to be published
   publish: .output/public
   rules:
      # This ensures that only pushes to the default branch 
      # will trigger a pages deploy
      - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
```

## Learn more

<read-more target="_blank" to="https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html#project-website-examples">

Head over **GitLab Pages default domain names and URLs** to learn more about the GitLab Pages default domain names.

</read-more>

---

# Source: https://nuxt.com/raw/blog/going-full-static.md

# Going Full Static

> Long awaited features for JAMstack fans has been shipped in v2.13: full static export, improved smart prefetching, integrated crawler, faster re-deploy, built-in web server and new target option for config ⚡️

## Too long to read

1. Upgrade nuxt to `2.14.0`
2. Set `target: 'static'` in your `nuxt.config.js`
3. Run `nuxt generate`
4. That's it ✨

*Bonus: you can run nuxt start to run a local server serving your generated static application.*

<video :autoplay="true" :controls="true" autoPlay="true" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1588095794/nuxt-full-static_rnnbvm.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1588095794/nuxt-full-static_rnnbvm.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1588095794/nuxt-full-static_rnnbvm.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1588095794/nuxt-full-static_rnnbvm.ogg" type="video/ogg" />
</video>

Note: in this video we are using `nuxt export` which has been deprecated in favor of `nuxt generate`.

## History

Nuxt had the static generation feature with `nuxt generate` since [v0.3.2](https://github.com/nuxt/nuxt.js/releases/tag/v0.3.2) (November 2016), since then we have improved it in multiple ways but never achieved full static generation. Today I am excited to announce that full static export is now possible with Nuxt 2.13.

## Current issues

`nuxt generate` is mostly pre-rendering, when you navigate client-side, `asyncData` and `fetch` are called, *making a request to your API*. A lot of users asked to support a "full static" mode, meaning to not call these 2 hooks on navigation, since the next page has been already pre-rendered.

Also, the developer experience is not optimal:

- You have access to `req` or `res` on SSR but not when running `nuxt generate`
- `process.static` is `true` only when running `nuxt generate`, making it slow to develop Nuxt modules or plugins for static generation
- You have to specify all your [dynamic routes](https://v2.nuxt.com/docs/features/file-system-routing#dynamic-routes) in `generate.routes`, making it harder since you don't have access to nuxt modules there.
- You cannot test the [SPA fallback](https://v2.nuxt.com/docs/concepts/static-site-generation#spa-fallback) in development, the fallback is a client-only version of your Nuxt application that loads when hitting a 404 page
- `nuxt generate` runs `nuxt build` by default, making it slower to generate your website if only your content changed

Note that it was possible to have full static support with [nuxt-payload-extractor](https://github.com/DreaMinder/nuxt-payload-extractor) module but it was more verbose to use and had limitations.

## New config option: `target`

To improve the user experience as well as telling Nuxt that you want to export your application to static hosting, we are introducing a `target` option in your `nuxt.config.js`:

```vue
<script setup>
  import { ref, computed } from '#imports'

  const count = ref(1)
  const double = computed(() => count.value * 2)
</script>
```

<important>

Full static doesn't work with `ssr: 'false'` (which is the same as the deprecated `mode: 'spa'`) as this is used for client-side rendering only (Single Page Applications).

</important>

Running `nuxt dev` with the static target will improve the developer experience:

- Remove `req` & `res` from context
- Fallback to client-side rendering on 404, errors and redirects (see [SPA fallback](https://v2.nuxt.com/docs/concepts/static-site-generation#spa-fallback))
- `$route.query` will always be equal to `{}` on server-side rendering
- `process.static` is `true`

We are also exposing `process.target` for modules author to add logic depending on the user target.

## Smarter `nuxt generate`

Now with `v2.14.0`, you can use `nuxt generate`, it will smartly know if it has to build or not.

### Crazy fast static applications

`nuxt generate` with `target: 'static'` will pre-render all your pages to HTML and save a payload file in order to mock `asyncData` and `fetch` on client-side navigation, this means **no** **more HTTP calls to your API on client-side navigation.** By extracting the page payload to a js file, **it also reduces the HTML size** served as well as preloading it (from the <link />

 in the header) for optimal performance.

We also improved the [smart prefetching](/blog/introducing-smart-prefetching) when doing full static, it will also fetch the payloads, making navigation instant 👀

### Crawler integrated

On top of that, it also has a crawler inside, detecting every relative link and generating it:

If you want to exclude a bunch of routes, use the [generate.exclude](https://v2.nuxt.com/docs/configuration-glossary/configuration-generate#exclude). You can keep using [generate.routes](https://v2.nuxt.com/docs/configuration-glossary/configuration-generate#routes) to add extra routes that the crawler could not detect.

To disable the crawler, set `generate.crawler: false` in your `nuxt.config.js`

### Faster re-deploy

By separating `nuxt build` and `nuxt export`, we are opening a new range of improvements: pre-render your pages only if you content has changed, this means: no webpack build → faster re-deployments.

## Smarter `nuxt start`

Once you statically generated your Nuxt app into `dist/`, use `nuxt start` to start a production HTTP server and serve your static app, supporting [SPA Fallback](https://v2.nuxt.com/docs/concepts/static-site-generation#spa-fallback).

This command is perfect to locally test your static application before pushing to your favorite static hosting provider.

## Preview mode

We do support live preview out of the box to keep calling your API:

```js [plugins/preview.client.js]
export default async function ({ query, enablePreview }) {
  if (query.preview) {
    enablePreview()
  }
}
```

It will automatically refresh the page data (calling `nuxtServerInit`, `asyncData` and `fetch`).

When the preview mode is activated, `asyncData` and `fetch` original methods will be called.

## Commands

Depending of the `target`, you can run these commands.

- `server`
  - `nuxt dev`: Start the development server
  - `nuxt build`: Bundle your Nuxt application for production
  - `nuxt start`: Start the production server
- `static`
  - `nuxt dev`: Start the development server (static aware)
  - `nuxt generate`: Bundle your Nuxt application for production if needed (static aware) and export your application to static HTML in `dist/` directory
  - `nuxt start`: Serve your production application from `dist/`

### What to do next

<read-more target="_blank" to="https://v2.nuxt.com/tutorials/moving-from-nuxtjs-dotenv-to-runtime-config">

Learn more about how to move from `@nuxtjs/dotenv` to runtime config.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide.md

# Source: https://nuxt.com/raw/docs/4.x/guide.md

# Nuxt Guide

> Learn how Nuxt works with in-depth guides.

<card-group className="sm:grid-cols-1">
<card icon="i-lucide-medal" title="Key Concepts" to="/docs/4.x/guide/concepts">

Discover the main concepts behind Nuxt, from auto-import, hybrid rendering to its TypeScript support.

</card>

<card icon="i-lucide-square-check" title="Best Practices" to="/docs/4.x/guide/best-practices">

Learn about best practices when developing with Nuxt.

</card>

<card icon="i-lucide-bot" title="Working with AI" to="/docs/4.x/guide/ai">

Integrate AI tools into your Nuxt workflow with MCP Server and LLMs.txt.

</card>

<card icon="i-lucide-box" title="Module Author Guide" to="/docs/4.x/guide/modules">

Learn how to create Nuxt modules to integrate, enhance or extend any Nuxt application.

</card>

<card icon="i-lucide-book-open" title="Recipes" to="/docs/4.x/guide/recipes">

Find solutions to common problems and learn how to implement them in your Nuxt project.

</card>

<card icon="i-lucide-star" title="Going Further" to="/docs/4.x/guide/going-further">

Master Nuxt with advanced concepts like experimental features, hooks, and more.

</card>
</card-group>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/hello-world.md

# Source: https://nuxt.com/raw/docs/4.x/examples/hello-world.md

# Hello World

> A minimal Nuxt application only requires the `app.vue` and `nuxt.config.js` files.

<read-more to="/docs/getting-started/introduction">



</read-more>

<sandbox branch="main" dir="examples/hello-world" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/deploy/heroku.md

# Heroku

> Deploy your Nuxt Application to Heroku infrastructure.

Nuxt supports deploying on [Heroku](https://heroku.com/) with minimal configuration.

## Using the Heroku CLI

1. Create a new Heroku app.```bash [Terminal]
heroku create myapp
```
2. Configure Heroku to use the nodejs buildpack.```bash [Terminal]
heroku buildpacks:set heroku/nodejs
```
3. Configure your app.```bash [Terminal]
heroku config:set SERVER_PRESET=heroku
```
4. Ensure you have `start` and `build` commands in your `package.json` file.```json [package.json]
{
  "scripts": {
    "build": "nuxt build",
    "start": "node .output/server/index.mjs"
  }
}
```

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/heroku">

Head over **Nitro documentation** to learn more about the Heroku deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/advanced/hooks.md

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/hooks.md

# Source: https://nuxt.com/raw/docs/4.x/api/advanced/hooks.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/hooks.md

# Lifecycle Hooks

> Nuxt provides a powerful hooking system to expand almost every aspect using hooks.

<tip>

The hooking system is powered by [unjs/hookable](https://github.com/unjs/hookable).

</tip>

## Nuxt Hooks (Build Time)

These hooks are available for [Nuxt modules](/docs/4.x/guide/modules) and build context.

### Within `nuxt.config.ts`

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  hooks: {
    close: () => { },
  },
})
```

### Within Nuxt Modules

```js
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async () => { })
  },
})
```

<read-more to="/docs/4.x/api/advanced/hooks#nuxt-hooks-build-time">

Explore all available Nuxt hooks.

</read-more>

## App Hooks (Runtime)

App hooks can be mainly used by [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) to hook into rendering lifecycle but could also be used in Vue composables.

```ts [app/plugins/test.ts]
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:start', () => {
    /* your code goes here */
  })
})
```

<read-more to="/docs/4.x/api/advanced/hooks#app-hooks-runtime">

Explore all available App hooks.

</read-more>

## Server Hooks (Runtime)

These hooks are available for [server plugins](/docs/4.x/directory-structure/server#server-plugins) to hook into Nitro's runtime behavior.

```ts [~/server/plugins/test.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', (html, { event }) => {
    console.log('render:html', html)
    html.bodyAppend.push('<hr>Appended by custom plugin')
  })

  nitroApp.hooks.hook('render:response', (response, { event }) => {
    console.log('render:response', response)
  })
})
```

<read-more to="/docs/4.x/api/advanced/hooks#nitro-app-hooks-runtime-server-side">

Learn more about available Nitro lifecycle hooks.

</read-more>

## Adding Custom Hooks

You can define your own custom hooks support by extending Nuxt's hook interfaces.

```ts
import type { HookResult } from '@nuxt/schema'

declare module '#app' {
  interface RuntimeNuxtHooks {
    'your-nuxt-runtime-hook': () => HookResult
  }
  interface NuxtHooks {
    'your-nuxt-hook': () => HookResult
  }
}

declare module 'nitropack/types' {
  interface NitroRuntimeHooks {
    'your-nitro-hook': () => void
  }
}
```

---

# Source: https://nuxt.com/raw/docs/3.x/guide/best-practices/hydration.md

# Source: https://nuxt.com/raw/docs/4.x/guide/best-practices/hydration.md

# Nuxt and hydration

> Why fixing hydration issues is important

When developing, you may face hydration issues. Don't ignore those warnings.

# Why is it important to fix them?

Hydration mismatches are not just warnings - they are indicators of serious problems that can break your application:

## Performance Impact

- **Increased time to interactive**: Hydration errors force Vue to re-render the entire component tree, which will increase the time for your Nuxt app to become interactive
- **Poor user experience**: Users may see content flashing or unexpected layout shifts

## Functionality Issues

- **Broken interactivity**: Event listeners may not attach properly, leaving buttons and forms non-functional
- **State inconsistencies**: Application state can become out of sync between what the user sees and what the application thinks is rendered
- **SEO problems**: Search engines may index different content than what users actually see

# How to detect them

## Development Console Warnings

Vue will log hydration mismatch warnings in the browser console during development:

![Screenshot of Vue hydration mismatch warning in the browser console](/assets/docs/best-practices/vue-console-hydration.png)

# Common reasons

## Browser-only APIs in Server Context

**Problem**: Using browser-specific APIs during server-side rendering.

```html
<template>
  <div>User preference: {{ userTheme }}</div>
</template>

<script setup>
// This will cause hydration mismatch!
// localStorage doesn't exist on the server!
const userTheme = localStorage.getItem('theme') || 'light'
</script>
```

**Solution**: You can use [`useCookie`](/docs/4.x/api/composables/use-cookie):

```html
<template>
  <div>User preference: {{ userTheme }}</div>
</template>

<script setup>
// This works on both server and client
const userTheme = useCookie('theme', { default: () => 'light' })
</script>
```

## Inconsistent Data

**Problem**: Different data between server and client.

```html
<template>
  <div>{{ Math.random() }}</div>
</template>
```

**Solution**: Use SSR-friendly state:

```html
<template>
  <div>{{ state }}</div>
</template>

<script setup>
const state = useState('random', () => Math.random())
</script>
```

## Conditional Rendering Based on Client State

**Problem**: Using client-only conditions during SSR.

```html
<template>
  <div v-if="window?.innerWidth > 768">
    Desktop content
  </div>
</template>
```

**Solution**: Use media queries or handle it client-side:

```html
<template>
  <div class="responsive-content">
    <div class="hidden md:block">Desktop content</div>
    <div class="md:hidden">Mobile content</div>
  </div>
</template>
```

## Third-party Libraries with Side Effects

**Problem**: Libraries that modify the DOM or have browser dependencies (this happens a LOT with tag managers).

```html
<script setup>
if (import.meta.client) {
    const { default: SomeBrowserLibrary } = await import('browser-only-lib')
    SomeBrowserLibrary.init()
}
</script>
```

**Solution**: Initialise libraries after hydration has completed:

```html
<script setup>
onMounted(async () => {
  const { default: SomeBrowserLibrary } = await import('browser-only-lib')
  SomeBrowserLibrary.init()
})
</script>
```

## Dynamic Content Based on Time

**Problem**: Content that changes based on current time.

```html
<template>
  <div>{{ greeting }}</div>
</template>

<script setup>
const hour = new Date().getHours()
const greeting = hour < 12 ? 'Good morning' : 'Good afternoon'
</script>
```

**Solution**: Use [`NuxtTime`](/docs/4.x/api/components/nuxt-time) component or handle it client-side:

```html
<template>
  <div>
    <NuxtTime :date="new Date()" format="HH:mm" />
  </div>
</template>
```

```html
<template>
  <div>
    <ClientOnly>
      {{ greeting }}
      <template #fallback>
        Hello!
      </template>
    </ClientOnly>
  </div>
</template>

<script setup>
const greeting = ref('Hello!')

onMounted(() => {
  const hour = new Date().getHours()
  greeting.value = hour < 12 ? 'Good morning' : 'Good afternoon'
})
</script>
```

## In summary

1. **Use SSR-friendly composables**: [`useFetch`](/docs/4.x/api/composables/use-fetch), [`useAsyncData`](/docs/4.x/api/composables/use-async-data), [`useState`](/docs/4.x/api/composables/use-state)
2. **Wrap client-only code**: Use [`ClientOnly`](/docs/4.x/api/components/client-only) component for browser-specific content
3. **Consistent data sources**: Ensure server and client uses the same data
4. **Avoid side effects in setup**: Move browser-dependent code to `onMounted`

<tip>

You can read the [Vue documentation on SSR hydration mismatch](https://vuejs.org/guide/scaling-up/ssr#hydration-mismatch) for a better understanding of hydration.

</tip>

---

# Source: https://nuxt.com/raw/deploy/iis.md

# IIS

> Deploy your Nuxt Application to IIS infrastructure.

## Using IISnode

1. Install the latest LTS version of [Node.js](https://nodejs.org/en/) on your Windows Server.
2. Install [IISnode](https://github.com/azure/iisnode/releases)
3. Install [IIS `URLRewrite` Module](https://www.iis.net/downloads/microsoft/url-rewrite).
4. In IIS, add `.mjs` as a new mime type and set its content type to `application/javascript`.
5. Build you application with the following command:
```bash [Terminal]
npx nuxi build --preset=iis_node
```
6. Deploy the contents of your `.output` folder to your website in IIS.

## More options

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/iis">

Head over **Nitro documentation** to learn more about the IIS deployment presets.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/advanced/import-meta.md

# Source: https://nuxt.com/raw/docs/4.x/api/advanced/import-meta.md

# Import meta

> Understand where your code is running using `import.meta`.

## The `import.meta` object

With ES modules you can obtain some metadata from the code that imports or compiles your ES-module.
This is done through `import.meta`, which is an object that provides your code with this information.
Throughout the Nuxt documentation you may see snippets that use this already to figure out whether the
code is currently running on the client or server side.

<read-more to="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta">

Read more about `import.meta`.

</read-more>

## Runtime (App) Properties

These values are statically injected and can be used for tree-shaking your runtime code.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        import.meta.client
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when evaluated on the client side.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.browser
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when evaluated on the client side.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.server
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when evaluated on the server side.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.nitro
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when evaluated on the server side.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.dev
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when running the Nuxt dev server.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.test
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when running in a test context.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.prerender
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      True when rendering HTML on the server in the prerender stage of your build.
    </td>
  </tr>
</tbody>
</table>

## Builder Properties

These values are available both in modules and in your `nuxt.config`.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        import.meta.env
      </code>
    </td>
    
    <td>
      object
    </td>
    
    <td>
      Equals <code>
        process.env
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import.meta.url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Resolvable path for the current file.
    </td>
  </tr>
</tbody>
</table>

## Examples

### Using `import.meta.url` to resolve files within modules

```ts [modules/my-module/index.ts]
import { createResolver } from 'nuxt/kit'

// Resolve relative from the current file
const resolver = createResolver(import.meta.url)

export default defineNuxtModule({
  meta: { name: 'myModule' },
  setup () {
    addComponent({
      name: 'MyModuleComponent',
      // Resolves to '/modules/my-module/components/MyModuleComponent.vue'
      filePath: resolver.resolve('./components/MyModuleComponent.vue'),
    })
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/info.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/info.md

# nuxt info

> The info command logs information about the current or specified Nuxt project.

```bash [Terminal]
npx nuxt info [ROOTDIR] [--cwd=<directory>]
```

The `info` command logs information about the current or specified Nuxt project.

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/init.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/init.md

# create nuxt

> The init command initializes a fresh Nuxt project.

```bash [Terminal]
npm create nuxt@latest [DIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager] [-M, --modules] [--no-modules] [--nightly]
```

The `create-nuxt` command initializes a fresh Nuxt project using [unjs/giget](https://github.com/unjs/giget).

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        DIR=""
      </code>
    </td>
    
    <td>
      Project directory
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      <code>
        .
      </code>
    </td>
    
    <td>
      Specify the working directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -t, --template
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Template name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -f, --force
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Override existing directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --offline
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Force offline mode
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --preferOffline
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Prefer offline mode
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --no-install
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Skip installing dependencies
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --gitInit
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Initialize git repository
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --shell
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Start shell after installation in project directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --packageManager
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Package manager choice (npm, pnpm, yarn, bun)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -M, --modules
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Nuxt modules to install (comma separated without spaces)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --no-modules
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Skip module installation prompt
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --nightly
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Use Nuxt nightly release channel (3x or latest)
    </td>
  </tr>
</tbody>
</table>

## Environment variables

- `NUXI_INIT_REGISTRY`: Set to a custom template registry. ([learn more](https://github.com/unjs/giget#custom-registry)).

  - Default registry is loaded from [nuxt/starter/templates](https://github.com/nuxt/starter/tree/templates/templates)

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/installation.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/installation.md

# Installation

> Get started with Nuxt quickly with our online starters or start locally with your terminal.

## Play Online

If you just want to play around with Nuxt in your browser without setting up a project, you can use one of our online sandboxes:

<card-group>
<card icon="i-simple-icons-stackblitz" target="_blank" title="Open on StackBlitz" to="https://nuxt.new/s/v4">



</card>

<card icon="i-simple-icons-codesandbox" target="_blank" title="Open on CodeSandbox" to="https://nuxt.new/c/v4">



</card>
</card-group>

Or follow the steps below to set up a new Nuxt project on your computer.

## New Project

### Prerequisites

- **Node.js** - [`20.x`](https://nodejs.org/en) or newer (but we recommend the [active LTS release](https://github.com/nodejs/release#release-schedule))
- **Text editor** - There is no IDE requirement, but we recommend [Visual Studio Code](https://code.visualstudio.com/) with the [official Vue extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (previously known as Volar) or [WebStorm](https://www.jetbrains.com/webstorm/), which, along with [other JetBrains IDEs](https://www.jetbrains.com/ides/), offers great Nuxt support right out-of-the-box.
- **Terminal** - In order to run Nuxt commands

<note>
<details>
<summary>

Additional notes for an optimal setup:

</summary>

- **Node.js**: Make sure to use an even numbered version (20, 22, etc.)
- **WSL**: If you are using Windows and experience slow HMR, you may want to try using [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install) which may solve some performance issues.
- **Windows slow DNS resolution**: Instead of using `localhost:3000` for local dev server on Windows, use `127.0.0.1` for much faster loading experience on browsers.

</details>
</note>

Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.com), you can open an [integrated terminal](https://code.visualstudio.com/docs/terminal/basics)) and use the following command to create a new starter project:

<code-group sync="pm">

```bash [npm]
npm create nuxt@latest <project-name>
```

```bash [yarn]
yarn create nuxt <project-name>
```

```bash [pnpm]
pnpm create nuxt@latest <project-name>
```

```bash [bun]
bun create nuxt@latest <project-name>
```

```bash [deno]
deno -A npm:create-nuxt@latest <project-name>
```

</code-group>

<tip>

Alternatively, you can find other starters or themes by opening [nuxt.new](https://nuxt.new) and following the instructions there.

</tip>

Open your project folder in Visual Studio Code:

```bash [Terminal]
code <project-name>
```

Or change directory into your new project from your terminal:

```bash
cd <project-name>
```

## Development Server

Now you'll be able to start your Nuxt app in development mode:

<code-group sync="pm">

```bash [npm]
npm run dev -- -o
```

```bash [yarn]
yarn dev --open
```

```bash [pnpm]
pnpm dev -o
```

```bash [bun]
bun run dev -o

# To use the Bun runtime during development
# bun --bun run dev -o
```

```bash [deno]
deno run dev -o
```

</code-group>

<tip icon="i-lucide-circle-check">

Well done! A browser window should automatically open for [http://localhost:3000](http://localhost:3000).

</tip>

## Next Steps

Now that you've created your Nuxt project, you are ready to start building your application.

<read-more title="Nuxt Concepts" to="/docs/4.x/guide/concepts">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/internals.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/internals.md

# How Nuxt Works?

> Nuxt is a minimal but highly customizable framework to build web applications.

This guide helps you better understand Nuxt internals to develop new solutions and module integrations on top of Nuxt.

## The Nuxt Interface

When you start Nuxt in development mode with [`nuxt dev`](/docs/4.x/api/commands/dev) or building a production application with [`nuxt build`](/docs/4.x/api/commands/build),
a common context will be created, referred to as `nuxt` internally. It holds normalized options merged with `nuxt.config` file,
some internal state, and a powerful [hooking system](/docs/4.x/api/advanced/hooks) powered by [unjs/hookable](https://github.com/unjs/hookable)
allowing different components to communicate with each other. You can think of it as **Builder Core**.

This context is globally available to be used with [Nuxt Kit](/docs/4.x/guide/going-further/kit) composables.
Therefore only one instance of Nuxt is allowed to run per process.

To extend the Nuxt interface and hook into different stages of the build process, we can use [Nuxt modules](/docs/4.x/guide/modules).

For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/core/nuxt.ts).

## The NuxtApp Interface

When rendering a page in the browser or on the server, a shared context will be created, referred to as `nuxtApp`.
This context keeps vue instance, runtime hooks, and internal states like ssrContext and payload for hydration.
You can think of it as **Runtime Core**.

This context can be accessed using [`useNuxtApp()`](/docs/4.x/api/composables/use-nuxt-app) composable within Nuxt plugins and `<script setup>` and vue composables.
Global usage is possible for the browser but not on the server, to avoid sharing context between users.

Since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception if context is currently unavailable, if your composable does not always require `nuxtApp`, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead, which will return `null` instead of throwing an exception.

To extend the `nuxtApp` interface and hook into different stages or access contexts, we can use [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins).

Check [Nuxt App](/docs/4.x/api/composables/use-nuxt-app) for more information about this interface.

`nuxtApp` has the following properties:

```ts
interface NuxtApp {
  vueApp // the global Vue application: https://vuejs.org/api/application.html#application-api

  versions // an object containing Nuxt and Vue versions

  // These let you call and add runtime NuxtApp hooks
  // https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts#L18
  hooks
  hook
  callHook

  // Only accessible on server-side
  ssrContext: {
    url
    req
    res
    runtimeConfig
    noSSR
  }

  // This will be stringified and passed from server to client
  payload: {
    serverRendered: true
    data: {}
    state: {}
  }

  provide: (name: string, value: any) => void
}
```

For more details, check out [the source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/nuxt.ts).

## Runtime Context vs. Build Context

Nuxt builds and bundles project using Node.js but also has a runtime side.

While both areas can be extended, that runtime context is isolated from build-time. Therefore, they are not supposed to share state, code, or context other than runtime configuration!

`nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules) can be used to extend the build context, and [Nuxt Plugins](/docs/4.x/directory-structure/app/plugins) can be used to extend runtime.

When building an application for production, `nuxt build` will generate a standalone build in the `.output` directory, independent of `nuxt.config` and [Nuxt modules](/docs/4.x/guide/modules).

---

# Source: https://nuxt.com/raw/blog/introducing-nuxt-devtools.md

# Introducing Nuxt DevTools

> Unleash the Developer Experience with Nuxt and understand your app better than ever.

We announced the preview of [Nuxt DevTools](https://github.com/nuxt/devtools) on [Vue Amsterdam 2023](https://vuejs.amsterdam/), a new tool to help you understand your Nuxt app and improve the developer experience even further. Today we released a new minor version [`v0.3.0`](https://github.com/nuxt/devtools/releases/tag/v0.3.0) with a bunch of updates and improvements.

![devtools-tab-overview](/assets/blog/devtools/tab-overview.png)

In this post, we will explore the reasons behind the creation of Nuxt DevTools, how it can enhance your development experience, and what you can expect in the future.

## Developer Experience

Over the recent years, there has been an increasing focus on Developer Experience (DX). Tools and frameworks have been striving to improve the DX. Along the way, Nuxt introduced many innovative features and conventions to make your day-to-day development easier and more efficient.

In Nuxt 3, we switched to [Vite](https://vitejs.dev/) as the default bundler for the instant hot module replacement (HMR) during developement, creating a faster feedback loop to your workflow. Additionally, we have introduced [Nitro](https://github.com/unjs/nitro), a new server engine that allows you to deploy your Nuxt app to any hosting service, such as [Vercel](https://vercel.com), [Netlify](https://netlify.com), [Cloudflare](https://cloudflare.com) and [more](https://nitro.unjs.io/deploy) **with zero-config**.

Nuxt offers many common practices built-in:

- Write TypeScript and ESM out-of-the-box throughout your codebase.
- Build single-page applications (SPA), server-side rendering (SSR), static site generation (SSG), or [hybrid them **per routes**](/docs/guide/concepts/rendering#route-rules) - using the same codebase isomorphically without any explicit setup.
- Use several composables, like [`useState`](/docs/api/composables/use-state) and [`useAsyncData`](/docs/api/composables/use-async-data) for sharing states accessible across the server and client sides.
- Leverage SEO utilities, like [`useHead`](/docs/api/composables/use-head) and [`useSeoMeta`](/docs/getting-started/seo-meta#useseometa) to make meta-tags management a breaze.

Moreover, features such as the [layout system](/docs/guide/directory-structure/layouts), [plugins](/docs/guide/directory-structure/plugins), route [middleware](/docs/guide/directory-structure/middleware), and other tools make app creation easier and codebases more organized.

Conventions like [file-based routing](/docs/guide/directory-structure/pages) and [file-based server APIs](https://nitro.unjs.io/guide/introduction/routing) making the routing intuitive and effortless.

[Components auto-imports](/docs/guide/directory-structure/components) makes it easy to create shared components that are directly available in any Vue file. Unlike global components, they are code-splitted. We also introduced [composables auto-import](/docs/guide/concepts/auto-imports), where all APIs from Vue are directly available. Nuxt modules can also provide their custom composables to be auto-imported, as well as your [local composables](/docs/guide/directory-structure/composables).

Recently, we introduced client and server-only components, which can be used by adding `.client` and `.server` to the filename. All these conventions are fully typed and developers can even have type autocomplete when doing route navigation or fetching data from APIs. **These conventions significantly reduce boilerplate code, avoid duplications, and improve productivity.**

When it comes to ecosystem, Nuxt has a large community of developers building modules around it, [with hundreds of high-quality modules](/modules) available. Modules allow developers to get integrations for features they want without worrying about configuration or best practices.

## The Problem

Nuxt is capable of creating a large scale application at ease, however there is one problem: **the lack of transparency**.

For every new feature and convention we introduce, we are adding a bit more abstraction to the framework.

Abstractions are great things to transfer implementation complexity and make things easier to get more focus when building. On the other hand, they can also add extra burden for users to learn and understand what's going on under the hood. Leading also to implicitness, like where a auto-imported component is from, or how many modules is using a certain component, etc. It can also make things hard to debug.

This might be considered as a trade-off of any tools, you have to learn and understand the tool to use it with efficiency. Despite improving the documentation and providing more examples, **we believe of an opportunity to improve the lack of transparency**.

## Introducing Nuxt DevTools

[Nuxt DevTools](https://github.com/nuxt/devtools) is a visual tool to help you understand your Nuxt app and improve the developer experience even further. It's created to provide a better transparency of Nuxt and your app, find performance bottlenecks and help you manage your app and configuration.

It is shipped as an experimental module and provide the views right inside your app. Once installed, it will add a small icon on the bottom of your app. Clicking it will open the DevTools panel.

To try it, please refer to the [installation guide](https://devtools.nuxtjs.org/guide).

### Overview

Shows a quick overview of your app, including the Nuxt version, pages, components, modules, and plugins you are using. **It also check your Nuxt version and allow you to upgrade with a single click.**

<video :autoplay="true" :controls="true" autoPlay="true" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1679922926/nuxt3/nuxt-devtools-upgrade_dnfghq.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1679922926/nuxt3/nuxt-devtools-upgrade_dnfghq.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1679922926/nuxt3/nuxt-devtools-upgrade_dnfghq.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1679922926/nuxt3/nuxt-devtools-upgrade_dnfghq.ogg" type="video/ogg" />
</video>

### Pages

The pages tab shows your current routes and provide a quick way to navigate to them. For dynamic routes, it also provide a form to fill with each params interactively. You can also use the textbox to play and test how each route is matched.

<video :autoplay="true" :controls="true" autoPlay="true" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1679923373/nuxt3/nuxt-devtools-pages_csjoh0.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1679923373/nuxt3/nuxt-devtools-pages_csjoh0.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1679923373/nuxt3/nuxt-devtools-pages_csjoh0.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1679923373/nuxt3/nuxt-devtools-pages_csjoh0.ogg" type="video/ogg" />
</video>

### Components

Components tab show all the components you are using in your app and where they are from. You can also search for them and go to the source code.

![nuxt-devtools-tab-components](/assets/blog/devtools/tab-components.png)

It also provides a graph view that show the relationship between components. You can filter the components to see the dependencies of a specific component. This could help to identify unintended dependencies and improve the performance and bundle size of pages.

![nuxt-devtools-components-graph](/assets/blog/devtools/tab-components-graph-all.png)

![nuxt-devtools-components-graph-filtered](/assets/blog/devtools/tab-components-graph-filtered.png)

You can also use the "Inspector" feature to inspect the DOM tree and see which component is rendering it. Click to go to your editor of the specific line. Making it much easier to make changes, without the requirement of understanding the project structure thoroughly.

![nuxt-devtools-tab-components-inspector](/assets/blog/devtools/tab-components-inspector.png)

### Imports

Imports tab shows all the auto-imports registered to Nuxt. You can see which files are importing them, and where they are from. Some entries can also provide short descriptions and documentation links.

![nuxt-devtools-tab-imports](/assets/blog/devtools/tab-imports.png)

### Modules

Modules tab shows all the modules you have installed and providing the links to their documentation and source code. You can find more modules available in [Nuxt Modules](/modules).

![nuxt-devtools-tab-modules](/assets/blog/devtools/tab-modules.png)

Recently we introduce the experimental upgrade feature, which allows you to upgrade your Nuxt or modules with ease. With the [Terminal tab](#terminals), it shows the output of the upgrade process transparently.

![nuxt-devtools-tab-modules-upgrade](/assets/blog/devtools/tab-modules-upgrade.png)

### Assets

The assets tab that shows all your static assets and their information. You can copy the paths of the assets, or the code snippets of using them. In the future, with the integrations of [Nuxt Image](https://image.nuxtjs.org/), you can even optimize images with a single click.

![nuxt-devtools-tab-assets](/assets/blog/devtools/tab-assets.png)

### Plugins

Plugins tab shows all the plugins you are using in your app. As plugins runs before the app is mounted,the time spent in each plugin should be minimal to avoid blocking the app from rendering. The time cost of each plugin provided can be helpful to find performance bottlenecks.

![nuxt-devtools-tab-plugins](/assets/blog/devtools/tab-plugins.png)

### Hooks

Hooks tab can help you to monitor the time spent in each hook from both client and server side. You can also see how many lisenters registed to each hook, and how many times they have been invoked. This can be helpful to find performance bottlenecks.

![nuxt-devtools-tab-hooks](/assets/blog/devtools/tab-hooks.png)

### App Config

You can inspect and modify the app config in DevTools, try different configurations and see the effects immediately.

![nuxt-devtools-app-config](/assets/blog/devtools/tab-app-config.png)

### Payload & Data

This tab shows the state created by [`useState`](/docs/api/composables/use-state), [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch). It can be helpful to understand how the data is fetched and how the state is managed, or change them reactively to see it they affects your app. For `useAsyncData` and `useFetch`, you can also manually the trigger the refetch.

![nuxt-devtools-tab-payload](/assets/blog/devtools/tab-payload.png)

### Terminals

In some integrations, they might require to have subprocesses running to do certain jobs. Before DevTools, you either hide the output of the subprocess entirely and swallow the potential warnings/errors, or pipe to stdout and pollute your terminal with multiple outputs. Now you can now have the outputs in DevTools for each process and clearly isolated.

![nuxt-devtools-tab-terminals](/assets/blog/devtools/tab-terminals.png)

### Virtual Files

Virtual Files tab shows the virtual files generated by Nuxt and Nitro to support the conventions. This can be helpful for advanced debugging.

![nuxt-devtools-tab-virtual-files](/assets/blog/devtools/tab-virtual-files.png)

### Inspect

Inspect expose the [`vite-plugin-inspect`](https://github.com/antfu/vite-plugin-inspect) integration, allowing you to inspect transformation steps of Vite. It can be helpful to understand how each plugin is transforming your code and spot potential issues.

![nuxt-devtools-vite-plugin-inspect](/assets/blog/devtools/tab-inspect.png)

### VS Code

Thanks to [VS Code Server](https://code.visualstudio.com/docs/remote/vscode-server), we are able to integrate a **full-featured** VS Code instance into DevTools. You can install extensions and sync your settings. This allows you to get closer feedback loop where you can change the code and see the result immediately without leaving the browser.

![nuxt-devtools-tab-vscode](/assets/blog/devtools/tab-vscode.png)

### Module Contributed View

With the ecosystem in mind, Nuxt DevTools to designed to be flexible and extendable. Modules could contribute their own views to DevTools, to provide interactive data and playgrounds for their integrations. The following are a few examples:

[VueUse module](/modules/vueuse) provides a search page for available composables and see their documentation.

![nuxt-devtools-tab-vueuse](/assets/blog/devtools/tab-vueuse.png)

[UnoCSS module](/modules/unocss) provides an interactive inspector to see how each module contributes to the final CSS.

![nuxt-devtools-tab-unocss](/assets/blog/devtools/tab-unocss.png)

[Nuxt Icon module](/modules/icon) provides a search engine for all icons available.

![nuxt-devtools-tab-nuxt-icon](/assets/blog/devtools/tab-icones.png)

[Nuxt Vitest module](https://nuxt.com/modules/vitest) provides Vitest UI for tests runing with the same pipeline as your Nuxt app.

![nuxt-devtools-tab-vitest](/assets/blog/devtools/tab-vitest.png)

### For Module Authors

With the release of `v0.3.0`, we improved the ability for module authors to contribute to the DevTools.

It includes:

- Module contributed views
- Access to client app's context and devtools' utils
- Custom RPC functions to communicate between server and client
- Subprocesses spawning and output steaming
- [`@nuxt/devtools-kit`](https://devtools.nuxtjs.org/module/utils-kit) - a set of utilities help you integrate your module with DevTools
- [`@nuxt/devtools-ui-kit`](https://devtools.nuxtjs.org/module/ui-kit) - the UI components used in DevTools, to make your module's view consistent with the rest of DevTools
- Starter template to create module with DevTools integration

Please check out the [Devtools Module Authors Guide](https://devtools.nuxtjs.org/module/guide) to learn more.

## What to Expect Next?

This is just the beginning of the journey. We are planning to add more features to DevTools, while exploring the ways to present the data in more intuitive and playful ways.

The goals of Nuxt DevTools are to:

- <icon className="size-5" name="lucide:blend">



</icon>

 Improve transparency for conventions
- <icon className="size-5" name="lucide:gauge">



</icon>

 Inspecting performance & analysis
- <icon className="size-5" name="lucide:swatch-book">



</icon>

 Interactive & playful
- <icon className="size-5" name="lucide:file-pen-line">



</icon>

 Personalized documentations
- <icon className="size-5" name="lucide:blocks">



</icon>

 Manage and scaffold apps with ease
- <icon className="size-5" name="lucide:lightbulb">



</icon>

 Provide insights and improvements
- <icon className="size-5" name="lucide:user-check">



</icon>

 Make the development experience more enjoyable

---

You can check our [Project Roadmap](https://github.com/nuxt/devtools/discussions/31) and share your [Ideas & Suggestions](https://github.com/nuxt/devtools/discussions/29), helping us to make the DevTools better.

You can follow the latest updates by staring the [GitHub repository](https://github.com/nuxt/devtools), and following [Nuxt's official Twitter](https://x.com/nuxt_js).

Thank you for reading, and we are looking forward to your feedback and contributions!

---

# Source: https://nuxt.com/raw/blog/introducing-smart-prefetching.md

# Introducing Smart Prefetching

> Starting from Nuxt v2.4.0, Nuxt will automagically prefetch the code-splitted pages linked with a nuxt-link when visible in the viewport by default.

## Introducing Smart prefetching ⚡️

Starting from [Nuxt v2.4.0](https://github.com/nuxt/nuxt.js/releases/tag/v2.4.0), Nuxt will automagically prefetch the code-splitted pages linked with `<nuxt-link>` when visible in the viewport **by default**. This hugely improves the end user performances, inspired by [quicklink](https://github.com/GoogleChromeLabs/quicklink).

![nuxt-prefetch-comparison](/assets/blog/nuxt-prefetch-comparison.gif)

Demos are online and we recommend you to try it out to feel the difference:

- No prefetching (v2.3): [https://nuxt-no-prefetch.surge.sh](https://nuxt-no-prefetch.surge.sh)
- With prefetching (v2.4): [https://nuxt-prefetch.surge.sh](https://nuxt-prefetch.surge.sh)

You can learn more about this feature in the [`<nuxt-link>`](https://v2.nuxt.com/docs/features/nuxt-components#the-nuxtlink-component) section of the documentation.

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/introduction.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/introduction.md

# Introduction

> Nuxt's goal is to make web development intuitive and performant with a great Developer Experience in mind.

Nuxt is a free and [open-source framework](https://github.com/nuxt/nuxt) with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with [Vue.js](https://vuejs.org).

We made everything so you can start writing `.vue` files from the beginning while enjoying hot module replacement in development and a performant application in production with server-side rendering by default.

Nuxt has no vendor lock-in, allowing you to deploy your application [**everywhere, even on the edge**](/blog/nuxt-on-the-edge).

<tip>

If you want to play around with Nuxt in your browser, you can [try it out in one of our online sandboxes](/docs/4.x/getting-started/installation#play-online).

</tip>

## Automation and Conventions

Nuxt uses conventions and an opinionated directory structure to automate repetitive tasks and allow developers to focus on pushing features. The configuration file can still customize and override its default behaviors.

- **File-based routing:** define routes based on the structure of your [`app/pages/` directory](/docs/4.x/directory-structure/app/pages). This can make it easier to organize your application and avoid the need for manual route configuration.
- **Code splitting:** Nuxt automatically splits your code into smaller chunks, which can help reduce the initial load time of your application.
- **Server-side rendering out of the box:** Nuxt comes with built-in SSR capabilities, so you don't have to set up a separate server yourself.
- **Auto-imports:** write Vue composables and components in their respective directories and use them without having to import them with the benefits of tree-shaking and optimized JS bundles.
- **Data-fetching utilities:** Nuxt provides composables to handle SSR-compatible data fetching as well as different strategies.
- **Zero-config TypeScript support:** write type-safe code without having to learn TypeScript with our auto-generated types and `tsconfig.json`.
- **Configured build tools:** we use [Vite](https://vite.dev) by default to support hot module replacement (HMR) in development and bundling your code for production with best-practices baked-in.

Nuxt takes care of these and provides both frontend and backend functionality so you can focus on what matters: **creating your web application**.

## Server-Side Rendering

Nuxt comes with built-in server-side rendering (SSR) capabilities by default, without having to configure a server yourself, which has many benefits for web applications:

- **Faster initial page load time:** Nuxt sends a fully rendered HTML page to the browser, which can be displayed immediately. This can provide a faster perceived page load time and a better user experience (UX), especially on slower networks or devices.
- **Improved SEO:** search engines can better index SSR pages because the HTML content is available immediately, rather than requiring JavaScript to render the content on the client-side.
- **Better performance on low-powered devices:** it reduces the amount of JavaScript that needs to be downloaded and executed on the client-side, which can be beneficial for low-powered devices that may struggle with processing heavy JavaScript applications.
- **Better accessibility:** the content is immediately available on the initial page load, improving accessibility for users who rely on screen readers or other assistive technologies.
- **Easier caching:** pages can be cached on the server-side, which can further improve performance by reducing the amount of time it takes to generate and send the content to the client.

Overall, server-side rendering can provide a faster and more efficient user experience, as well as improve search engine optimization and accessibility.

As Nuxt is a versatile framework, it gives you the possibility to statically render your whole application to a static hosting with `nuxt generate`,
disable SSR globally with the `ssr: false` option or leverage hybrid rendering by setting up the `routeRules` option.

<read-more title="Nuxt rendering modes" to="/docs/4.x/guide/concepts/rendering">



</read-more>

### Server engine

The Nuxt server engine [Nitro](https://nitro.build/) unlocks new full-stack capabilities.

In development, it uses Rollup and Node.js workers for your server code and context isolation. It also generates your server API by reading files in `server/api/` and server middleware from `server/middleware/`.

In production, Nitro builds your app and server into one universal `.output` directory. This output is light: minified and removed from any Node.js modules (except polyfills). You can deploy this output on any system supporting JavaScript, from Node.js, Serverless, Workers, Edge-side rendering or purely static.

<read-more title="Nuxt server engine" to="/docs/4.x/guide/concepts/server-engine">



</read-more>

### Production-ready

A Nuxt application can be deployed on a Node or Deno server, pre-rendered to be hosted in static environments, or deployed to serverless and edge providers.

<read-more title="Deployment section" to="/docs/4.x/getting-started/deployment">



</read-more>

### Modular

A module system allows you to extend Nuxt with custom features and integrations with third-party services.

<read-more title="Nuxt Modules Concept" to="/docs/4.x/guide/concepts/modules">



</read-more>

### Architecture

Nuxt is composed of different [core packages](https://github.com/nuxt/nuxt/tree/main/packages):

- Core engine: [nuxt](https://github.com/nuxt/nuxt/tree/main/packages/nuxt)
- Bundlers: [@nuxt/vite-builder](https://github.com/nuxt/nuxt/tree/main/packages/vite), [@nuxt/rspack-builder](https://github.com/nuxt/nuxt/tree/main/packages/rspack) and [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)
- Command line interface: [@nuxt/cli](https://github.com/nuxt/cli)
- Server engine: [nitro](https://github.com/nitrojs/nitro)
- Development kit: [@nuxt/kit](https://github.com/nuxt/nuxt/tree/main/packages/kit)

We recommend reading each concept to have a full vision of Nuxt capabilities and the scope of each package.

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/jsx.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/jsx.md

# JSX / TSX

> This example shows how to use JSX syntax with typescript in Nuxt pages and components.

<read-more icon="i-simple-icons-vuedotjs" target="_blank" to="https://vuejs.org/guide/extras/render-function.html#jsx-tsx">



</read-more>

<sandbox branch="main" dir="examples/advanced/jsx" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/kit.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/kit.md

# Nuxt Kit

> @nuxt/kit provides features for module authors.

Nuxt Kit provides composable utilities to make interacting with [Nuxt Hooks](/docs/4.x/api/advanced/hooks), the [Nuxt Interface](/docs/4.x/guide/going-further/internals#the-nuxt-interface) and developing [Nuxt modules](/docs/4.x/guide/modules) super easy.

<read-more to="/docs/4.x/api/kit">

Discover all Nuxt Kit utilities.

</read-more>

## Usage

### Install Dependency

You can install the latest Nuxt Kit by adding it to the `dependencies` section of your `package.json`. However, please consider always explicitly installing the `@nuxt/kit` package even if it is already installed by Nuxt.

<note>

`@nuxt/kit` and `@nuxt/schema` are key dependencies for Nuxt. If you are installing it separately, make sure that the versions of `@nuxt/kit` and `@nuxt/schema` are equal to or greater than your `nuxt` version to avoid any unexpected behavior.

</note>

```json [package.json]
{
  "dependencies": {
    "@nuxt/kit": "npm:@nuxt/kit-nightly@latest"
  }
}
```

### Import Kit Utilities

```ts [test.mjs]
import { useNuxt } from '@nuxt/kit'
```

<read-more to="/docs/4.x/api/kit">



</read-more>

<note>

Nuxt Kit utilities are only available for modules and not meant to be imported in runtime (components, Vue composables, pages, plugins, or server routes).

</note>

Nuxt Kit is an [esm-only package](/docs/4.x/guide/concepts/esm) meaning that you **cannot** `require('@nuxt/kit')`. As a workaround, use dynamic import in the CommonJS context:

```ts [test.cjs]
// This does NOT work!
// const kit = require('@nuxt/kit')
async function main () {
  const kit = await import('@nuxt/kit')
}
main()
```

---

# Source: https://nuxt.com/raw/deploy/koyeb.md

# Koyeb

> Deploy your Nuxt Application to Koyeb infrastructure.

Nuxt supports deploying on the [Koyeb serverless platform](https://www.koyeb.com/docs) with minimal configuration.

## Setup

1. Create a new Koyeb app for Nuxt following the [guide](https://www.koyeb.com/docs/deploy/nuxt).
2. Set the `engines.node` field in your project's `package.json` file to a [Koyeb-supported version of Node.js](https://www.koyeb.com/docs/build-and-deploy/build-from-git/nodejs#runtime):```json [package.json]
{
  "engines": {
      "node": "20.x"
  }
}
```
3. Ensure that `build` and `start` scripts are defined within the project's `package.json` file to define how to build and run the application:```json [package.json]
{
  "scripts": {
      "build": "nuxt build",
      "start": "node .output/server/index.mjs"
  }
}
```
4. During deployment, you'll need to configure environment variables. In your service settings, set the following [environment variable](https://www.koyeb.com/docs/build-and-deploy/environment-variables):```bash
SERVER_PRESET=koyeb
```
5. Click "Deploy" to build and deploy your Nuxt app.

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/koyeb">

Head over **Nitro documentation** to learn more about the Koyeb deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/layers.md

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/layers.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/layers.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/layers.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/layers.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/layers.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/layers.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/layers.md

# Layers

> Nuxt provides a powerful system that allows you to extend the default files, configs, and much more.

One of the core features of Nuxt is the layers and extending support. You can extend a default Nuxt application to reuse components, utils, and configuration. The layers structure is almost identical to a standard Nuxt application which makes them easy to author and maintain.

## Use Cases

- Share reusable configuration presets across projects using `nuxt.config` and `app.config`
- Create a component library using [`app/components/`](/docs/4.x/directory-structure/app/components) directory
- Create utility and composable library using [`app/composables/`](/docs/4.x/directory-structure/app/composables) and [`app/utils/`](/docs/4.x/directory-structure/app/utils) directories
- Create Nuxt module presets
- Share standard setup across projects
- Create Nuxt themes
- Enhance code organization by implementing a modular architecture and support Domain-Driven Design (DDD) pattern in large scale projects.

## Usage

By default, any layers within your project in the `~~/layers` directory will be automatically registered as layers in your project.

<note>

Layer auto-registration was introduced in Nuxt v3.12.0.

</note>

In addition, named layer aliases to the `srcDir` of each of these layers will automatically be created. For example, you will be able to access the `~~/layers/test` layer via `#layers/test`.

<note>

Named layer aliases were introduced in Nuxt v3.16.0.

</note>

In addition, you can extend from a layer by adding the [extends](/docs/4.x/api/nuxt-config#extends) property to your [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config) file.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: [
    // Extend from a local layer
    '../base',
    // Extend from an installed npm package
    '@my-themes/awesome',
    // Extend from a git repository
    'github:my-themes/awesome#v1',
  ],
})
```

You can also pass an authentication token if you are extending from a private GitHub repository:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: [
    // per layer configuration
    ['github:my-themes/private-awesome', { auth: process.env.GITHUB_TOKEN }],
  ],
})
```

<note>

If a branch is not specified, this will clone `main`.

</note>

<tip>

You can override a layer's alias by specifying it in the options next to the layer source.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: [
    [
      'github:my-themes/awesome',
      {
        meta: {
          name: 'my-awesome-theme',
        },
      },
    ],
  ],
})
```

</tip>

Nuxt uses [unjs/c12](https://github.com/unjs/c12) and [unjs/giget](https://github.com/unjs/giget) for extending remote layers. Check the documentation for more information and all available options.

## Layer Priority

When using multiple layers, it's important to understand the override order. Layers with **higher priority** override layers with lower priority when they define the same files or components.

### Priority Order

From highest to lowest priority:

1. **Your project files** - always have the highest priority
2. **Auto-scanned layers** from `~~/layers` directory - sorted alphabetically (Z has higher priority than A)
3. **Layers in extends** config - first entry has higher priority than second

### Practical Example

Consider multiple layers defining the same component:

```bash [Directory structure]
layers/
  1.base/
    app/components/Button.vue    # Base button style
  2.theme/
    app/components/Button.vue    # Themed button (overrides base)
app/
  components/Button.vue          # Project button (overrides all layers)
```

In this case:

- If only layers exist, `2.theme/Button.vue` is used (higher alphabetically)
- If `app/components/Button.vue` exists in your project, it overrides all layers

### Controlling Priority

You can prefix layer directories with numbers to control the order:

```bash [Directory structure]
layers/
  1.base/        # Lowest priority
  2.features/    # Medium priority
  3.admin/       # Highest priority (among layers)
```

<tip>

This pattern is useful for creating base layers with defaults that can be progressively overridden by more specific layers.

</tip>

### When to Use Each

- **~~/layers directory** - Use for local layers that are part of your project
- **extends** - Use for external dependencies (npm packages, remote repositories) or layers outside your project directory

### Full Example with extends

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: [
    '../base', // Local layer outside project
    '@my-themes/awesome', // NPM package
    'github:my-themes/awesome#v1', // Remote repository
  ],
})
```

If you also have `~~/layers/custom`, the priority order is:

- Your project files (highest)
- `~~/layers/custom`
- `../base`
- `@my-themes/awesome`
- `github:my-themes/awesome#v1` (lowest)

<read-more to="/docs/4.x/directory-structure/layers">

Learn about the **layers/ directory** to organize and share reusable code, components, composables, and configurations across your Nuxt application.

</read-more>

<read-more to="/docs/4.x/guide/going-further/layers">

Read more about layers in the **Layer Author Guide**.

</read-more>

<video-accordion title="Watch a video from Learn Vue about Nuxt Layers" video-id="lnFCM7c9f7I">



</video-accordion>

<video-accordion title="Watch a video from Alexander Lichter about Nuxt Layers" video-id="fr5yo3aVkfA">



</video-accordion>

## Examples

<card-group>
<card icon="i-simple-icons-github" target="_blank" title="Content Wind" to="https://github.com/Atinux/content-wind">

A lightweight Nuxt theme to build a Markdown driven website. Powered by Nuxt Content, TailwindCSS and Iconify.

</card>
</card-group>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/layout.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/layout.md

# Layout

> Nuxt Kit provides a set of utilities to help you work with layouts.

Layouts is used to be a wrapper around your pages. It can be used to wrap your pages with common components, for example, a header and a footer. Layouts can be registered using `addLayout` utility.

## `addLayout`

Register template as layout and add it to the layouts.

<note>

In Nuxt 2 `error` layout can also be registered using this utility. In Nuxt 3+ `error` layout [replaced](/docs/4.x/getting-started/error-handling#error-page) with `error.vue` page in project root.

</note>

### Usage

```tstwoslash
import { addLayout, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addLayout({
      src: resolve('templates/custom-layout.ts'),
      filename: 'custom-layout.ts',
    }, 'custom')
  },
})
```

### Type

```ts
function addLayout (layout: NuxtTemplate | string, name: string): void
```

### Parameters

**layout**: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        src
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path to the template. If <code>
        src
      </code>
      
       is not provided, <code>
        getContents
      </code>
      
       must be provided instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filename
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Filename of the template. If <code>
        filename
      </code>
      
       is not provided, it will be generated from the <code>
        src
      </code>
      
       path. In this case, the <code>
        src
      </code>
      
       option is required.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dst
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path to the destination file. If <code>
        dst
      </code>
      
       is not provided, it will be generated from the <code>
        filename
      </code>
      
       path and nuxt <code>
        buildDir
      </code>
      
       option.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Record
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="sZSNi">
          any
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Options to pass to the template.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        getContents
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          data
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="s52Pk">
          Promise
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      A function that will be called with the <code>
        options
      </code>
      
       object. It should return a string or a promise that resolves to a string. If <code>
        src
      </code>
      
       is provided, this function will be ignored.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        write
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
    </td>
  </tr>
</tbody>
</table>

**name**: The name to register the layout under (e.g., `default`, `custom`, etc.).

### Example

This will register a layout named `custom` that wraps pages with a header and footer.

```tstwoslash
import { addLayout, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addLayout({
      write: true,
      filename: 'my-layout.vue',
      getContents: () => `<template>
  <div>
    <header>My Header</header>
    <slot />
    <footer>My Footer</footer>
  </div>
</template>`,
    }, 'custom')
  },
})
```

You can then use this layout in your pages:

```vue [app/pages/about.vue]
<script setup lang="ts">
definePageMeta({
  layout: 'custom',
})
</script>

<template>
  <div>About Page</div>
</template>
```

<warning>

Due to the lack of support for virtual `.vue` files by `@vitejs/plugin-vue`, you can work around this limitation by passing `write: true` to the first argument of `addLayout`.

</warning>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/features/layouts.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/layouts.md

# Source: https://nuxt.com/raw/docs/4.x/examples/features/layouts.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/layouts.md

# layouts

> Nuxt provides a layouts framework to extract common UI patterns into reusable layouts.

<tip icon="i-lucide-rocket">

For best performance, components placed in this directory will be automatically loaded via asynchronous import when used.

</tip>

## Enable Layouts

Layouts are enabled by adding [`<NuxtLayout>`](/docs/4.x/api/components/nuxt-layout) to your [`app.vue`](/docs/4.x/directory-structure/app/app):

```vue [app/app.vue]
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>
```

To use a layout:

- Set a `layout` property in your page with [definePageMeta](/docs/4.x/api/utils/define-page-meta).
- Set the `name` prop of `<NuxtLayout>`.
- Set the `appLayout` property in route rules.

<note>

The layout name is normalized to kebab-case, so `someLayout` becomes `some-layout`.

</note>

<note>

If no layout is specified, `app/layouts/default.vue` will be used.

</note>

<important>

If you only have a single layout in your application, we recommend using [`app.vue`](/docs/4.x/directory-structure/app/app) instead.

</important>

<important>

Unlike other components, your layouts must have a single root element to allow Nuxt to apply transitions between layout changes - and this root element cannot be a `<slot />`.

</important>

## Default Layout

Add a `~/layouts/default.vue`:

```vue [app/layouts/default.vue]
<template>
  <div>
    <p>Some default layout content shared across all pages</p>
    <slot />
  </div>
</template>
```

In a layout file, the content of the page will be displayed in the `<slot />` component.

## Named Layout

```bash [Directory Structure]
-| layouts/
---| default.vue
---| custom.vue
```

Then you can use the `custom` layout in your page:

```vue [pages/about.vue]twoslash
<script setup lang="ts">
declare module 'nuxt/app' {
  interface NuxtLayouts {
    'custom': unknown
  }
}
// ---cut---
definePageMeta({
  layout: 'custom',
})
</script>
```

<read-more to="/docs/4.x/directory-structure/app/pages#page-metadata">

Learn more about `definePageMeta`.

</read-more>

You can directly override the default layout for all pages using the `name` property of [`<NuxtLayout>`](/docs/4.x/api/components/nuxt-layout):

```vue [app/app.vue]
<script setup lang="ts">
// You might choose this based on an API call or logged-in status
const layout = 'custom'
</script>

<template>
  <NuxtLayout :name="layout">
    <NuxtPage />
  </NuxtLayout>
</template>
```

If you have a layout in nested directories, the layout's name will be based on its own path directory and filename, with duplicate segments being removed.

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      Layout Name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ~/layouts/desktop/default.vue
      </code>
    </td>
    
    <td>
      <code>
        desktop-default
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ~/layouts/desktop-base/base.vue
      </code>
    </td>
    
    <td>
      <code>
        desktop-base
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ~/layouts/desktop/index.vue
      </code>
    </td>
    
    <td>
      <code>
        desktop
      </code>
    </td>
  </tr>
</tbody>
</table>

For clarity, we recommend that the layout's filename matches its name:

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      Layout Name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ~/layouts/desktop/DesktopDefault.vue
      </code>
    </td>
    
    <td>
      <code>
        desktop-default
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ~/layouts/desktop-base/DesktopBase.vue
      </code>
    </td>
    
    <td>
      <code>
        desktop-base
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ~/layouts/desktop/Desktop.vue
      </code>
    </td>
    
    <td>
      <code>
        desktop
      </code>
    </td>
  </tr>
</tbody>
</table>

<link-example to="/docs/4.x/examples/features/layouts">



</link-example>

## Changing the Layout Dynamically

You can also use the [`setPageLayout`](/docs/4.x/api/utils/set-page-layout) helper to change the layout dynamically:

```vuetwoslash
<script setup lang="ts">
declare module 'nuxt/app' {
  interface NuxtLayouts {
    'custom': unknown
  }
}
// ---cut---
function enableCustomLayout () {
  setPageLayout('custom')
}
definePageMeta({
  layout: false,
})
</script>

<template>
  <div>
    <button @click="enableCustomLayout">
      Update layout
    </button>
  </div>
</template>
```

You can also set layouts for specific routes using the `appLayout` property in route rules:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    // Set layout for specific route
    '/admin': { appLayout: 'admin' },
    // Set layout for multiple routes
    '/dashboard/**': { appLayout: 'dashboard' },
    // Disable layout for a route
    '/landing': { appLayout: false },
  },
})
```

<tip>

This is useful when you want to manage layouts centrally in your configuration rather than in each page file, or when you need to apply layouts to routes that don't have corresponding page components (such as catchall pages which might match many paths).

</tip>

<link-example to="/docs/4.x/examples/features/layouts">



</link-example>

## Overriding a Layout on a Per-page Basis

If you are using pages, you can take full control by setting `layout: false` and then using the `<NuxtLayout>` component within the page.

<code-group>

```vue [app/pages/index.vue]
<script setup lang="ts">
definePageMeta({
  layout: false,
})
</script>

<template>
  <div>
    <NuxtLayout name="custom">
      <template #header>
        Some header template content.
      </template>

      The rest of the page
    </NuxtLayout>
  </div>
</template>
```

```vue [app/layouts/custom.vue]
<template>
  <div>
    <header>
      <slot name="header">
        Default header content
      </slot>
    </header>
    <main>
      <slot />
    </main>
  </div>
</template>
```

</code-group>

<important>

If you use `<NuxtLayout>` within your pages, make sure it is not the root element (or [disable layout/page transitions](/docs/4.x/getting-started/transitions#disable-transitions)).

</important>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/ai/llms-txt.md

# Source: https://nuxt.com/raw/docs/4.x/guide/ai/llms-txt.md

# Nuxt LLMs.txt

> How to get AI tools like Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude to understand Nuxt concepts, APIs, and best practices.

## What is LLMs.txt?

LLMs.txt is a structured documentation format specifically designed for large language models (LLMs). Nuxt provides LLMs.txt files that contain comprehensive information about the framework, making it easy for AI tools to understand and assist with Nuxt development.

These files are optimized for AI consumption and contain structured information about concepts, APIs, usage patterns, and best practices.

## Available routes

We provide LLMs.txt routes to help AI tools access our documentation:

- **/llms.txt** - Contains a structured overview of all documentation pages and their links (~5K tokens)
- **/llms-full.txt** - Provides comprehensive documentation including getting started guides, API references, blog posts, and deployment guides (~1M+ tokens)

## Choosing the Right File

<note icon="i-lucide-info">

**Most users should start with /llms.txt** - it contains all essential information and works with standard LLM context windows.

Use `/llms-full.txt` only if you need comprehensive implementation details and your AI tool supports large contexts (200K+ tokens).

</note>

## Important usage notes

<warning icon="i-lucide-alert-triangle">

**@-symbol must be typed manually** - When using tools like Cursor or Windsurf, the `@` symbol must be typed by hand in the chat interface. Copy-pasting breaks the tool's ability to recognize it as a context reference.

</warning>

## Usage with AI Tools

### Cursor

Nuxt provides specialized LLMs.txt files that you can reference in Cursor for better AI assistance with Nuxt development.

#### How to use

1. **Direct reference**: Mention the LLMs.txt URLs when asking questions
2. Add these specific URLs to your project context using `@docs`

[Read more about Cursor Web and Docs Search](https://cursor.com/docs/context/symbols)

### Windsurf

Windsurf can directly access the Nuxt LLMs.txt files to understand framework usage and best practices.

#### Using LLMs.txt with Windsurf

- Use `@docs` to reference specific LLMs.txt URLs
- Create persistent rules referencing these URLs in your workspace

[Read more about Windsurf Web and Docs Search](https://docs.windsurf.com/windsurf/cascade/web-search)

### Other AI Tools

Any AI tool that supports LLMs.txt can use these routes to better understand Nuxt.

#### Examples for ChatGPT, Claude, or other LLMs

- "Using Nuxt documentation from [https://nuxt.com/llms.txt](https://nuxt.com/llms.txt)"
- "Follow complete Nuxt guidelines from [https://nuxt.com/llms-full.txt](https://nuxt.com/llms-full.txt)"

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/locale.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/locale.md

# Locale

> This example shows how to define a locale composable to handle the application's locale, both server and client side.

<callout icon="i-ph-info-duotone">

You can right-click to "View Page Source" and see that Nuxt renders the correct date in SSR based on the visitor's locale.

</callout>

<sandbox branch="main" dir="examples/advanced/locale" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/logging.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/logging.md

# Logging

> Nuxt Kit provides a set of utilities to help you work with logging. These functions allow you to log messages with extra features.

Nuxt provides a logger instance that you can use to log messages with extra features. `useLogger` allows you to get a logger instance.

## `useLogger`

Returns a logger instance. It uses [consola](https://github.com/unjs/consola) under the hood.

### Usage

```tstwoslash
import { defineNuxtModule, useLogger } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const logger = useLogger('my-module')

    logger.info('Hello from my module!')
  },
})
```

### Type

```ts
function useLogger (tag?: string, options?: Partial<ConsolaOptions>): ConsolaInstance
```

### Parameters

**tag**: A tag to suffix all log messages with, displayed on the right near the timestamp.

**options**: Consola configuration options.

### Examples

```tstwoslash
import { defineNuxtModule, useLogger } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const logger = useLogger('my-module', { level: options.quiet ? 0 : 3 })

    logger.info('Hello from my module!')
  },
})
```

---

# Source: https://nuxt.com/raw/blog/looking-forward-2024.md

# Nuxt: Looking forward

> A lot of things have happened for Nuxt over the last year. Sébastien and Daniel share their thoughts on what we've achieved, and where we're going next.

## A Review of 2023 - Sébastien

In January 2023, Daniel set out [**Nuxt: A vision for 2023**](/blog/vision-2023). We achieved most of the goals we set out to accomplish. Some of them are missing and we will tackle them this year!

It was a productive year and the team shipped **9 minor releases**: from v3.1 to v3.9.

In the first 365 days, Nuxt 3 reached new milestones:

- <icon name="i-lucide-star">



</icon>

 **49,5K stars** on GitHub ([add yours](https://github.com/nuxt/nuxt) 😊)
- <icon name="i-lucide-download">



</icon>

  **27M downloads** on npm
- <icon name="i-lucide-user-plus">



</icon>

 **612 contributors** on the [nuxt repository](https://github.com/nuxt/nuxt)
- <icon name="i-lucide-puzzle">



</icon>

 **184 modules** created by **142 maintainers**
- <icon name="i-lucide-circle-check">



</icon>

 **2,423 closed issues**
- <icon name="i-lucide-git-pull-request">



</icon>

 **1,728 merged pull request**
- <icon name="i-simple-icons-discord">



</icon>

 **26,300 members** on [Discord](https://chat.nuxt.dev)

End of October, Nuxt 3 downloads [surpassed Nuxt 2 downloads](https://x.com/Atinux/status/1731980841142669379) 🚀.

The same month, we released [Nuxt Image 1.0](https://image.nuxt.com) with Nuxt 3 support and new features to make sure your website stays performant when using Images. Nuxt now auto-installs it as soon as you start using the [`<NuxtImg>`](/docs/api/components/nuxt-img) or [`<NuxtPicture>`](/docs/api/components/nuxt-picture) component.

We shipped [Nuxt DevTools](/blog/nuxt-devtools-v1-0), leveling up the Developer Experience we can expect from a Web framework. I am happy to see that we inspired other frameworks to adopt a similar approach: [Vue DevTools](https://x.com/vuejs/status/1741032977919053865), [Next DevTools](https://x.com/xinyao27/status/1741447261132145133), [Remix DevTools](https://x.com/AlemTuzlak59192/status/1741903214860009539), [Vite Plugin DevTools](https://github.com/pheno-agency/vite-plugin-devtools), [Astro Dev Toolbar](https://x.com/n_moore/status/1732164645778071888) and more.

After many months of building our UI library internally, [Benjamin Canac](https://github.com/benjamincanac) open sourced [Nuxt UI](https://ui.nuxt.com) to let you create websites at a faster pace with highly customizable components built with TailwindCSS.

[Nuxt Content](http://content.nuxt.com) has had 10 minor releases with various improvements: from performance to the MDC syntax. We have some ongoing work to better support [edge rendering](https://nuxt.com/blog/nuxt-on-the-edge) in the future. At the same time, the NuxtLabs team is working on [Nuxt Studio](https://nuxt.studio) to let users edit Markdown files with a Notion-like editor while keeping your content inside your git repository.

## Looking forward into 2024 - Daniel

We are well into 2024, and this update is definitely overdue!

Here are a few thoughts on the direction that I'll be seeking to lead Nuxt in over the next year.

### Continued development and reimagination

I would love to see us continuing to adapt our best practices to the changing needs of the ecosystem, expand the boundaries of what good DX could be, and improve Nuxt.

I am really pleased at what we currently offer in Nuxt. But I would never want to rest on our laurels. We need to keep pursuing new possibilities that appear as the web platform develops. We've committed to [Baseline Compatibility](https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility) going forward (and are included in conversations about it with the [W3C WebDX Community Group](https://github.com/web-platform-dx/web-features)).

We have some strategies to enable us to do this while also prioritising stability for our existing users, and recognising the scope of the Nuxt ecosystem.

1. In general we follow a pattern of **introducing a module or experimental feature** that can be disabled in testing while we gather feedback and confirm the direction and API of new features.
2. We have adopted the **ecosystem-ci pattern** of validating that our code changes in Nuxt don't break downstream projects unintentionally. If you maintain a well-tested module or library that depends on Nuxt, I'd welcome a PR adding your project to [nuxt/ecosystem-ci](https://github.com/nuxt/ecosystem-ci).
3. We plan to release a **pull-based test** that will allow you to configure your CI to test itself against the latest nightly version of Nuxt to provide early feedback on new Nuxt releases, rather than facing an issue when upgrading.
4. Finally, we have adopted a **push-based approach to updating existing projects**. When we identify breaking changes or improvements that can be rolled out to the ecosystem, we will proactively raise PRs to Nuxt modules (and, to a lesser extent, other open-source projects using Nuxt).

I hope this will allow us to continue to innovate and experiment with new features without sacrificing the stability and maintainability.

In particular, look for active development on the following:

- ✅ [nuxt/fonts](https://github.com/nuxt/fonts) - working up to v1.0.0
- ✅ [nuxt/eslint](https://github.com/nuxt/eslint) - working up to v1.0.0
- 🔥 [nuxt/scripts](https://github.com/nuxt/scripts) - soon to be released
- 🚧 [nuxt/a11y](https://github.com/nuxt/a11y) - coming soon!
- 🚧 [nuxt/auth](https://github.com/nuxt/auth) - coming soon!
- 🚧 [nuxt/hints](https://github.com/nuxt/hints) - coming soon!

### Sustainable open source

I want Nuxt to continue to be an independent, community-driven framework for the long term.

I'm really delighted to see successful businesses founded on Nuxt, and initiatives springing up around Nuxt that become [sponsors](/enterprise/sponsors) or otherwise giving back to the core framework, enabling ongoing Nuxt development.

Obviously, [NuxtLabs](https://nuxtlabs.com) is the preeminent example of that. [Pooya Parsa](https://github.com/pi0), [Anthony Fu](https://github.com/antfu) and I are all able to work full-time on open source thanks to their paid services around Nuxt: [Nuxt UI Pro](https://ui.nuxt.com/pro/getting-started), [Nuxt Experts](/enterprise/support), [Nuxt Studio](https://nuxt.studio/) and [NuxtHub](https://hub.nuxt.com/) (soon). They also [sponsor community members](https://github.com/orgs/nuxtlabs/sponsoring) from Vue, Vite, UnJS, and Nuxt.

For me, keeping Nuxt independent and sustainable for the future requires an active and growing team and community. In the weeks ahead, I'll be announcing a broader 'Nuxt team' alongside the core team. This is about recognising the tireless work of the many people whose contributions are already making Nuxt what it is.

I would also love to see more of those team members or the wider community sponsored to work in the Nuxt ecosystem in the years ahead. If your company has benefited from Nuxt, please do consider sponsoring some of the developers working on Nuxt, whether they are team or wider community members.

### Friendly collaboration

From the beginning of our work on Nuxt 3, we have sought to extract out utilities, libraries and even frameworks that we benefit from so they can *also* benefit a much broader audience.

That's the origin of [UnJS](https://unjs.io/), of course, and it continues to thrive under the leadership of [Pooya Parsa](https://github.com/pi0) (who is also a key member of the Nuxt core team).

We'd like to continue that attitude of friendly collaboration. Although building things ourselves or keeping them to ourselves might to be 'success', I don't have any time for zero-sum games. We will go further, both as a framework and as a web community, if we build *together*.

Equally, one of our core values is platform-independence (alongside deep platform *integration*). We support 90+ providers across deployment, testing, stories, KV and cache, databases, image CDNs and font hosts. That breadth of ecosystem is one that bears rich rewards and frees people up to make choices about which providers they use based on the value they bring. But it *also* means we are dependent on our community who use these different providers to help us keep these integrations up-to-date.

Nuxt isn't going anywhere, but we hope that the work we do collaboratively will last long beyond us.

### A welcoming community

Although it is easy to focus on technical excellence or the quality of developer experience, I am more encouraged to see the continued growth of the Nuxt ecosystem as a welcoming and friendly community.

I am incredibly grateful for the kind tone that prevails across [our community Discord](https://chat.nuxt.dev), on [Twitter](https://x.com/nuxt_js), and on [GitHub](https://github.com/nuxt/nuxt).

### What about Nuxt 4?

The JavaScript space is known for producing a new framework every week, which means there is a natural hype cycle.

But we are not aiming for hype with the continued development of Nuxt, which is part of why we have committed to regular release cycles:

- **major** framework releases every year
- **minor** releases every month or so
- **patch** releases every week or so

You can expect to see breaking changes shipped in major releases, with features shipped in our minor releases. That means we aren't holding features back for Nuxt 4; we'll ship those as regularly as we can in our 6-weekly minor release cycle.

Our aim is that Nuxt 4 is an opportunity for *thoughtful* breaking changes with either a straightforward migration path (ideally with automated processes) or the ability to opt-in to previous behaviour.

There are definitely lessons we as a team have learned form the transition from Nuxt 2 to 3, and I see Nuxt 4 as an opportunity for us to prove that major releases can be a good experience for users.

You can preview the changes we have in mind by browsing [our roadmap](https://github.com/orgs/nuxt/projects/8/views/4) or checking through [the issues we've tagged for v4](https://github.com/nuxt/nuxt/issues?q=is:issue+label:4.x). Feedback and wishes are very welcome as always!

#### Timetable

Our roadmap for Nuxt 4 is a little complex as we are also planning on major releases across the UnJS ecosystem.

Roughly speaking, we are aiming to have one more minor release for Nuxt v3 and Nitro v2, before beginning a [raft of major releases across the UnJS ecosystem of packages](https://github.com/unjs/community/discussions/4) - culminating in Nuxt v4.

We are aiming to release **Nuxt v4 on or before June 14** (though obviously this is dependent on having enough time after Nitro's major release to be properly tested in the community, so be aware that this is not an exact date).

#### Ongoing Support

After the release of Nuxt v4, we will be providing **six months** of ongoing support and bug-fixes for Nuxt v3, which we expect will be more than ample to upgrade to v4 given our aim of a gentle upgrade path.

We hope you are as excited as we are about the pending release of Nuxt v4! 🎉

---

Finally, thank you so much for all your trust and support as we've been building Nuxt. I know I speak for the whole team when I say that it's such a privilege to be doing this alongside everyone in the Nuxt community! ❤️

Daniel (on behalf of the whole Nuxt team)

---

# Source: https://nuxt.com/raw/docs/3.x/guide/ai/mcp.md

# Source: https://nuxt.com/raw/docs/4.x/guide/ai/mcp.md

# Nuxt MCP Server

> Use Nuxt documentation in your AI assistants with Model Context Protocol support.

## What is MCP?

MCP (Model Context Protocol) is a standardized protocol that enables AI assistants to access external data sources and tools. Nuxt provides an MCP server that allows AI assistants like Claude Code, Cursor, and Windsurf to access documentation, blog posts, and deployment guides directly.

The MCP server provides structured access to the Nuxt documentation, making it easy for AI tools to understand and assist with Nuxt development.

## Resources

The Nuxt MCP server provides the following resources for discovery:

- **resource://nuxt-com/documentation-pages**: Browse all available documentation pages (defaults to v4.x)
- **resource://nuxt-com/blog-posts**: Browse all Nuxt blog posts including releases and tutorials
- **resource://nuxt-com/deploy-providers**: Browse all deployment providers and hosting platforms

You're able to access these resources with tools like Claude Code by using `@`.

## Tools

The Nuxt MCP server provides the following tools organized by category:

### Documentation

- **list_documentation_pages**: Lists all available Nuxt documentation pages with their categories and basic information. Supports version filtering (3.x, 4.x, or all)
- **get_documentation_page**: Retrieves documentation page content and details by path
- **get_getting_started_guide**: Gets the getting started guide for a specific Nuxt version

### Blog

- **list_blog_posts**: Lists all Nuxt blog posts with metadata including dates, categories, and tags
- **get_blog_post**: Retrieves blog post content and details by path

### Deployment

- **list_deploy_providers**: Lists all deployment providers and hosting platforms for Nuxt applications
- **get_deploy_provider**: Retrieves deployment provider details and instructions by path

## Prompts

The Nuxt MCP server provides guided prompts for common workflows:

- **find_documentation_for_topic**: Find the best Nuxt documentation for a specific topic or feature
- **deployment_guide**: Get deployment instructions for a specific hosting provider
- **migration_help**: Get help with migrating between Nuxt versions

You're able to access these resources with tools like Claude Code by using `/`.

## Setup

The Nuxt MCP server uses HTTP transport and can be installed in different AI assistants.

### ChatGPT

<note icon="i-lucide-info">

**Custom connectors using MCP are available on ChatGPT for Pro and Plus accounts** on the web.

</note>

Follow these steps to set up Nuxt as a connector within ChatGPT:

1. **Enable Developer mode:**
  - Go to Settings → Connectors → Advanced settings → Developer mode
2. **Open ChatGPT settings**
3. **In the Connectors tab, Create a new connector:**
  - Give it a name: `Nuxt`
  - MCP server URL: `https://nuxt.com/mcp`
  - Authentication: `None`
4. **Click Create**

The Nuxt connector will appear in the composer's "Developer mode" tool later during conversations.

### Claude Code

<note icon="i-lucide-info">

**Ensure Claude Code is installed** - Visit [Anthropic's documentation](https://docs.claude.com/en/docs/claude-code/quickstart) for installation instructions.

</note>

Add the server using the CLI command:

```bash
claude mcp add --transport http nuxt-remote https://nuxt.com/mcp
```

### Claude Desktop

#### Setup Instructions

1. Open Claude Desktop and navigate to "Settings" > "Developer".
2. Click on "Edit Config". This will open the local Claude directory.
3. Modify the `claude_desktop_config.json` file with your custom MCP server configuration.
```json [claude_desktop_config.json]
{
  "mcpServers": {
    "nuxt": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://nuxt.com/mcp"
      ]
    }
  }
}
```
4. Restart Claude Desktop app. The Nuxt MCP server should now be registered.

### Cursor

Click the button below to install the Nuxt MCP server directly in Cursor:

<u-button color="neutral" icon="i-custom-cursor" label="Install MCP Server" to="cursor://anysphere.cursor-deeplink/mcp/install?name=nuxt&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vbnV4dC5jb20vbWNwIn0%3D">



</u-button>

For manual setup, follow these steps:

1. Open Cursor and go to "Settings" > "Tools & MCP"
2. Add the Nuxt MCP server configuration

Or manually create/update `.cursor/mcp.json` in your project root:

```json [.cursor/mcp.json]
{
  "mcpServers": {
    "nuxt": {
      "type": "http",
      "url": "https://nuxt.com/mcp"
    }
  }
}
```

### Le Chat Mistral

1. Navigate to "Intelligence" > "Connectors"
2. Click on "Add Connector" button, then select "Custom MCP Connector"
3. Create your Custom MCP Connector:

  - Connector Name : `Nuxt`
  - Connector Server : `https://nuxt.com/mcp`

### Visual Studio Code

<note icon="i-lucide-info">

**Install required extensions** - Ensure you have [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions installed.

</note>

1. Open VS Code and access the Command Palette (Ctrl/Cmd + Shift + P)
2. Type "Preferences: Open Workspace Settings (JSON)" and select it
3. Navigate to your project's `.vscode` folder or create one if it doesn't exist
4. Create or edit the `mcp.json` file with the following configuration:

```json [.vscode/mcp.json]
{
  "servers": {
    "nuxt": {
      "type": "http",
      "url": "https://nuxt.com/mcp"
    }
  }
}
```

### GitHub Copilot Agent

<note icon="i-lucide-info">

**Repository administrator access required** to configure MCP servers for GitHub Copilot coding agent.

</note>

If you have already configured MCP servers in VS Code (replace the `servers` key with `mcpServers` for GitHub Copilot Agent), you can leverage a similar configuration for GitHub Copilot coding agent. You will need to add a `tools` key specifying which tools are available to Copilot.

1. Navigate to your GitHub repository
2. Go to **Settings** > **Code & automation** > **Copilot** > **Coding agent**
3. In the **MCP configuration** section, add the following configuration:
```json
{
  "mcpServers": {
    "nuxt": {
      "type": "http",
      "url": "https://nuxt.com/mcp",
      "tools": ["*"]
    }
  }
}
```
4. Click **Save**

#### Validating the Configuration

To verify the MCP server is configured correctly:

1. Create an issue in your repository and assign it to Copilot
2. Wait for Copilot to create a pull request
3. In the pull request, click **View session** in the "Copilot started work" timeline event
4. Click the ellipsis button (**...**) at the top right, then click **Copilot** in the sidebar
5. Expand the **Start MCP Servers** step to see the configured Nuxt tools

For more information on using MCP with GitHub Copilot coding agent, see [Extend coding agent with MCP](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp).

### Windsurf

1. Open Windsurf and navigate to "Settings" > "Windsurf Settings" > "Cascade"
2. Click the "Manage MCPs" button, then select the "View raw config" option
3. Add the following configuration to your MCP settings:

```json [.codeium/windsurf/mcp_config.json]
{
  "mcpServers": {
    "nuxt": {
      "type": "http",
      "url": "https://nuxt.com/mcp"
    }
  }
}
```

### Zed

1. Open Zed and go to "Settings" > "Open Settings"
2. Navigate to the JSON settings file
3. Add the following context server configuration to your settings:

```json [.config/zed/settings.json]
{
  "context_servers": {
    "nuxt": {
      "source": "custom",
      "command": "npx",
      "args": ["mcp-remote", "https://nuxt.com/mcp"],
      "env": {}
    }
  }
}
```

### Opencode

1. In your project root, create `opencode.json`
2. Add the following configuration:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nuxt": {
      "type": "remote",
      "url": "https://nuxt.com/mcp",
      "enabled": true
    }
  }
}
```

## Prompts Examples

Once configured, you can ask your AI assistant questions like:

- "List all available Nuxt documentation pages"
- "Get the introduction documentation"
- "What's the difference between v3 and v4?"
- "How do I deploy to Vercel?"
- "Show me the latest blog posts"
- "Help me migrate from Nuxt 3 to Nuxt 4"
- "Search documentation about composables"
- "Find deployment guides for Cloudflare"

The AI assistant will use the MCP server to fetch structured JSON data and provide guided assistance for Nuxt development.

---

# Source: https://nuxt.com/raw/docs/3.x/examples/features/meta-tags.md

# Source: https://nuxt.com/raw/docs/4.x/examples/features/meta-tags.md

# Meta Tags

> This example shows how to use the Nuxt helpers and composables for SEO and meta management.

<read-more to="/docs/getting-started/seo-meta">



</read-more>

<sandbox branch="main" dir="examples/features/meta-tags/" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/meta.md

# Source: https://nuxt.com/raw/docs/3.x/bridge/meta.md

# Source: https://nuxt.com/raw/docs/4.x/migration/meta.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/meta.md

# Meta Tags

> Learn how to migrate from Nuxt 2 to Nuxt Bridge new meta tags.

If you need to access the component state with `head`, you should migrate to using [`useHead`](/docs/4.x/api/composables/use-head) .

If you need to use the Options API, there is a `head()` method you can use when you use `defineNuxtComponent`.

## Migration

### Set `bridge.meta`

```js
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    meta: true,
    nitro: false, // If migration to Nitro is complete, set to true
  },
})
```

### Update head properties

In your `nuxt.config`, rename `head` to `app.head`. (Note that objects no longer have a `hid` key for deduplication.)

<code-group>

```ts [Nuxt 2]
export default {
  head: {
    titleTemplate: '%s - Nuxt',
    meta: [
      { charset: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { hid: 'description', name: 'description', content: 'Meta description' },
    ],
  },
}
```

```ts [Nuxt 3]
export default defineNuxtConfig({
  app: {
    head: {
      titleTemplate: '%s - Nuxt',
      meta: [
        { charset: 'utf-8' },
        { name: 'viewport', content: 'width=device-width, initial-scale=1' },
        { name: 'description', content: 'Meta description' },
      ],
    },
  },
})
```

</code-group>

## `useHead` Composables

Nuxt Bridge provides a new Nuxt 3 meta API that can be accessed with a new [`useHead`](/docs/4.x/api/composables/use-head) composable.

```vue
<script setup lang="ts">
useHead({
  title: 'My Nuxt App',
})
</script>
```

<tip>

This [`useHead`](/docs/4.x/api/composables/use-head) composable uses `@unhead/vue` under the hood (rather than `vue-meta`) to manipulate your `<head>`.

</tip>

<warning>

We recommend not using the native Nuxt 2 `head()` properties in addition to [`useHead`](/docs/4.x/api/composables/use-head) , as they may conflict.

</warning>

For more information on how to use this composable, see [the docs](/docs/4.x/getting-started/seo-meta).

## Options API

```vue
<script>
// if using options API `head` method you must use `defineNuxtComponent`
export default defineNuxtComponent({
  head (nuxtApp) {
    // `head` receives the nuxt app but cannot access the component instance
    return {
      meta: [{
        name: 'description',
        content: 'This is my page description.',
      }],
    }
  },
})
</script>
```

<warning>

Possible breaking change: `head` receives the nuxt app but cannot access the component instance. If the code in your `head` tries to access the data object through `this` or `this.$data`, you will need to migrate to the `useHead` composable.

</warning>

## Title Template

If you want to use a function (for full control), then this cannot be set in your nuxt.config, and it is recommended instead to set it within your `/layouts` directory.

```vue [app/layouts/default.vue]
<script setup lang="ts">
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} - Site Title` : 'Site Title'
  },
})
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/examples/routing/middleware.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/middleware.md

# Source: https://nuxt.com/raw/docs/4.x/examples/routing/middleware.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/middleware.md

# middleware

> Nuxt provides middleware to run code before navigating to a particular route.

Nuxt provides a customizable **route middleware** framework you can use throughout your application, ideal for extracting code that you want to run before navigating to a particular route.

There are three kinds of route middleware:

1. Anonymous (or inline) route middleware are defined directly within the page.
2. Named route middleware, placed in the `app/middleware/` and automatically loaded via asynchronous import when used on a page.
3. Global route middleware, placed in the `app/middleware/` with a `.global` suffix and is run on every route change.

The first two kinds of route middleware can be defined in [`definePageMeta`](/docs/4.x/api/utils/define-page-meta).

<note>

Name of middleware are normalized to kebab-case: `myMiddleware` becomes `my-middleware`.

</note>

<note>

Route middleware run within the Vue part of your Nuxt app. Despite the similar name, they are completely different from [server middleware](/docs/4.x/directory-structure/server#server-middleware), which are run in the Nitro server part of your app.

</note>

<video-accordion platform="vimeo" title="Watch a video from Vue School on all 3 kinds of middleware" video-id="761471577">



</video-accordion>

## Usage

Route middleware are navigation guards that receive the current route and the next route as arguments.

```ts [middleware/my-middleware.ts]twoslash
export default defineNuxtRouteMiddleware((to, from) => {
  if (to.params.id === '1') {
    return abortNavigation()
  }
  // In a real app you would probably not redirect every route to `/`
  // however it is important to check `to.path` before redirecting or you
  // might get an infinite redirect loop
  if (to.path !== '/') {
    return navigateTo('/')
  }
})
```

Nuxt provides two globally available helpers that can be returned directly from the middleware.

1. [`navigateTo`](/docs/4.x/api/utils/navigate-to) - Redirects to the given route
2. [`abortNavigation`](/docs/4.x/api/utils/abort-navigation) - Aborts the navigation, with an optional error message.

Unlike [navigation guards](https://router.vuejs.org/guide/advanced/navigation-guards#Global-Before-Guards) from `vue-router`, a third `next()` argument is not passed, and **redirect or route cancellation is handled by returning a value from the middleware**.

Possible return values are:

- nothing (a simple `return` or no return at all) - does not block navigation and will move to the next middleware function, if any, or complete the route navigation
- `return navigateTo('/')` - redirects to the given path and will set the redirect code to [`302` Found](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302) if the redirect happens on the server side
- `return navigateTo('/', { redirectCode: 301 })` - redirects to the given path and will set the redirect code to [`301` Moved Permanently](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/301) if the redirect happens on the server side
- `return abortNavigation()` - stops the current navigation
- `return abortNavigation(error)` - rejects the current navigation with an error

<read-more to="/docs/4.x/api/utils/navigate-to">



</read-more>

<read-more to="/docs/4.x/api/utils/abort-navigation">



</read-more>

<important>

We recommend using the helper functions above for performing redirects or stopping navigation. Other possible return values described in [the vue-router docs](https://router.vuejs.org/guide/advanced/navigation-guards#Global-Before-Guards) may work but there may be breaking changes in future.

</important>

## Middleware Order

Middleware runs in the following order:

1. Global Middleware
2. Page defined middleware order (if there are multiple middleware declared with the array syntax)

For example, assuming you have the following middleware and component:

```bash [app/middleware/ directory]
-| middleware/
---| analytics.global.ts
---| setup.global.ts
---| auth.ts
```

```vue [pages/profile.vue]twoslash
<script setup lang="ts">
definePageMeta({
  middleware: [
    function (to, from) {
      // Custom inline middleware
    },
    'auth',
  ],
})
</script>
```

You can expect the middleware to be run in the following order:

1. `analytics.global.ts`
2. `setup.global.ts`
3. Custom inline middleware
4. `auth.ts`

### Ordering Global Middleware

By default, global middleware is executed alphabetically based on the filename.

However, there may be times you want to define a specific order. For example, in the last scenario, `setup.global.ts` may need to run before `analytics.global.ts`. In that case, we recommend prefixing global middleware with 'alphabetical' numbering.

```bash [Directory structure]
-| middleware/
---| 01.setup.global.ts
---| 02.analytics.global.ts
---| auth.ts
```

<note>

In case you're new to 'alphabetical' numbering, remember that filenames are sorted as strings, not as numeric values. For example, `10.new.global.ts` would come before `2.new.global.ts`. This is why the example prefixes single digit numbers with `0`.

</note>

## When Middleware Runs

If your site is server-rendered or generated, middleware for the initial page will be executed both when the page is rendered and then again on the client. This might be needed if your middleware needs a browser environment, such as if you have a generated site, aggressively cache responses, or want to read a value from local storage.

However, if you want to avoid this behaviour you can do so:

```ts [middleware/example.ts]twoslash
export default defineNuxtRouteMiddleware((to) => {
  // skip middleware on server
  if (import.meta.server) {
    return
  }
  // skip middleware on client side entirely
  if (import.meta.client) {
    return
  }
  // or only skip middleware on initial client load
  const nuxtApp = useNuxtApp()
  if (import.meta.client && nuxtApp.isHydrating && nuxtApp.payload.serverRendered) {
    return
  }
})
```

This is true even if you throw an error in your middleware on the server, and an error page is rendered. The middleware will still run again in the browser.

<note>

Rendering an error page is an entirely separate page load, meaning any registered middleware will run again. You can use [`useError`](/docs/4.x/getting-started/error-handling#useerror) in middleware to check if an error is being handled.

</note>

## Accessing Route in Middleware

Always use the `to` and `from` parameters in your middleware to access the next and previous routes. Avoid using the [`useRoute()`](/docs/4.x/api/composables/use-route) composable in this context altogether.
There is **no concept of a "current route" in middleware**, as middleware can abort a navigation or redirect to a different route. The `useRoute()` composable will always be inaccurate in this context.

<warning>

Sometimes, you might call a composable that uses `useRoute()` internally, which can trigger this warning even if there is no direct call in your middleware.
This leads to the **same issue as above**, so you should structure your functions to accept the route as an argument instead when they are used in middleware.

</warning>

<code-group>

```ts [middleware/access-route.ts]twoslash
// @errors: 2304
export default defineNuxtRouteMiddleware((to) => {
  // passing the route to the function to avoid calling `useRoute()` in middleware
  doSomethingWithRoute(to)

  // ❌ this will output a warning and is NOT recommended
  callsRouteInternally()
})
```

```ts [utils/handle-route.ts]twoslash
// providing the route as an argument so that it can be used in middleware correctly
export function doSomethingWithRoute (route = useRoute()) {
  // ...
}
```

```ts [utils/dont-do-this.ts]twoslash
// ❌ this function is not suitable for use in middleware
export function callsRouteInternally () {
  const route = useRoute()
  // ...
}
```

</code-group>

## Adding Middleware Dynamically

It is possible to add global or named route middleware manually using the [`addRouteMiddleware()`](/docs/4.x/api/utils/add-route-middleware) helper function, such as from within a plugin.

```tstwoslash
export default defineNuxtPlugin(() => {
  addRouteMiddleware('global-test', () => {
    console.log('this global middleware was added in a plugin and will be run on every route change')
  }, { global: true })

  addRouteMiddleware('named-test', () => {
    console.log('this named middleware was added in a plugin and would override any existing middleware of the same name')
  })
})
```

## Example

```bash [Directory Structure]
-| middleware/
---| auth.ts
```

In your page file, you can reference this route middleware:

```vuetwoslash
<script setup lang="ts">
definePageMeta({
  middleware: ['auth'],
  // or middleware: 'auth'
})
</script>
```

Now, before navigation to that page can complete, the `auth` route middleware will be run.

<link-example to="/docs/4.x/examples/routing/middleware">



</link-example>

## Setting Middleware at Build Time

Instead of using `definePageMeta` on each page, you can add named route middleware within the `pages:extend` hook.

```ts [nuxt.config.ts]twoslash
import type { NuxtPage } from 'nuxt/schema'

export default defineNuxtConfig({
  hooks: {
    'pages:extend' (pages) {
      function setMiddleware (pages: NuxtPage[]) {
        for (const page of pages) {
          if (/* some condition */ Math.random() > 0.5) {
            page.meta ||= {}
            // Note that this will override any middleware set in `definePageMeta` in the page
            page.meta.middleware = ['named']
          }
          if (page.children) {
            setMiddleware(page.children)
          }
        }
      }
      setMiddleware(pages)
    },
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/module-anatomy.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/module-anatomy.md

# Understand Module Structure

> Learn how Nuxt modules are structured and how to define them.

There are two types of Nuxt modules:

- published modules are distributed on npm - you can see a list of some community modules on [the Nuxt website](/modules).
- "local" modules exist within a Nuxt project, either [inlined in Nuxt config](/docs/4.x/api/nuxt-config#modules) or within [the `modules` directory](/docs/4.x/directory-structure/modules).

In either case, they work in the same way.

## Define Your Module

<note>

When using the starter, your module definition is available at `src/module.ts`.

</note>

The module definition is the entry point of your module. It's what gets loaded by Nuxt when your module is referenced within a Nuxt configuration.

At a low level, a Nuxt module definition is a simple, potentially asynchronous, function accepting inline user options and a `nuxt` object to interact with Nuxt.

```ts
export default function (inlineOptions, nuxt) {
  // You can do whatever you like here..
  console.log(inlineOptions.token) // `123`
  console.log(nuxt.options.dev) // `true` or `false`
  nuxt.hook('ready', (nuxt) => {
    console.log('Nuxt is ready')
  })
}
```

You can get type hinting for this function using the higher-level `defineNuxtModule` helper provided by [Nuxt Kit](/docs/4.x/guide/going-further/kit).

```ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule((options, nuxt) => {
  nuxt.hook('pages:extend', (pages) => {
    console.log(`Discovered ${pages.length} pages`)
  })
})
```

However, **we do not recommend** using this low-level function definition. Instead, to define a module, **we recommend** using the object-syntax with `meta` property to identify your module, especially when publishing to npm.

This helper makes writing Nuxt modules more straightforward by implementing many common patterns needed by modules, guaranteeing future compatibility and improving the experience for both module authors and users.

```ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    // Usually the npm package name of your module
    name: '@nuxtjs/example',
    // The key in `nuxt.config` that holds your module options
    configKey: 'sample',
    // Compatibility constraints
    compatibility: {
      // Semver version of supported nuxt versions
      nuxt: '>=3.0.0',
    },
  },
  // Default configuration options for your module, can also be a function returning those
  defaults: {},
  // Shorthand sugar to register Nuxt hooks
  hooks: {},
  // Configuration for other modules - this does not ensure the module runs before
  // your module, but it allows you to change the other module's configuration before it runs
  moduleDependencies: {
    'some-module': {
      // You can specify a version constraint for the module. If the user has a different
      // version installed, Nuxt will throw an error on startup.
      version: '>=2',
      // By default moduleDependencies will be added to the list of modules to be installed
      // by Nuxt unless `optional` is set.
      optional: true,
      // Any configuration that should override `nuxt.options`.
      overrides: {},
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`.
      defaults: {},
    },
  },
  // The function holding your module logic, it can be asynchronous
  setup (moduleOptions, nuxt) {
    // ...
  },
})
```

`defineNuxtModule` returns a wrapper function with the lower level `(inlineOptions, nuxt)` module signature. This wrapper function applies defaults and other necessary steps before calling your `setup` function:

- Support `defaults` and `meta.configKey` for automatically merging module options
- Type hints and automated type inference
- Ensure module gets installed only once using a unique key computed from `meta.name` or `meta.configKey`
- Automatically register Nuxt hooks
- Automatically check for compatibility issues based on module meta
- Expose `getOptions` and `getMeta` for internal usage of Nuxt
- Ensuring backward and upward compatibility as long as the module is using `defineNuxtModule` from the latest version of `@nuxt/kit`
- Integration with module builder tooling

## Add Runtime Code

<note>

When using the starter, the runtime directory is `src/runtime/`.

</note>

Modules, like everything in a Nuxt configuration, aren't included in your application runtime. However, you might want your module to provide, or inject runtime code to the application it's installed on. That's what the runtime directory enables you to do.

Inside the runtime directory, you can provide any kind of assets related to the Nuxt app:

- Vue components
- Composables
- [Nuxt plugins](/docs/4.x/directory-structure/app/plugins)

To the [server engine](/docs/4.x/guide/concepts/server-engine), Nitro:

- API routes
- Middlewares
- Nitro plugins

Or any other kind of asset you want to inject in users' Nuxt applications:

- Stylesheets
- 3D models
- Images
- etc.

You'll then be able to inject all those assets inside the application from your [module definition](#define-your-module).

<tip>

Learn more about asset injection in [the recipes section](/docs/4.x/guide/modules/recipes-basics).

</tip>

<warning>

Published modules cannot leverage auto-imports for assets within their runtime directory. Instead, they have to import them explicitly from `#imports` or alike.
<br />

 <br />


Auto-imports are not enabled for files within `node_modules` (the location where a published module will eventually live) for performance reasons.

</warning>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/module-authors.md

# Source: https://nuxt.com/raw/docs/4.x/migration/module-authors.md

# Modules

> Learn how to migrate from Nuxt 2 to Nuxt 3 modules.

## Module Compatibility

Nuxt 3 has a basic backward compatibility layer for Nuxt 2 modules using `@nuxt/kit` auto wrappers. But there are usually steps to follow to make modules compatible with Nuxt 3 and sometimes, using Nuxt Bridge is required for cross-version compatibility.

We have prepared a [Dedicated Guide](/docs/4.x/guide/modules) for authoring Nuxt 3 ready modules using `@nuxt/kit`. Currently best migration path is to follow it and rewrite your modules. Rest of this guide includes preparation steps if you prefer to avoid a full rewrite yet making modules compatible with Nuxt 3.

<tip icon="i-lucide-puzzle" to="/modules">

Explore Nuxt 3 compatible modules.

</tip>

### Plugin Compatibility

Nuxt 3 plugins are **not** fully backward compatible with Nuxt 2.

<read-more to="/docs/4.x/directory-structure/app/plugins">



</read-more>

### Vue Compatibility

Plugins or components using the Composition API need exclusive Vue 2 or Vue 3 support.

By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both Nuxt 2 and 3.

## Module Migration

When Nuxt 3 users add your module, you will not have access to the module container (`this.*`) so you will need to use utilities from `@nuxt/kit` to access the container functionality.

### Test with `@nuxt/bridge`

Migrating to `@nuxt/bridge` is the first and most important step for supporting Nuxt 3.

If you have a fixture or example in your module, add `@nuxt/bridge` package to its config (see [example](/docs/4.x/bridge/overview#update-nuxtconfig))

### Migrate from CommonJS to ESM

Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/docs/4.x/guide/concepts/esm) for more info and upgrading.

### Ensure Plugins Default Export

If you inject a Nuxt plugin that does not have `export default` (such as global Vue plugins), ensure you add `export default () => { }` to the end of it.

<code-group>

```js [Before]
// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)
```

```js [After]
// ~/plugins/vuelidate.js
import Vue from 'vue'
import Vuelidate from 'vuelidate'

Vue.use(Vuelidate)

export default () => { }
```

</code-group>

### Avoid Runtime Modules

With Nuxt 3, Nuxt is now a build-time-only dependency, which means that modules shouldn't attempt to hook into the Nuxt runtime.

Your module should work even if it's only added to [`buildModules`](/docs/4.x/api/nuxt-config#runtimeconfig) (instead of `modules`). For example:

- Avoid updating `process.env` within a Nuxt module and reading by a Nuxt plugin; use [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) instead.
- (*) Avoid depending on runtime hooks like `vue-renderer:*` for production
- (*) Avoid adding `serverMiddleware` by importing them inside the module. Instead, add them by referencing a file path so that they are independent of the module's context

(*) Unless it is for `nuxt dev` purpose only and guarded with `if (nuxt.options.dev) { }`.

<tip>

Continue reading about Nuxt 3 modules in the [Modules Author Guide](/docs/4.x/guide/modules).

</tip>

### Use TypeScript (Optional)

While it is not essential, most of the Nuxt ecosystem is shifting to use TypeScript, so it is highly recommended to consider migration.

<tip>

You can start migration by renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!

</tip>

<tip>

You can use TypeScript syntax for Nuxt 2 and 3 modules and plugins without any extra dependencies.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/module-extend-pages.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/module-extend-pages.md

# Module Extend Pages

> This example defines a new `test` page using `extendPages` within a module.

<read-more to="/docs/guide/going-further/modules">



</read-more>

<sandbox branch="main" dir="examples/advanced/module-extend-pages" file="pages/index.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/module.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/module.md

# nuxt module

> Search and add modules to your Nuxt application with the command line.

Nuxt provides a few utilities to work with [Nuxt modules](/modules) seamlessly.

## nuxt module add

```bash [Terminal]
npx nuxt module add <MODULENAME> [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--skipInstall] [--skipConfig] [--dev]
```

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        MODULENAME
      </code>
    </td>
    
    <td>
      Specify one or more modules to install by name, separated by spaces
    </td>
  </tr>
</tbody>
</table>

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      <code>
        .
      </code>
    </td>
    
    <td>
      Specify the working directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --skipInstall
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Skip npm install
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --skipConfig
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Skip nuxt.config.ts update
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dev
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Install modules as dev dependencies
    </td>
  </tr>
</tbody>
</table>

The command lets you install [Nuxt modules](/modules) in your application with no manual work.

When running the command, it will:

- install the module as a dependency using your package manager
- add it to your [package.json](/docs/4.x/directory-structure/package) file
- update your [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config) file

**Example:**

Installing the [`Pinia`](/modules/pinia) module

```bash [Terminal]
npx nuxt module add pinia
```

## nuxt module search

```bash [Terminal]
npx nuxt module search <QUERY> [--cwd=<directory>] [--nuxtVersion=<2|3>]
```

### Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        QUERY
      </code>
    </td>
    
    <td>
      keywords to search for
    </td>
  </tr>
</tbody>
</table>

### Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      <code>
        .
      </code>
    </td>
    
    <td>
      Specify the working directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --nuxtVersion=<2|3>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Filter by Nuxt version and list compatible modules only (auto detected by default)
    </td>
  </tr>
</tbody>
</table>

The command searches for Nuxt modules matching your query that are compatible with your Nuxt version.

**Example:**

```bash [Terminal]
npx nuxt module search pinia
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/modules.md

# Source: https://nuxt.com/raw/docs/3.x/guide/modules.md

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/modules.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/modules.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/modules.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/modules.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/modules.md

# modules

> Use the modules/ directory to automatically register local modules within your application.

It is a good place to place any local modules you develop while building your application.

The auto-registered files patterns are:

- `modules/*/index.ts`
- `modules/*.ts`

You don't need to add those local modules to your [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) separately.

<code-group>

```ts [modules/hello/index.ts]twoslash
// `nuxt/kit` is a helper subpath import you can use when defining local modules
// that means you do not need to add `@nuxt/kit` to your project's dependencies
import { addComponentsDir, addServerHandler, createResolver, defineNuxtModule } from 'nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'hello',
  },
  setup () {
    const resolver = createResolver(import.meta.url)

    // Add an API route
    addServerHandler({
      route: '/api/hello',
      handler: resolver.resolve('./runtime/api-route'),
    })

    // Add components
    addComponentsDir({
      path: resolver.resolve('./runtime/app/components'),
      pathPrefix: true, // Prefix your exports to avoid conflicts with user code or other modules
    })
  },
})
```

```ts [modules/hello/runtime/api-route.ts]twoslash
export default defineEventHandler(() => {
  return { hello: 'world' }
})
```

</code-group>

When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available.

<note>

Note that all components, pages, composables and other files that would be normally placed in your `app/` directory need to be in `modules/your-module/runtime/app/`. This ensures they can be type-checked properly.

</note>

Modules are executed in the following sequence:

- First, the modules defined in [`nuxt.config.ts`](/docs/4.x/api/nuxt-config#modules-1) are loaded.
- Then, modules found in the `modules/` directory are executed, and they load in alphabetical order.

You can change the order of local module by adding a number to the front of each directory name:

```bash [Directory structure]
modules/
  1.first-module/
    index.ts
  2.second-module.ts
```

<read-more to="/docs/4.x/guide/modules">



</read-more>

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/creating-your-first-module-from-scratch?friend=nuxt">

Watch Vue School video about Nuxt private modules.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/navigate-to.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/navigate-to.md

# navigateTo

> navigateTo is a helper function that programmatically navigates users.

## Usage

`navigateTo` is available on both server side and client side. It can be used within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context), or directly, to perform page navigation.

<warning>

Make sure to always use `await` or `return` on result of `navigateTo` when calling it.

</warning>

<note>

`navigateTo` cannot be used within Nitro routes. To perform a server-side redirect in Nitro routes, use [`sendRedirect`](https://h3.dev/utils/response#redirectlocation-status-statustext) instead.

</note>

### Within a Vue Component

```vue
<script setup lang="ts">
// passing 'to' as a string
await navigateTo('/search')

// ... or as a route object
await navigateTo({ path: '/search' })

// ... or as a route object with query parameters
await navigateTo({
  path: '/search',
  query: {
    page: 1,
    sort: 'asc',
  },
})
</script>
```

### Within Route Middleware

```ts
export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // setting the redirect code to '301 Moved Permanently'
    return navigateTo('/search', { redirectCode: 301 })
  }
})
```

When using `navigateTo` within route middleware, you must **return its result** to ensure the middleware execution flow works correctly.

For example, the following implementation **will not work as expected**:

```ts
export default defineNuxtRouteMiddleware((to, from) => {
  if (to.path !== '/search') {
    // ❌ This will not work as expected
    navigateTo('/search', { redirectCode: 301 })
    return
  }
})
```

In this case, `navigateTo` will be executed but not returned, which may lead to unexpected behavior.

<read-more to="/docs/4.x/directory-structure/app/middleware">



</read-more>

### Navigating to an External URL

The `external` parameter in `navigateTo` influences how navigating to URLs is handled:

- **Without external: true**:
  - Internal URLs navigate as expected.
  - External URLs throw an error.
- **With external: true**:
  - Internal URLs navigate with a full-page reload.
  - External URLs navigate as expected.

#### Example

```vue
<script setup lang="ts">
// will throw an error;
// navigating to an external URL is not allowed by default
await navigateTo('https://nuxt.com')

// will redirect successfully with the 'external' parameter set to 'true'
await navigateTo('https://nuxt.com', {
  external: true,
})
</script>
```

### Opening a Page in a New Tab

```vue
<script setup lang="ts">
// will open 'https://nuxt.com' in a new tab
await navigateTo('https://nuxt.com', {
  open: {
    target: '_blank',
    windowFeatures: {
      width: 500,
      height: 500,
    },
  },
})
</script>
```

## Type

```ts [Signature]
export function navigateTo (
  to: RouteLocationRaw | undefined | null,
  options?: NavigateToOptions,
): Promise<void | NavigationFailure | false> | false | void | RouteLocationRaw

interface NavigateToOptions {
  replace?: boolean
  redirectCode?: number
  external?: boolean
  open?: OpenOptions
}

type OpenOptions = {
  target: string
  windowFeatures?: OpenWindowFeatures
}

type OpenWindowFeatures = {
  popup?: boolean
  noopener?: boolean
  noreferrer?: boolean
} & XOR<{ width?: number }, { innerWidth?: number }>
  & XOR<{ height?: number }, { innerHeight?: number }>
  & XOR<{ left?: number }, { screenX?: number }>
  & XOR<{ top?: number }, { screenY?: number }>
```

## Parameters

### `to`

**Type**: [`RouteLocationRaw`](https://router.vuejs.org/api/interfaces/routelocationoptions) | `undefined` | `null`

**Default**: `'/'`

`to` can be a plain string or a route object to redirect to. When passed as `undefined` or `null`, it will default to `'/'`.

#### Example

```ts
// Passing the URL directly will redirect to the '/blog' page
await navigateTo('/blog')

// Using the route object, will redirect to the route with the name 'blog'
await navigateTo({ name: 'blog' })

// Redirects to the 'product' route while passing a parameter (id = 1) using the route object.
await navigateTo({ name: 'product', params: { id: 1 } })
```

### `options` (optional)

**Type**: `NavigateToOptions`

An object accepting the following properties:

- `replace`
  - **Type**: `boolean`
  - **Default**: `false`
  - By default, `navigateTo` pushes the given route into the Vue Router's instance on the client side.<br />
  
  This behavior can be changed by setting `replace` to `true`, to indicate that given route should be replaced.
- `redirectCode`
  - **Type**: `number`
  - **Default**: `302`
  - `navigateTo` redirects to the given path and sets the redirect code to [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302) by default when the redirection takes place on the server side.<br />
  
  This default behavior can be modified by providing different `redirectCode`. Commonly, [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/301) can be used for permanent redirections.
- `external`
  - **Type**: `boolean`
  - **Default**: `false`
  - Allows navigating to an external URL when set to `true`. Otherwise, `navigateTo` will throw an error, as external navigation is not allowed by default.
- `open`
  - **Type**: `OpenOptions`
  - Allows navigating to the URL using the [open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) method of the window. This option is only applicable on the client side and will be ignored on the server side.<br />
  
  An object accepting the following properties:
  - `target`
    - **Type**: `string`
    - **Default**: `'_blank'`
    - A string, without whitespace, specifying the name of the browsing context the resource is being loaded into.
  - `windowFeatures`
    - **Type**: `OpenWindowFeatures`
    - An object accepting the following properties:<table>
    <thead>
      <tr>
        <th>
          Property
        </th>
        
        <th>
          Type
        </th>
        
        <th>
          Description
        </th>
      </tr>
    </thead>
    
    <tbody>
      <tr>
        <td>
          <code>
            popup
          </code>
        </td>
        
        <td>
          <code>
            boolean
          </code>
        </td>
        
        <td>
          Requests a minimal popup window instead of a new tab, with UI features decided by the browser.
        </td>
      </tr>
      
      <tr>
        <td>
          <code>
            width
          </code>
          
           or <code>
            innerWidth
          </code>
        </td>
        
        <td>
          <code>
            number
          </code>
        </td>
        
        <td>
          Specifies the content area's width (minimum 100 pixels), including scrollbars.
        </td>
      </tr>
      
      <tr>
        <td>
          <code>
            height
          </code>
          
           or <code>
            innerHeight
          </code>
        </td>
        
        <td>
          <code>
            number
          </code>
        </td>
        
        <td>
          Specifies the content area's height (minimum 100 pixels), including scrollbars.
        </td>
      </tr>
      
      <tr>
        <td>
          <code>
            left
          </code>
          
           or <code>
            screenX
          </code>
        </td>
        
        <td>
          <code>
            number
          </code>
        </td>
        
        <td>
          Sets the horizontal position of the new window relative to the left edge of the screen.
        </td>
      </tr>
      
      <tr>
        <td>
          <code>
            top
          </code>
          
           or <code>
            screenY
          </code>
        </td>
        
        <td>
          <code>
            number
          </code>
        </td>
        
        <td>
          Sets the vertical position of the new window relative to the top edge of the screen.
        </td>
      </tr>
      
      <tr>
        <td>
          <code>
            noopener
          </code>
        </td>
        
        <td>
          <code>
            boolean
          </code>
        </td>
        
        <td>
          Prevents the new window from accessing the originating window via <code>
            window.opener
          </code>
          
          .
        </td>
      </tr>
      
      <tr>
        <td>
          <code>
            noreferrer
          </code>
        </td>
        
        <td>
          <code>
            boolean
          </code>
        </td>
        
        <td>
          Prevents the Referer header from being sent and implicitly enables <code>
            noopener
          </code>
          
          .
        </td>
      </tr>
    </tbody>
    </table>
    
    <br />
    
    Refer to the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#windowfeatures) for more detailed information on the **windowFeatures** properties.

---

# Source: https://nuxt.com/raw/deploy/netlify.md

# Netlify

> Deploy your Nuxt Application to Netlify infrastructure.

<tip>

**Zero Configuration ✨**

<br />

Integration with Netlify is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

## Setup

Nuxt will auto-detect that you are in a [Netlify](https://www.netlify.com) build environment and build an optimized version of your server.

For new sites, Netlify will detect that you are using Nuxt 3 and set the publish directory to `dist` and build command to `npm run build`.

<note>

If you are upgrading an existing site from Nuxt 2 you should check these and update them if needed.

</note>

If you want to add custom redirects, you can do so with [`routeRules`](/docs/guide/concepts/rendering#hybrid-rendering) or by adding a [`_redirects`](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file) file to your `public` directory.

<tip color="green" icon="i-lucide-check-circle">

For deployment, just push to your git repository [as you would normally do for Netlify](https://docs.netlify.com/configure-builds/get-started/).

</tip>

## Netlify Edge Functions

<read-more target="_blank" to="https://www.netlify.com/blog/announcing-serverless-compute-with-edge-functions">

Netlify Edge Functions use Deno and the powerful V8 JavaScript runtime to let you run globally distributed functions for the fastest possible response times.

</read-more>

Set the following environment variable to run Nuxt on Edge Functions:

```bash
SERVER_PRESET=netlify_edge
```

## On-demand Builders

On-demand Builders are serverless functions used to generate web content as needed that’s automatically cached on Netlify’s Edge CDN.

They enable you to build pages for your site when a user visits them for the first time and then cache them at the edge for subsequent visits until the next deployment.

<read-more target="_blank" to="https://docs.netlify.com/configure-builds/on-demand-builders/">

Read More about Netlify on-demand builders

</read-more>

Set the following environment variable to enable on-demand builders:

```bash
SERVER_PRESET=netlify_builder
```

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/netlify">

Head over **Nitro documentation** to learn more about the netlify deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/blog/new-website.md

# A New Website

> We are thrilled to release the new nuxt.com, powered by Nuxt UI and now open source.

Nuxt.com is the main entry point when you want to learn Nuxt. With **more than 300k visitors every month**, it was time to give it a new look and feel.

## New Design

We are back to the original colors of Nuxt, with a navy background (`#020420`) and its signature shiny green (`#00DC82`).

<nuxt-img alt="Nuxt Website Screenshot" className="rounded-lg,border,border-gray-700" height="497" src="/assets/blog/website/nuxt-website.png" width="832">



</nuxt-img>

<read-more to="/design-kit" icon="i-lucide-palette">

Discover the **Nuxt Design Kit** as well as our **Logo History**.

</read-more>

We wanted to achieve a consistent design across all our official documentations:

<div className="grid,sm:grid-cols-2,gap-4">
<nuxt-link className="hover:border-transparent" target="_blank" to="https://image.nuxt.com">
<nuxt-img alt="Nuxt Image" className="m-0,border,rounded-md,border-gray-700" height="255" src="/assets/blog/website/nuxt-image.png" width="408">



</nuxt-img>
</nuxt-link>

<nuxt-link className="hover:border-transparent" target="_blank" to="https://content.nuxt.com">
<nuxt-img alt="Nuxt Content" className="m-0,border,rounded-md,border-gray-700" height="255" src="/assets/blog/website/nuxt-content.png" width="408">



</nuxt-img>
</nuxt-link>

<nuxt-link className="hover:border-transparent" target="_blank" to="https://devtools.nuxt.com">
<nuxt-img alt="Nuxt DevTools" className="m-0,border,rounded-md,border-gray-700" height="255" src="/assets/blog/website/nuxt-devtools.png" width="408">



</nuxt-img>
</nuxt-link>

<nuxt-link className="hover:border-transparent" target="_blank" to="https://ui.nuxt.com">
<nuxt-img alt="Nuxt UI" className="m-0,border,rounded-md,border-gray-700" height="255" src="/assets/blog/website/nuxt-ui.png" width="408">



</nuxt-img>
</nuxt-link>
</div>

We really love this new design and hope you do too. **This is only the first step toward many improvements coming to the website.**

## Improved Navigation

From now on, you can easily jump between the five main documentation categories:

<video :controls="true" className="rounded,dark:border,dark:border-gray-700" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1697548111/nuxt3/nuxt-website-docs-nav.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1697548111/nuxt3/nuxt-website-docs-nav.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697548111/nuxt3/nuxt-website-docs-nav.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697548111/nuxt3/nuxt-website-docs-nav.ogg" type="video/ogg" />
</video>

On the right side, you can see the table of contents as well as community shortcuts: Edit this page, Chat on Discord, etc.

<video :controls="true" className="rounded,dark:border,dark:border-gray-700" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1697549697/nuxt3/nuxt-website-docs-aside.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1697549697/nuxt3/nuxt-website-docs-aside.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697549697/nuxt3/nuxt-website-docs-aside.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697549697/nuxt3/nuxt-website-docs-aside.ogg" type="video/ogg" />
</video>

## Source Code Buttons

When looking at Nuxt built-in [components](/docs/api/components), [composables](/docs/api/composables), [utils](/docs/api/utils), [commands](/docs/api/commands) and [kit utilities](/docs/api/kit), you can now jump to the source code by clicking on the <u-button color="gray" icon="i-simple-icons-github" size="xs">

Source

</u-button>

 button.

<nuxt-img alt="Nuxt Source Code Button" className="border,rounded,border-gray-700" height="343" src="/assets/blog/website/nuxt-website-source-button.png" width="818">



</nuxt-img>

<read-more to="/docs/api/components/nuxt-link">

Checkout an example on `<NuxtLink>` documentation page.

</read-more>

## Improved Search Feature

You may notice a new modal when hitting <kbd value="meta">



</kbd>

 <kbd value="K">



</kbd>

. We leverage the Nuxt UI [`<CommandPalette>`](https://ui.nuxt.com/components/command-palette) components combined with Nuxt Content data (search & navigation) to provide a better search experience.

With the command palette, you can:

- Jump to a page
- Search in the documentation
- Search a module
- Switch the color mode

We plan to add more commands soon.

<video :controls="true" className="rounded,dark:border,dark:border-gray-700" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1697550571/nuxt3/nuxt-website-search.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1697550571/nuxt3/nuxt-website-search.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697550571/nuxt3/nuxt-website-search.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697550571/nuxt3/nuxt-website-search.ogg" type="video/ogg" />
</video>

## Migration to Nuxt UI

The new website is powered by [Nuxt UI](https://ui.nuxt.com), our UI library tailored made for Nuxt and built on top of [Tailwind CSS](https://tailwindcss.com) & [Headless UI](https://headlessui.com/).

The website also uses [Nuxt UI Pro](https://ui.nuxt.com/pro), a set of premium components built on top of Nuxt UI to create beautiful & responsive Nuxt applications in minutes.

It includes components such as `<UHeader>`, `<UFooter>`, `<ULandingHero>`, `<ULandingCard>` and more.

<note>

We plan to launch the full documentation of Nuxt UI Pro at the end of October. If you cannot wait and want early access, you can already [purchase a license](https://ui.nuxt.com/pro/purchase) now and get access to our private repository on GitHub.

</note>

This [migration](https://github.com/nuxt/nuxt.com/pull/1365) was a great opportunity to improve Nuxt UI & UI Pro and fix some bugs, as well as a difference of <span className="text-primary">

+9,004

</span>

 / <span className="text-error">

-23,113

</span>

 lines of code changed.

<read-more to="https://ui.nuxt.com" icon="i-simple-icons-nuxtdotjs" target="_blank">

Read more about **Nuxt UI**.

</read-more>

## Open Graph Images

We are big fans of having a custom image when we share a link on social media. That's why we have added OG images on all our documentation pages.

Example of the [Installation page](/docs/getting-started/installation):

![Nuxt OG Image](/__og-image__/image/docs/getting-started/introduction/og.png)<read-more to="https://nuxtseo.com/og-image/getting-started/installation" target="_blank">

Discover the **Nuxt OG Image** module.

</read-more>

## Available on GitHub

We are proud to announce that the website is **now open source** and available on GitHub.

<read-more to="https://github.com/nuxt/nuxt.com" icon="i-simple-icons-github" target="_blank" color="gray">

Check out `nuxt/nuxt.com` on GitHub.

</read-more>

## What's next?

This new website is the beginning of upcoming changes we are planing, some of them are:

- Team & Contributors pages
- Integrations page to showcase all the possibilities with Nuxt: Hosting, CMS, Database, etc.
- Templates page (currently [nuxt.new](https://nuxt.new)) to list official and community starters
- And more...

**We are looking forward to your feedback on Twitter, Discord or GitHub**.

Thank you for reading this blog post, and happy Nuxting 🤟

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/nightly-release-channel.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/nightly-release-channel.md

# Nightly Release Channel

> The nightly release channel allows using Nuxt built directly from the latest commits to the repository.

Nuxt lands commits, improvements, and bug fixes every day. You can opt in to test them earlier before the next release.

After a commit is merged into the `main` branch of [nuxt/nuxt](https://github.com/nuxt/nuxt) and **passes all tests**, we trigger an automated npm release, using GitHub Actions.

You can use these 'nightly' releases to beta test new features and changes.

The build and publishing method and quality of these 'nightly' releases are the same as stable ones. The only difference is that you should often check the GitHub repository for updates. There is a slight chance of regressions not being caught during the review process and by the automated tests. Therefore, we internally use this channel to double-check everything before each release.

<note>

Features that are only available on the nightly release channel are marked with an alert in the documentation.

</note>

<warning>

The `latest` nightly release channel is currently tracking the Nuxt v4 branch, meaning that it is particularly likely to have breaking changes right now — be careful! You can opt in to the 3.x branch nightly releases with `"nuxt": "npm:nuxt-nightly@3x"`.

</warning>

## Opting In

Update `nuxt` dependency inside `package.json`:

```diff [package.json]
{
  "devDependencies": {
--    "nuxt": "^4.0.0"
++    "nuxt": "npm:nuxt-nightly@latest"
  }
}
```

Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock` or `bun.lockb`) and reinstall dependencies.

## Opting Out

Update `nuxt` dependency inside `package.json`:

```diff [package.json]
{
  "devDependencies": {
--    "nuxt": "npm:nuxt-nightly@latest"
++    "nuxt": "^4.0.0"
  }
}
```

Remove lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock` or `bun.lockb`) and reinstall dependencies.

## Using Nightly `@nuxt/cli`

To try the latest version of [nuxt/cli](https://github.com/nuxt/cli):

```bash [Terminal]
npx @nuxt/cli-nightly@latest [command]
```

<read-more to="/docs/4.x/api/commands">

Read more about the available commands.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/bridge/nitro.md

# Source: https://nuxt.com/raw/docs/3.x/api/kit/nitro.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/nitro.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/nitro.md

# Nitro

> Nuxt Kit provides a set of utilities to help you work with Nitro. These functions allow you to add server handlers, plugins, and prerender routes.

Nitro is an open source TypeScript framework to build ultra-fast web servers. Nuxt uses Nitro as its server engine. You can use `useNitro` to access the Nitro instance, `addServerHandler` to add a server handler, `addDevServerHandler` to add a server handler to be used only in development mode, `addServerPlugin` to add a plugin to extend Nitro's runtime behavior, and `addPrerenderRoutes` to add routes to be prerendered by Nitro.

## `addServerHandler`

Adds a Nitro server handler. Use this if you want to create server middleware or a custom route.

### Usage

```tstwoslash
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})
```

### Type

```ts
function addServerHandler (handler: NitroEventHandler): void
```

### Parameters

**handler**: A handler object with the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        handler
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Path to event handler.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        route
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path prefix or route. If an empty string used, will be used as a middleware.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        middleware
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Specifies this is a middleware handler. Middleware are called on every route and should normally return nothing to pass to the next handlers.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        lazy
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Use lazy loading to import the handler. This is useful when you only want to load the handler on demand.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        method
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Router method matcher. If handler name contains method name, it will be used as a default value.
    </td>
  </tr>
</tbody>
</table>

### Examples

#### Basic Usage

You can use `addServerHandler` to add a server handler from your module.

<code-group>

```ts [module.ts]twoslash
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})
```

```ts [runtime/robots.get.ts]twoslash
export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`,
  }
})
```

</code-group>

When you access `/robots.txt`, it will return the following response:

```txt
User-agent: *
Disallow: /
```

## `addDevServerHandler`

Adds a Nitro server handler to be used only in development mode. This handler will be excluded from production build.

### Usage

```tstwoslash
import { defineEventHandler } from 'h3'
import { addDevServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addDevServerHandler({
      handler: defineEventHandler(() => {
        return {
          body: `Response generated at ${new Date().toISOString()}`,
        }
      }),
      route: '/_handler',
    })
  },
})
```

### Type

```tstwoslash
// @errors: 2391
import type { NitroDevEventHandler } from 'nitropack/types'
// ---cut---
function addDevServerHandler (handler: NitroDevEventHandler): void
```

### Parameters

**handler**: A handler object with the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        handler
      </code>
    </td>
    
    <td>
      <code>
        EventHandler
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Event handler.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        route
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path prefix or route. If an empty string used, will be used as a middleware.
    </td>
  </tr>
</tbody>
</table>

### Examples

#### Basic Usage

In some cases, you may want to create a server handler specifically for development purposes, such as a Tailwind config viewer.

```ts
import { joinURL } from 'ufo'
import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (options, nuxt) {
    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')

    // @ts-expect-error - tailwind-config-viewer does not have correct types
    const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
    const viewerDevMiddleware = createServer({ tailwindConfigProvider: () => options, routerPrefix: route }).asMiddleware()

    addDevServerHandler({ route, handler: viewerDevMiddleware })
  },
})
```

## `useNitro`

Returns the Nitro instance.

<warning>

You can call `useNitro()` only after `ready` hook.

</warning>

<note>

Changes to the Nitro instance configuration are not applied.

</note>

### Usage

```ts
import { defineNuxtModule, useNitro } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      // Do something with Nitro instance
    })
  },
})
```

### Type

```ts
function useNitro (): Nitro
```

## `addServerPlugin`

Add plugin to extend Nitro's runtime behavior.

<tip>

You can read more about Nitro plugins in the [Nitro documentation](https://nitro.build/guide/plugins).

</tip>

<warning>

It is necessary to explicitly import `defineNitroPlugin` from `nitropack/runtime` within your plugin file. The same requirement applies to utilities such as `useRuntimeConfig`.

</warning>

### Usage

```tstwoslash
import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./runtime/plugin.ts'))
  },
})
```

### Type

```ts
function addServerPlugin (plugin: string): void
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        plugin
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Path to the plugin. The plugin must export a default function that accepts the Nitro instance as an argument.
    </td>
  </tr>
</tbody>
</table>

### Examples

<code-group>

```ts [module.ts]
import { addServerPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./runtime/plugin.ts'))
  },
})
```

```ts [runtime/plugin.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('on request', event.path)
  })

  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
    console.log('on response', event.path, { body })
  })

  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
    console.log('on after response', event.path, { body })
  })
})
```

</code-group>

## `addPrerenderRoutes`

Add routes to be prerendered to Nitro.

### Usage

```ts
import { addPrerenderRoutes, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-sitemap',
    configKey: 'sitemap',
  },
  defaults: {
    sitemapUrl: '/sitemap.xml',
    prerender: true,
  },
  setup (options) {
    if (options.prerender) {
      addPrerenderRoutes(options.sitemapUrl)
    }
  },
})
```

### Type

```ts
function addPrerenderRoutes (routes: string | string[]): void
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        routes
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          string[]
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      A route or an array of routes to prerender.
    </td>
  </tr>
</tbody>
</table>

## `addServerImports`

Add imports to the server. It makes your imports available in Nitro without the need to import them manually.

<warning>

If you want to provide a utility that works in both server and client contexts and is usable in the [`shared/`](/docs/4.x/directory-structure/shared) directory, the function must be imported from the same source file for both [`addImports`](/docs/4.x/api/kit/autoimports#addimports) and `addServerImports` and should have identical signature. That source file should not import anything context-specific (i.e., Nitro context, Nuxt app context) or else it might cause errors during type-checking.

</warning>

### Usage

```tstwoslash
import { addServerImports, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options) {
    const names = [
      'useStoryblok',
      'useStoryblokApi',
      'useStoryblokBridge',
      'renderRichText',
      'RichTextSchema',
    ]

    names.forEach(name =>
      addServerImports({ name, as: name, from: '@storyblok/vue' }),
    )
  },
})
```

### Type

```ts
function addServerImports (dirs: Import | Import[]): void
```

### Parameters

`imports`: An object or an array of objects with the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        name
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Import name to be detected.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Module specifier to import from.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        priority
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Priority of the import; if multiple imports have the same name, the one with the highest priority will be used.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        disabled
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If this import is disabled.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meta
      </code>
    </td>
    
    <td>
      <code>
        Record<string, any>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Metadata of the import.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If this import is a pure type import.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        typeFrom
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Use this as the <code>
        from
      </code>
      
       value when generating type declarations.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        as
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Import as this name.
    </td>
  </tr>
</tbody>
</table>

## `addServerImportsDir`

Add a directory to be scanned for auto-imports by Nitro.

### Usage

```tstwoslash
import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})
```

### Type

```ts
function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean }): void
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dirs
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          string[]
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      A directory or an array of directories to register to be scanned by Nitro.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        opts
      </code>
    </td>
    
    <td>
      <code>
        { prepend?: boolean }
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Options for the import directory. If <code>
        prepend
      </code>
      
       is <code>
        true
      </code>
      
      , the directory is added to the beginning of the scan list.
    </td>
  </tr>
</tbody>
</table>

### Examples

You can use `addServerImportsDir` to add a directory to be scanned by Nitro. This is useful when you want Nitro to auto-import functions from a custom server directory.

<code-group>

```ts [module.ts]twoslash
import { addServerImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})
```

```ts [runtime/server/composables/index.ts]twoslash
export function useApiSecret () {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}
```

</code-group>

You can then use the `useApiSecret` function in your server code:

```ts [runtime/server/api/hello.ts]twoslash
const useApiSecret = (): string => ''
// ---cut---
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // Do something with the apiSecret
})
```

## `addServerScanDir`

Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered
just like the `~/server` folder is.

<note>

Only `~/server/api`, `~/server/routes`, `~/server/middleware`, and `~/server/utils` are scanned.

</note>

### Usage

```tstwoslash
import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

### Type

```ts
function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean }): void
```

### Parameters

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dirs
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="sZSNi">
          string[]
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      A directory or an array of directories to register to be scanned for by Nitro as server dirs.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        opts
      </code>
    </td>
    
    <td>
      <code>
        { prepend?: boolean }
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Options for the import directory. If <code>
        prepend
      </code>
      
       is <code>
        true
      </code>
      
      , the directory is added to the beginning of the scan list.
    </td>
  </tr>
</tbody>
</table>

### Examples

You can use `addServerScanDir` to add a directory to be scanned by Nitro. This is useful when you want to add a custom server directory.

<code-group>

```ts [module.ts]twoslash
import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

```ts [runtime/server/utils/index.ts]twoslash
export function hello () {
  return 'Hello from server utils!'
}
```

</code-group>

You can then use the `hello` function in your server code.

```ts [runtime/server/api/hello.ts]twoslash
function hello () {
  return 'Hello from server utils!'
}
// ---cut---
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/node_modules.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/node_modules.md

# node_modules

> The package manager stores the dependencies of your project in the node_modules/ directory.

The package manager ([`npm`](https://docs.npmjs.com/cli/commands/npm/) or [`yarn`](https://yarnpkg.com) or [`pnpm`](https://pnpm.io/cli/install) or [`bun`](https://bun.com/package-manager) or [`deno`](https://docs.deno.com/runtime/getting_started/installation/)) creates this directory to store the dependencies of your project.

<important>

This directory should be added to your [`.gitignore`](/docs/4.x/directory-structure/gitignore) file to avoid pushing the dependencies to your repository.

</important>

---

# Source: https://nuxt.com/raw/deploy/northflank.md

# Northflank

> Deploy your Nuxt Application to Northflank infrastructure.

Nuxt supports deploying on [Northflank](https://www.northflank.com) with minimal configuration.

## Setup

1. Link your [Git provider](https://northflank.com/docs/v1/application/getting-started/link-your-git-account) and [create a new project](https://northflank.com/docs/v1/application/getting-started/create-a-project) in Northflank.
2. In your project, create a [Service](https://northflank.com/docs/v1/application/getting-started/build-and-deploy-your-code) and connect it to your Nuxt repository.
3. Ensure your package.json includes a start script that runs the Nuxt production server.

```json [package.json]
{
  "scripts": {
    "start": "node .output/server/index.mjs"
  }
}
```

1. Click "Create Service" to build and deploy your Nuxt app.

<read-more target="_blank" to="https://northflank.com/docs">

For more information, refer to the **Northflank documentation**.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/nuxt-app.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/nuxt-app.md

# NuxtApp

> In Nuxt, you can access runtime app context within composables, components and plugins.

In Nuxt, you can access runtime app context within composables, components and plugins.

<read-more to="https://v2.nuxt.com/docs/internals-glossary/context/#the-context" target="_blank">

In Nuxt 2, this was referred to as **Nuxt context**.

</read-more>

## Nuxt App Interface

<read-more to="/docs/4.x/guide/going-further/internals#the-nuxtapp-interface">

Jump over the `NuxtApp` interface documentation.

</read-more>

## The Nuxt Context

Many composables and utilities, both built-in and user-made, may require access to the Nuxt instance. This doesn't exist everywhere on your application, because a fresh instance is created on every request.

Currently, the Nuxt context is only accessible in [plugins](/docs/4.x/directory-structure/app/plugins), [Nuxt hooks](/docs/4.x/guide/going-further/hooks), [Nuxt middleware](/docs/4.x/directory-structure/app/middleware) (if wrapped in `defineNuxtRouteMiddleware`), and [setup functions](https://vuejs.org/api/composition-api-setup) (in pages and components).

If a composable is called without access to the context, you may get an error stating that 'A composable that requires access to the Nuxt instance was called outside of a plugin, Nuxt hook, Nuxt middleware, or Vue setup function.' In that case, you can also explicitly call functions within this context by using [`nuxtApp.runWithContext`](/docs/4.x/api/composables/use-nuxt-app#runwithcontext).

## Accessing NuxtApp

Within composables, plugins and components you can access `nuxtApp` with [`useNuxtApp()`](/docs/4.x/api/composables/use-nuxt-app):

```ts [app/composables/useMyComposable.ts]
export function useMyComposable () {
  const nuxtApp = useNuxtApp()
  // access runtime nuxt app instance
}
```

If your composable does not always need `nuxtApp` or you simply want to check if it is present or not, since [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) throws an exception, you can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead.

Plugins also receive `nuxtApp` as the first argument for convenience.

<read-more to="/docs/4.x/directory-structure/app/plugins">



</read-more>

## Providing Helpers

You can provide helpers to be usable across all composables and application. This usually happens within a Nuxt plugin.

```ts
const nuxtApp = useNuxtApp()
nuxtApp.provide('hello', name => `Hello ${name}!`)

console.log(nuxtApp.$hello('name')) // Prints "Hello name!"
```

<read-more to="/docs/4.x/directory-structure/app/plugins#providing-helpers">

It is possible to inject helpers by returning an object with a `provide` key in plugins.

</read-more>

<read-more to="https://v2.nuxt.com/docs/directory-structure/plugins/#inject-in-root--context" target="_blank">

In Nuxt 2 plugins, this was referred to as **inject function**.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-client-fallback.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-client-fallback.md

# <NuxtClientFallback>

> Nuxt provides the <NuxtClientFallback> component to render its content on the client if any of its children trigger an error in SSR

Nuxt provides the `<NuxtClientFallback>` component to render its content on the client if any of its children trigger an error in SSR.

<note to="/docs/4.x/guide/going-further/experimental-features#clientfallback">

This component is experimental and in order to use it you must enable the `experimental.clientFallback` option in your `nuxt.config`.

</note>

```vue [app/pages/example.vue]
<template>
  <div>
    <Sidebar />
    <!-- this component will be rendered on client-side -->
    <NuxtClientFallback fallback-tag="span">
      <Comments />
      <BrokeInSSR />
    </NuxtClientFallback>
  </div>
</template>
```

## Events

- `@ssr-error`: Event emitted when a child triggers an error in SSR. Note that this will only be triggered on the server.```vue
<template>
  <NuxtClientFallback @ssr-error="logSomeError">
    <!-- ... -->
  </NuxtClientFallback>
</template>
```

## Props

- `placeholderTag` | `fallbackTag`: Specify a fallback tag to be rendered if the slot fails to render on the server.

  - **type**: `string`
  - **default**: `div`
- `placeholder` | `fallback`: Specify fallback content to be rendered if the slot fails to render.

  - **type**: `string`
- `keepFallback`: Keep the fallback content if it failed to render server-side.

  - **type**: `boolean`
  - **default**: `false`

<warning icon="i-ph-warning-duotone">

The `placeholder` and `fallback` props render content as raw HTML. Do not pass untrusted user input to these props as it may lead to XSS vulnerabilities. Use the `#fallback` or `#placeholder` slots instead for dynamic content that needs proper escaping.

</warning>

```vue
<template>
  <!-- render <span>Hello world</span> server-side if the default slot fails to render -->
  <NuxtClientFallback
    fallback-tag="span"
    fallback="Hello world"
  >
    <BrokeInSSR />
  </NuxtClientFallback>
</template>
```

## Slots

- `#fallback`: specify content to be displayed server-side if the slot fails to render.

```vue
<template>
  <NuxtClientFallback>
    <!-- ... -->
    <template #fallback>
      <!-- this will be rendered on server side if the default slot fails to render in ssr -->
      <p>Hello world</p>
    </template>
  </NuxtClientFallback>
</template>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/nuxt-config.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/nuxt-config.md

# Source: https://nuxt.com/raw/docs/4.x/api/nuxt-config.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/nuxt-config.md

# nuxt.config.ts

> Nuxt can be easily configured with a single nuxt.config file.

The `nuxt.config` file extension can either be `.js`, `.ts` or `.mjs`.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  // My Nuxt config
})
```

<tip>

`defineNuxtConfig` helper is globally available without import.

</tip>

You can explicitly import `defineNuxtConfig` from `nuxt/config` if you prefer:

```ts [nuxt.config.ts]twoslash
import { defineNuxtConfig } from 'nuxt/config'

export default defineNuxtConfig({
  // My Nuxt config
})
```

<read-more to="/docs/4.x/api/configuration/nuxt-config">

Discover all the available options in the **Nuxt configuration** documentation.

</read-more>

To ensure your configuration is up to date, Nuxt will make a full restart when detecting changes in the main configuration file, the [`.env`](/docs/4.x/directory-structure/env), [`.nuxtignore`](/docs/4.x/directory-structure/nuxtignore) and [`.nuxtrc`](/docs/4.x/directory-structure/nuxtrc) dotfiles.

---

# Source: https://nuxt.com/raw/blog/nuxt-devtools-v1-0.md

# Nuxt DevTools v1.0

> Nuxt DevTools v1.0 is out, generally available to all Nuxt projects!

We are thrilled to announce the release of [Nuxt DevTools v1.0](https://github.com/nuxt/devtools)! 🎉

<tip>

Since this release, Nuxt DevTools is now enabled with [Nuxt v3.8](/blog/v3-8) and onwards by default. Generally available to all Nuxt projects!

</tip>

You can start playing with it by upgrading to the latest Nuxt, and press `Shift + Option + D` (macOS) or `Shift + Alt + D` (Windows) in your browser to open the DevTools. By default the floating panel is hidden to reduce the distraction. You can enable it inside Nuxt DevTools settings page, or explicitly enabled it in your config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  devtools: {
    enabled: true
  }
})
```

## The Reasons We Built Nuxt DevTools

Over the recent years, there has been an increasing focus on Developer Experience (DX). Tools and frameworks have been striving to improve the DX. Along the way, Nuxt introduced many innovative features and conventions to make your day-to-day development easier and more efficient.

For example, [file-based routing](/docs/guide/directory-structure/pages), [layout system](/docs/guide/directory-structure/layouts), [plugins](/docs/guide/directory-structure/plugins), [route middleware](/docs/guide/directory-structure/middleware), [composables auto-import](/docs/guide/concepts/auto-imports), [file-based server APIs](https://nitro.unjs.io/guide/routing), [powerful module system](/modules) and many more.

![List of Nuxt features that enhance developer experience](/assets/blog/devtools/slide-dx.png)

Nuxt is capable of creating various range of applications, from simple hobby projects to large scale applications, from simple client-rendered single-page applications to hybrid rendered sites with serverless functions on edge, etc. We provide those features and conventions to make it easier to support all those use cases and scenarios.

### The Problem

Out of all these benefits of having a powerful framework, we have to made some trade-offs. Sometimes, we have to sacrifice a bit of the transparency of the underlying implementation to make things easier to use.

!["Transparency" as the trade offs of having "Conventions", "Abstractions", "Sensible Defaults" and "Normalizations"](/assets/blog/devtools/slide-transparency.png)

Conventional abstractions are great things to transfer implementation complexity and make things easier to get more focus when building. On the other hand, they can also add extra burden for users to learn and understand what's going on under the hood. Leading also to implicitness, like where a auto-imported component is from, or how many modules is using a certain component, etc. It can also make things hard to debug.

Trade-offs are inevitable. Generally we believe those trade-offs are worth it, as they would help organizing users' codebase and make it easier to maintain in the long run. In the meantime, we also want to compensate the transparency we lost by providing a tool to help you understand what's going on under the hood and make the learning curve smoother.

That's where Nuxt DevTools comes in! We [first introduced it](/blog/introducing-nuxt-devtools) in February 2023 to experiment with the idea. After a few months of exploration and development, from surprisingly positive feedbacks from the community, this idea has been proven to be useful and we decided to make it a core part of your Nuxt development experience.

## Features

[Nuxt DevTools](https://github.com/nuxt/devtools) is a set of visual tools to help you understand your Nuxt app and improve the developer experience even further. It's created to provide better transparency between Nuxt and your app, find performance bottlenecks and help you manage your app and configuration.

### In App DevTools

From the overview, Nuxt DevTools is an in-app DevTools that lives alongside your app. It will show up as a floating panel that you can click to open.

<article-video cloudinary="v1700132388/devtools/0-intro_ilgwel">



</article-video>

We believe this is a better approach than the traditional browser extension DevTools, as it's:

- **Works across all browsers**, and even on mobile devices! - The capability of browser extension DevTools are limited by the APIs each browsers provides, and also maintain multiple extensions would require a lot of effort. This approach would allow us to focus more on the functionality and features, while having it accessible to users on any browsers and devices.
- **Build tools integrations** - Tranditionally browser extension DevTools are only able to access the runtime context of your app and have no access to the build tools. Having the DevTools comes with Nuxt, allows us to communicate with the build tools and provide much more insights and features.
- **Avoid layout shifts** - Having the DevTools as a floating panel would avoid the layout shifts when toggling the DevTools.

### Pages View

To help improving the implicitness of file-based routing, we introduced the Pages View in DevTools. It lists all the pages that have been registered in your app, that you can easily test and navigate between them.

<article-video cloudinary="v1700132393/devtools/1-pages_kkbecx">



</article-video>

### Components View

The Components tab shows all the components you are using in your app and where they are from. You can also search for them and go to the source code.

It also provides a graph view that show the relationship between components. You can filter the components to see the dependencies of a specific component. This could help to identify unintended dependencies and improve the performance and bundle size of pages.

<article-video cloudinary="v1700132398/devtools/2-components_paj0uv">



</article-video>

### Composables View

Composables view shows all the auto-imported composables registered to Nuxt. You can see which files are importing them, and where they are from. Some entries can also provide short descriptions and documentation links.

<article-video cloudinary="v1700132395/devtools/3-imports_qhahdf">



</article-video>

### Modules Management

The Modules tab shows all the modules that are registered in your app, with the links to their documentations and repositories.

We also provide the ability for you to search for and explore the modules from the community. And install them with a single click!

<article-video cloudinary="v1700132389/devtools/4-modules_v5ha5u">



</article-video>

### Static Assets Management

The Assets tab shows all the static assets under your `public` directory. It supports previewing images, videos, fonts, PDFs, and other files, that you can easily copy the URL or code snippet to use in your app. You may also drag and drop files to upload them directly from Nuxt DevTools.

<article-video cloudinary="v1700132394/devtools/5-assets_mpzyrs">



</article-video>

### Runtime Configs Editor

The Runtime Configs tab shows the runtime configs of your app and provides an interactive editor for you to play with different values.

<article-video cloudinary="v1700132393/devtools/6-runtime-configs_fzlrik">



</article-video>

### Payload Editor

Similar to the Runtime Configs Editor, the Payload Editor allows you to edit the payload from composables like [`useState`](/docs/api/composables/use-state) and [`useFetch`](/docs/api/composables/use-fetch) to see what have been passed from server to client on server-side rendering.

<article-video cloudinary="v1700132389/devtools/7-payload_nfzobp">



</article-video>

### Open Graph Preview

[Open Graph](https://ogp.me/) plays an important role in social media sharing as well as [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization). In the traditional workflow, we usually need to first deploy our app to check if the Open Graph is working as expected on various social media platforms. With the Open Graph Preview, you can now preview the Open Graph in DevTools and update it live with an instant feedback loop.

We also help you check the Open Graph tags in your app and provide suggestions to improve them. You can copy the generated code snippet and paste it to your routes to fix them in one go.

<article-video cloudinary="v1700132390/devtools/8-open-graph_hjawen">



</article-video>

### Plugins Overview

Plugins Overview list all the [plugins](/docs/guide/directory-structure/plugins) registered in your app. As the plugins are executed in the runtime before your app renders, it's important to keep plugins performant and avoid blocking the rendering. We provide the execution time of each plugin and the total time of all plugins, so you can better identify the potential performance bottlenecks.

<article-video cloudinary="v1700132390/devtools/9-plugins_bhcobr">



</article-video>

### Timeline

Timeline is a tool for you to check when and how each composable been called. Different from browser DevTools' performance tools, this tab only check the high-level composables combining with other events like route navigration, which is closer to day-to-day use. It also records the arguments and return values of each call, so you can better understand what's going on under the hood.

<warning>

As of November 2023, the Timeline is still an experimental feature that requires manually opt-in.

</warning>

<article-video cloudinary="v1700132392/devtools/10-timeline_zeei5s">



</article-video>

### Production Build Analyzer

While Nuxt DevTools is mostly focused on providing development tools, sometimes we might want to know how chunks are composed in production. The Build Analyzer allows you to fire up a production build and analyze the chunks and modules at any time and see how they are bundled. You can also do multiple builds on different branches to compare how your refactoring/changes affect the bundle size, etc.

<article-video cloudinary="v1700132394/devtools/11-build-analyze_f3wx6q">



</article-video>

### Server API Playground

Nuxt provides a very convenient way to create server API functions with the [server routes](/docs/guide/directory-structure/server#server-routes). Since in Nuxt we have that information, we are able to provide a playground for you to test and debug your server API functions, similar to tools like Postman. We list all the server APIs available in your app automatically. And we execute those functions **within the same context of your app**, so you don't need to manually set them up in external tools. As always, we also have code snippets for you to copy and paste into your app.

<article-video cloudinary="v1700132388/devtools/12-server-api_owjyjg">



</article-video>

### Embedded Full-feature VS Code

Thanks to the flexibility of our DevTools approach, we can leverage the power of the modern web to embed a full-featured VS Code right in the DevTools. In that VS Code, you can sign in to your account and synchronize your settings, and all the extensions just work as your normal VS Code client. This allows you to quickly edit your code without leaving your browser.

<article-video cloudinary="v1700132395/devtools/13-vscode_je5x0m">



</article-video>

### Component Inspector

The Inspector allows you to inspect the DOM tree and see which component is rendering it. Click to go to your editor for the specific line. Making it much easier to make changes without the requirement of understanding the project structure thoroughly.

<article-video cloudinary="v1700132391/devtools/0-inspector_fuxmr7">



</article-video>

### Split Screens

In the recent releases, we introduced a split screen feature, that allows you to open two tabs side-by-side.

<article-video cloudinary="v1700132391/devtools/0-split-view_mdeiie">



</article-video>

### UI Customization

In DevTools setting, we provide a few options for you to customize the tabs you want to see, and the layout of the DevTools.

<article-video cloudinary="v1700132391/devtools/0-settings_weflmu">



</article-video>

## Ecosystem

In Nuxt, we value the ecosystem a lot. Similar to how Nuxt modules enhance Nuxt core, we also designed Nuxt DevTools to be highly extensible, allowing modules to provide additional features and integrations.

### Community Modules

We are proud to see the community has already started to build modules for Nuxt DevTools. Here are some of them:

[Vitest module](https://nuxt.com/modules/vitest) provides Vitest UI for tests running with the same pipeline as your Nuxt app. Made it easier to debug your tests alongside your app.

<article-video cloudinary="v1700132393/devtools/99-vitest_wwikpc">



</article-video>

[VueUse module](/modules/vueuse) provides a search page for available composables and see their documentation.

<article-video cloudinary="v1700132390/devtools/99-vueuse_simsfj">



</article-video>

[SiteMap module](/modules/sitemap) provides an interactive editor for you to manage your sitemap.

<article-video cloudinary="v1700132390/devtools/99-sitemap_xpsfek">



</article-video>

[TailwindCSS module](/modules/tailwindcss) provides the Tailwind Config Viewer for you to check what's available based on your config.

<article-video cloudinary="v1700132388/devtools/99-tailwind_dgiodc">



</article-video>

[UnoCSS module](/modules/unocss) provides an interactive inspector to see how each module contributes to the final CSS.

<article-video cloudinary="v1700132394/devtools/99-unocss_xvii5x">



</article-video>

[Storybook module](/modules/storybook) provides a Storybook UI for your components.

<article-video cloudinary="v1700132388/devtools/99-storybook_ifxt4r">



</article-video>

And they are just a few of them! We are looking forward to see more modules coming to Nuxt DevTools!

### Projects Inspired by Nuxt DevTools

In the meantime, we are also flattered that other frameworks are starting to build their own DevTools inspired by Nuxt DevTools:

- [`webfansplz/vite-plugin-vue-devtools`](https://github.com/webfansplz/vite-plugin-vue-devtools) - A Nuxt DevTools port to support DevTools for Vite + Vue 3 apps.
- [`pheno-agency/vite-plugin-devtools`](https://github.com/pheno-agency/vite-plugin-devtools) - An experiment on building framework-agnostic DevTools for Vite.
- [Modern.js DevTools](https://github.com/Asuka109/modern.js/tree/dev/modernjs-devtools/packages/devtools/plugin) - In App DevTools for Modern.js
- [Qwik DevTools](https://github.com/QwikDev/devtools) - DevTools for Qwik

We are working closely with the maintainers of those projects to see how we can bring the experience of DevTools to the next level.

## What's Next

Nuxt DevTools just reached v1.0, but t doesn't mean we are done. There are still a lot of things we want to explore and improve. Here are some of the ideas we are considering:

- Nuxt Accessibility Integration - We are building an a11y integration for Nuxt ([#23255](https://github.com/nuxt/nuxt/issues/23255)). We'll build a dedicated view in Nuxt DevTools for you to check the accessibility hints interactively.
- Vue DevTools Integration - We are working with the Vue team to bring the Vue DevTools experience to a shared tool that works for both browser extensions and in-app DevTools like `vite-plugin-vue-devtools` and Nuxt DevTools.
- [Let us know your ideas/suggestions!](https://github.com/nuxt/devtools/discussions/29)

## The Future

We are excited to see how Nuxt DevTools can help you build better apps and improve your developer experience. Going forward, we are imagining something bigger than Nuxt DevTools itself. We believe that having such framework-specific DevTools is the way onwards to provide even better developer experience. We also see there are many parts of such tools can actually be shared and reused across tools. We came up with the idea of the DevTools Kit.

### DevTools Kit

DevTools Kit is an idea of the universal protocol that is still in the early brainstorming phase. We imagine that in the best world, each feature of the DevTools should be **composable, extensible, and collaborative**. Meta-frameworks could build their own features for their specific needs, while the common web-related tools could be shared and collaborated on between different frameworks.

![DevTools Kit](/assets/blog/devtools/slide-devtools-kit.png)

Imagine we could have all these features, each as a standalone package. We could have general web-related tools like SEO, Accessibility, PWA, Static Assets, etc. Then low-level build tools related, like Vite build analyzer, Vite Inspector, or Webpack visualizer, etc. And finally, we could have framework and meta-framework specific tools like Vue Components view, or Nuxt Server API Playground, etc.

![Nuxt DevTools](/assets/blog/devtools/slide-nuxt-devtools.png)

![Nuxt DevTools](/assets/blog/devtools/slide-vue-devtools.png)

At that time, Vue DevTools would be a composition of common web features and Vue-specific features. And Nuxt DevTools would essentially be a composition of the features above, inherit all features from Vue DevTools, and add Nuxt specific features on top of it.

![Your DevTools](/assets/blog/devtools/slide-your-devtools.png)

It would even be possible to compose your own DevTools as you like.

That said, we are still thinking about and discussing the details of the DevTools Kit. Stay tuned for more updates!

## Conclusion

We hope you enjoy the new Nuxt DevTools experience! We are looking forward to seeing how it can help you build better apps and improve your developer experience. If you have any ideas or suggestions, feel free to let us know in the [Ideas & Suggestions](https://github.com/nuxt/devtools/discussions/29) discussion.

Thank you for your support and happy hacking! 🚀

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-error-boundary.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-error-boundary.md

# <NuxtErrorBoundary>

> The <NuxtErrorBoundary> component handles client-side errors happening in its default slot.

<tip>

The `<NuxtErrorBoundary>` uses Vue's [`onErrorCaptured`](https://vuejs.org/api/composition-api-lifecycle#onerrorcaptured) hook under the hood.

</tip>

## Events

- `@error`: Event emitted when the default slot of the component throws an error.```vue
<template>
  <NuxtErrorBoundary @error="logSomeError">
    <!-- ... -->
  </NuxtErrorBoundary>
</template>
```

## Slots

- `#error`: Specify a fallback content to display in case of error.```vue
<template>
  <NuxtErrorBoundary>
    <!-- ... -->
    <template #error="{ error, clearError }">
      <p>An error occurred: {{ error }}</p>

      <button @click="clearError">
        Clear error
      </button>
    </template>
  </NuxtErrorBoundary>
</template>
```

<read-more to="/docs/4.x/getting-started/error-handling">



</read-more>

## Examples

### Accessing `error` and `clearError` in script

You can access `error` and `clearError` properties within the component's script as below:

```vue
<template>
  <NuxtErrorBoundary ref="errorBoundary">
    <!-- ... -->
  </NuxtErrorBoundary>
</template>

<script setup lang="ts">
const errorBoundary = useTemplateRef('errorBoundary')

// errorBoundary.value?.error
// errorBoundary.value?.clearError()
</script>
```

---

# Source: https://nuxt.com/raw/blog/nuxt-icon-v1-0.md

# Introducing Nuxt Icon v1

> Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects.

Icons are essential to modern web interfaces. They simplify navigation, clarify functionality, and enhance visual appeal. However, implementing icons efficiently involves challenges like scalability, dynamic loading, and server-side rendering (SSR) compatibility.

To address these challenges, we developed **Nuxt Icon v1** — a versatile, modern solution tailored for Nuxt projects. By building on established icon rendering techniques and introducing novel approaches, Nuxt Icon bridges the gap between performance, usability, and flexibility.

In this post, we’ll explore the challenges of icon rendering, the evolution of icon solutions, and how Nuxt Icon combines the best aspects of these methods to offer a seamless experience for developers.

---

## Why Are Icons Challenging?

At first glance, icons seem simple - they are essentially just tiny image elements that enhance a user interface, providing visual cues and enhancing usability.

![Icons Showcases](/assets/blog/nuxt-icon/icons-showcase.png)

However, from an engineering perspective, they pose several challenges. Ideal icons should be:

- **Colorable**: Adaptable to themes and color schemes.
- **Scalable**: Render crisply at various sizes and resolutions.
- **Manageable**: Icon sets can contain hundreds or thousands of icons.
- **Efficiently Bundled**: Minimize network requests.
- **Optimally Loaded**: Affect application performance and user experience.
- **Dynamic**: Support dynamic loading for user-generated or runtime-defined icons.

![Engineering Challenges with Icons](/assets/blog/nuxt-icon/challenges.png)

Meeting all these needs requires a carefully engineered solution that balances trade-offs. Let’s explore the evolution of icon solutions and how they address these challenges.

---

## A Journey Through Icon Solutions

Over the years, developers have experimented with various techniques to render icons efficiently. Let’s explore the evolution of these solutions and the challenges they faced.

### 1. `<img>` Tags: The Early Days

The most straightforward solution: using the `<img>` tag. This was the go-to method in the early days of the web.

You'd host your image assets and use an `<img>` tag to link to that image, specifying its width and height. It's simple, requires no setup or runtime dependencies, and works natively in browsers.

![Solution 1](/assets/blog/nuxt-icon/solution-1.png)

However, there are drawbacks. Images can become pixelated, lack color control, and don't scale well. Each icon being a separate image file results in many network requests, which could be slow, especially back in the days of HTTP 1.1. Before the image is downloaded, you might see a flash of invisible icons, which can hurt the user experience. Lastly, it's quite verbose to write, as you need to specify the full path of the image and manage the relative paths. It explains why this approach is rarely used on modern websites today.

---

### 2. Web Fonts: Icon Fonts

As the next step in icon evolution, web fonts emerged as a popular solution. Fonts are inherently vectorized and colorable, making them a natural fit for icons.

Iconset providers typically compile their icons into a special font file, assigning a unique Unicode character to each icon. This is accompanied by a CSS file that maps these Unicode values to specific icon classes.

The advantages of this approach are clear: it's easy to use, colorable, scalable, and requires only a single request to load all icons.

![Solution 2](/assets/blog/nuxt-icon/solution-2.png)

However, there are some downsides. Loading a large font file upfront can be slow, and customizing the icon set is challenging. Additionally, you might experience a flash of invisible icons before the font loads, as there are no fallback fonts available.

---

### 3. Inline SVGs: Component-Based Icons

With the advent of modern frontend frameworks, reusing HTML elements has become significantly easier. This led to the idea of directly inlining SVG tags as components.

To support this approach, many icon sets provide packages with wrappers tailored for each framework. For instance, MDI icons use a shared component and pass icon data as props, while Tabler icons offer a dedicated component for each icon.

Since these are SVGs, they are inherently colorable, scalable, and retain all the features of SVGs. Typically, icons are bundled into the app, eliminating additional network requests and ensuring they are SSR-friendly and visible on the first render.

![Solution 3](/assets/blog/nuxt-icon/solution-3.png)

However, this method has its downsides. It generates numerous SVG DOM elements, which can impact performance when many icons are used. It also increases the bundle size and requires specific integration support for each icon set and framework combination, leading to a degree of vendor lock-in. This makes it challenging to switch to a different icon set or framework.

Despite these trade-offs, this approach is widely adopted today, as switching icon sets or frameworks is not a frequent necessity for most projects.

---

### 4. Iconify Runtime: Dynamic API Access

[Iconify](https://iconify.design/) revolutionized icon usage by aggregating over 200,000 icons across 100+ collections. Its runtime solution dynamically fetched icons via an API, enabling dynamic access to any icon without pre-bundling.

This is a great fit for rendering icons from user-provided content or other dynamic content that you don't know at build time. And it's super easy to set up, as you can even use it as a CDN without any build tools.

![Solution 4](/assets/blog/nuxt-icon/solution-4.png)

While this method offers great flexibility, it does come with some trade-offs. It introduces runtime dependencies, meaning icons will only render after JavaScript is loaded and the icon data is fetched. This approach also poses challenges for server-side rendering (SSR) and caching layers, such as those used in Progressive Web Apps (PWAs).

---

### 5. On-Demand Component Icons

With the unified interface from Iconify and Vite's on-demand approach, we developed [`unplugin-icons`](https://github.com/unplugin/unplugin-icons). This tool allows you to import any icons as components on-demand.

As an [`unplugin`](https://github.com/unjs/unplugin), it supports all popular build tools, including Vite, webpack, and rspack. We provide compilers for popular frameworks like Vue, React, Svelte, and Solid. With Iconify, you can use any icon across any framework, minimizing vendor lock-in.

![Solution 5](/assets/blog/nuxt-icon/solution-5.png)

While this technique shares the same pros and cons as previous component icon solutions, the integration with build tools allows us to serve the full Iconify collection while only shipping the icons you actually use. However, runtime concerns like DOM element management still persist.

---

### 6. Pure CSS Icons

As a side-effect of working on [UnoCSS](https://unocss.dev/), we discovered the potential of embedding icons entirely in CSS, leading to the innovative solution of [Pure CSS Icons](https://antfu.me/posts/icons-in-pure-css).

This method involves inlining SVG icons as data URLs and providing a single class to display the icons. With some tweaks, these icons become colorable, scalable, and even capable of displaying SVG animations.

Browsers can cache the CSS rules, and each icon requires only **one DOM element** to render. This approach ships the icons in a single CSS file with no additional requests. Since it's pure CSS, the icons display along with the rest of your UI, require zero runtime, and work naturally with SSR—your server doesn't need any extra work on the server side.

![Solution 6](/assets/blog/nuxt-icon/solution-6.png)

The only downsides are the lack of full customization for elements inside the SVG and the need to bundle icons at build-time, which isn't dynamic.

---

## The Challenges to Integrate in Nuxt

While I would say that the [Pure CSS Icons](#_6-pure-css-icons) and [On-demand Component Icons](#_5-on-demand-component-icons) would be pretty sufficient for most of the static usages, Nuxt as a full featured framework, has a bit more requirements to integrate icons efficiently:

- **SSR/CSR**: Nuxt works in both server-side rendering (SSR) and client-side rendering (CSR) modes. We care a lot about the end user experience, and we want to ensure that icons are rendered instantly without flickers.
- **Dynamic Icons**: In integrations like [Nuxt Content](https://content.nuxt.com/), the content can be provided at runtime or from external sources, which we are not aware at build time. We want to ensure we have the capability to integrate with those cases well.
- **Performance**: We want to ensure that the icons are bundled efficiently, and the loading of icons is optimized for the best performance.
- **Custom Icons**: While Iconify provides a wide range of icons for selection, we also aware it's pretty common for projects to have their own icon sets, or wanted to use paid icons that are not available in Iconify. Supporting custom icons is crucial for our users.

![Nuxt Integration Challenges and Solutions](/assets/blog/nuxt-icon/nuxt-icon-challenges.png)

With these requirements in mind, let's revisit the solutions we discussed earlier and see how they stack up.

For dynamic icons, the Iconify Runtime stands out as a viable option. It allows for dynamic fetching of icons, making it suitable for content that isn't known at build time. However, it has its drawbacks. The reliance on runtime dependencies means it doesn't integrate seamlessly with SSR, and it doesn't support custom icons since the requests are directed to Iconify's servers, which don't have access to our local icon setup.

Conversely, Pure CSS Icons offer excellent performance and SSR compatibility. They ensure icons are rendered instantly without flickers and are bundled efficiently. However, they fall short when it comes to dynamic icons, as they need to be bundled at build time and lack the flexibility to adapt to runtime content changes.

Balancing these trade-offs is indeed challenging. So, why not leverage the strengths of both approaches? By understanding these trade-offs, we can better appreciate the balanced solution that Nuxt Icon v1 offers.

---

## Introducing Nuxt Icon v1: The Balance of Both Worlds

With the flexibility of the Nuxt Module system, Nuxt Icon combines the best of both worlds: the instant rendering of CSS icons and the dynamic fetching of Iconify icons. This dual approach provides a versatile, modern, and customizable icon solution that seamlessly adapts to your project's needs.

### Dual Rendering Modes

To address the trade-offs in rendering approaches, Nuxt Icon introduces a versatile `<Icon>` component that supports both CSS and SVG modes, both of which are SSR-friendly. Depending on your customization needs, you can switch between these modes for each icon.

In CSS mode, icons are included in the CSS during SSR, ensuring they render instantly without any runtime cost. In SVG mode, icons are inlined as HTML during SSR, providing the same immediate rendering benefits. Both approaches ensure that icons appear on the initial screen without any delay, offering a seamless user experience.

![Dual rendering mode](/assets/blog/nuxt-icon/dual-rendering-modes.png)

---

### Icon Bundles

Dynamic icons present unique challenges, especially when it comes to loading them efficiently. To address this, we leverage Iconify's API, which allows us to serve any icon on demand via network requests. However, relying solely on this API can introduce delays, especially if the servers are geographically distant from your users.

To mitigate this, we introduced the concept of Icon Bundles. We can bundle frequently used icons directly into the `Client Bundle`. This ensures that these icons render instantly without additional network requests. However, bundling all possible icons isn't feasible due to the potential increase in bundle size.

Given that Nuxt is a full-stack framework, we can strike a balance by introducing a `Server Bundle`. On the server side, bundle size is less of an issue, allowing us to include a more extensive set of icons. During SSR, these icons can be fetched quickly and sent to the client as needed. This setup ensures high performance for commonly used icons while still providing the flexibility to serve any icon from Iconify as a fallback.

By combining client-side bundling for static icons and server-side bundling for dynamic icons, we achieve an optimal balance between performance and flexibility.

![Icon Bundles in Nuxt Icons](/assets/blog/nuxt-icon/bundles.png)

---

### Data Flow

Here is a data flow diagram illustrating how Nuxt Icon requests icon data:

1. You use the `<Icon>` component and provide the icon `name`.
2. Nuxt Icon will first check if the icon is available in the `Client Bundle`, or the SSR payload (icons that are known at SSR will be presented in the payload). If so, the icon will be rendered instantly.
3. If the icon is not available on the client side, Nuxt Icon will fetch the icon data from the server API shipped along with your Nuxt app. Inside the server endpoint, it will query from the `Server Bundle` to see if the icon is available.
4. Between that, there are multiple cache systems involved. Server endpoint cache, HTTP cache, and client-side cache to ensure the icon is fetched efficiently and quickly. Since icon data does not change frequently, we use hard cache strategies to ensure the best performance.
5. When the icon is unknown to both the client and server (dynamic icons), the server endpoint will fallback to the Iconify API to fetch the icon data. Since the server endpoint is cached, the Iconify API will be called only once for each unique icon regardless of how many clients are requesting it, to save resources on both sides.

![Nuxt Icon Requesting Data flow](/assets/blog/nuxt-icon/dataflow.png)

This layered approach ensures efficient icon delivery, balancing speed and flexibility, while being as dynamic as possible. And balance out the trade-offs between each solution.

---

## Try Nuxt Icon Today

Nuxt Icon v1 represents the culmination of years of innovation in icon rendering. Whether you’re building a dynamic app, a static website, or anything in between, Nuxt Icon adapts to your needs.

It’s easy to add Nuxt Icon to your project by running the following command:

```bash
npx nuxi module add icon
```

Then, import the `<Icon>` component in your Vue components, providing icon `name` following [Iconify's conventions](https://iconify.design/docs/icons/icon-basics.html):

```vue
<template>
  <Icon name="i-lucide-activity" />
</template>
```

Explore more with the [documentation](https://github.com/nuxt/icon), experiment with its features, and let us know your thoughts. We’re excited to see how Nuxt Icon transforms your projects!

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/nuxt-image-v2.md

# Nuxt Image v2

> Nuxt Image v2 is out - with full TypeScript support, IPX v3, and new providers!

We're excited to announce **Nuxt Image v2**! 🎉 This release focuses on TypeScript support, performance improvements, and better developer experience.

<note>

Nuxt Image v2 works with Nuxt 3.1+. If you're on Nuxt 3.0.x, you'll need to upgrade to at least 3.1 first.

</note>

## 🎯 TypeScript support

The biggest change in v2 is full TypeScript support throughout the module ([#1802](https://github.com/nuxt/image/pull/1802)).

### Typed composables

The `$img` helper and `useImage()` composable have full type inference ([#1844](https://github.com/nuxt/image/pull/1844)):

```ts
const img = useImage()

// Full autocomplete for modifiers
const url = img('/image.jpg', { 
  width: 300,
  height: 200,
  fit: 'cover' // TypeScript knows the valid values!
})
```

### Type-safe configuration

Module options are now fully typed. For example, providers that require a `baseURL` will enforce it at the type level in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    provider: 'bunny',
    bunny: {
      baseURL: '...' // TypeScript error if missing!
    }
  }
})
```

### Typed providers

Finally, if you are using custom image providers, you should use the new `defineProvider` for type-safe configuration:

```ts
// Before (v1)
export const getImage = (src, { modifiers, baseURL }) => {
  // ...
  return { url }
}

// After (v2)
import { defineProvider } from '@nuxt/image/runtime'

export default defineProvider({
  getImage(src, { modifiers, baseURL }) {
    // Fully typed modifiers
    // ...
    return { url }
  }
})
```

## 🚀 IPX v3

We've upgraded to IPX v3 ([#1799](https://github.com/nuxt/image/pull/1799)) for better performance and better `sharp` binary handling. The upgrade includes automatic detection of the correct `sharp` binaries for your deployment architecture.

## 🔌 Server-side utilities

You can now use image helpers directly in Nitro server endpoints ([#1473](https://github.com/nuxt/image/pull/1473)).

```ts [server/api/og-image.ts]
export default defineEventHandler((event) => {
  const img = useImage()
  
  return {
    url: img('/hero.jpg', { 
      width: 1200, 
      height: 630,
      fit: 'cover' 
    })
  }
})
```

## 🎨 Component improvements

### Template refs

`<NuxtImg>` now exposes the underlying `<img>` element via template refs:

```vue
<script setup>
const img = useTemplateRef('img')

onMounted(() => {
  // Direct access to the native img element
  console.log(img.value.imgEl)
})
</script>

<template>
  <NuxtImg ref="img" src="/image.jpg" />
</template>
```

### Typed slots

Both `<NuxtImg>` and `<NuxtPicture>` now have properly typed default slots.

```vue
<template>
  <NuxtImg src="/image.jpg" custom>
    <template #default="{ imgAttrs, isLoaded, src }">
      <img v-bind="imgAttrs" :src="src">
      <span v-if="!isLoaded">Loading...</span>
    </template>
  </NuxtImg>
</template>
```

The slot provides:

- `imgAttrs` - All computed image attributes (sizes, srcset, etc.)
- `isLoaded` - Whether the placeholder has loaded
- `src` - The computed image source URL

## 🌐 New providers

### Shopify

You can now configure the Shopify provider ([#1890](https://github.com/nuxt/image/pull/1890)):

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  image: {
    provider: 'shopify',
    shopify: {
      baseURL: 'https://your-store.myshopify.com'
    }
  }
})
```

### GitHub

This provider lets you inject GitHub avatars and user content ([#1990](https://github.com/nuxt/image/pull/1990)):

```vue
<!-- Width and height -->
<NuxtImg provider="github" src="nuxt" height="50" width="50" />

<!-- Width only -->
<NuxtImg provider="github" src="unjs" width="512" />

<!-- Default size -->
<NuxtImg provider="github" src="npm" />
```

## ⚡ Performance

We've made several optimizations to reduce bundle size and improve runtime performance:

- **Better URL encoding** ([#1813](https://github.com/nuxt/image/pull/1813)) - Switched to `URLSearchParams` for more reliable parameter handling
- **Reduced runtime utilities** ([#1816](https://github.com/nuxt/image/pull/1816)) - Removed unused code and simplified implementations
- **Streamlined screen sizes** ([#1931](https://github.com/nuxt/image/pull/1931)) - Aligned default breakpoints with Tailwind CSS

## 🎯 Better layer support

Nuxt Image now properly supports custom image directories within Nuxt layers ([#1880](https://github.com/nuxt/image/pull/1880)), making it easier to organize images in modular projects.

## ⚠️ Breaking changes

### Provider API

The biggest breaking change is how providers are defined. All providers now use a default export with the `defineProvider` wrapper:

```diff
- export const getImage = (src, { modifiers }) => { ... }
+ export default defineProvider({
+   getImage(src, { modifiers }) { ... }
+ })
```

If you maintain a custom provider, you'll need to update it. But you get full TypeScript support in return!

### Removed providers

The deprecated `layer0` and `edgio` providers have been removed.

### URL formatters

If you have custom providers using `joinWith` for parameter formatting, you'll need to update them to use the `formatter` function with `createOperationsGenerator`. See the [migration guide](https://image.nuxt.com/get-started/migration#url-formatter-changes) for details.

### Screen sizes

Default screen sizes now match Tailwind CSS. We've removed `xs` (320px) and `xxl` (2560px). See the [migration guide](https://image.nuxt.com/get-started/migration#screen-size-changes) for how to add them back if needed.

### Removed utilities

We've removed several unused runtime utilities. If you were importing internal utilities directly, check if they still exist.

## ✅ Upgrading

Check out our comprehensive [migration guide](https://image.nuxt.com/get-started/migration) for step-by-step upgrade instructions.

The quick version:

```bash [Terminal]
npm install @nuxt/image@latest
```

Most apps can upgrade with no code changes. If you have custom providers, you'll need to update them to use `defineProvider` - see the [migration guide](https://image.nuxt.com/get-started/migration#custom-provider-updates) for examples.

## 🐛 Bug fixes

This release includes several fixes:

- **Preload links**: Fixed preload for multiple densities with single size ([#1851](https://github.com/nuxt/image/pull/1851))
- **Crossorigin attributes**: Correct crossorigin on preload links ([#1836](https://github.com/nuxt/image/pull/1836))
- **Provider-specific formats**: AWS Amplify and Vercel providers now have proper format allow lists ([#1996](https://github.com/nuxt/image/pull/1996))
- **Hygraph**: Prevented broken image URLs ([#1999](https://github.com/nuxt/image/pull/1999))
- **Preset sizes**: Fixed preset size application when component sizes prop is undefined ([#1919](https://github.com/nuxt/image/pull/1919))
- **Cloudflare**: Don't add baseURL if there are no operations ([#1790](https://github.com/nuxt/image/pull/1790))
- **IPX**: Always use IPX provider if external baseURL is provided ([#1800](https://github.com/nuxt/image/pull/1800))

## 🙏 Thank you

Thank you to all the contributors who made this release possible! This includes contributions from dozens of community members who helped with features, bug fixes, documentation improvements, and feedback.

## 📚 Resources

- [Documentation](https://image.nuxt.com)
- [GitHub Repository](https://github.com/nuxt/image)
- [Migration Guide](https://image.nuxt.com/get-started/migration)

## 👉 Full release notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/image/releases/tag/v2.0.0">

Read the full release notes of Nuxt Image `v2.0.0`.

</read-more>

Happy optimizing! 🖼️✨

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-img.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-img.md

# <NuxtImg>

> Nuxt provides a <NuxtImg> component to handle automatic image optimization.

`<NuxtImg>` is a drop-in replacement for the native `<img>` tag.

- Uses built-in provider to optimize local and remote images
- Converts `src` to provider-optimized URLs
- Automatically resizes images based on `width` and `height`
- Generates responsive sizes when providing `sizes` option
- Supports native lazy loading as well as other `<img>` attributes

## Setup

In order to use `<NuxtImg>` you should install and enable the Nuxt Image module:

```bash [Terminal]
npx nuxt module add image
```

## Usage

`<NuxtImg>` outputs a native `img` tag directly (without any wrapper around it). Use it like you would use the `<img>` tag:

```html
<NuxtImg src="/nuxt-icon.png" />
```

Will result in:

```html
<img src="/nuxt-icon.png" />
```

<read-more target="_blank" to="https://image.nuxt.com/usage/nuxt-img">

Read more about the `<NuxtImg>` component.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-island.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-island.md

# <NuxtIsland>

> Nuxt provides the <NuxtIsland> component to render a non-interactive component without any client JS.

When rendering an island component, the content of the island component is static, thus no JS is downloaded client-side.

Changing the island component props triggers a refetch of the island component to re-render it again.

<note>

Global styles of your application are sent with the response.

</note>

<tip>

Server only components use `<NuxtIsland>` under the hood

</tip>

## Props

- `name` : Name of the component to render.

  - **type**: `string`
  - **required**
- `lazy`: Make the component non-blocking.

  - **type**: `boolean`
  - **default**: `false`
- `props`: Props to send to the component to render.

  - **type**: `Record<string, any>`
- `source`: Remote source to call the island to render.

  - **type**: `string`
- **dangerouslyLoadClientComponents**: Required to load client components from a remote source.

  - **type**: `boolean`
  - **default**: `false`

<note>

Remote islands need `experimental.componentIslands` to be `'local+remote'` in your `nuxt.config`.

</note>

<warning icon="i-ph-warning-duotone">

Using the `source` prop to render content from a remote server is inherently dangerous. When you specify a remote `source`, you are fully trusting that server to provide safe HTML content that will be rendered directly in your application.

This is similar to using `v-html` with external content - the remote server can inject any HTML, including potentially malicious content. **Only use source with servers you fully trust and control.**

The `dangerouslyLoadClientComponents` prop controls an additional layer of risk: whether to also download and execute client components from the remote source. Even with `dangerouslyLoadClientComponents` disabled (the default), you are still trusting the remote server's HTML output.

</warning>

<note>

By default, component islands are scanned from the `~/components/islands/` directory. So the `~/components/islands/MyIsland.vue` component could be rendered with `<NuxtIsland name="MyIsland" />`.

</note>

## Slots

Slots can be passed to an island component if declared.

Every slot is interactive since the parent component is the one providing it.

Some slots are reserved to `NuxtIsland` for special cases.

- `#fallback`: Specify the content to be rendered before the island loads (if the component is lazy) or if `NuxtIsland` fails to fetch the component.

## Ref

- `refresh()`
  - **type**: `() => Promise<void>`
  - **description**: force refetch the server component by refetching it.

## Events

- `error`
  - **parameters**:
  
    - **error**:
    
      - **type**: `unknown`
  - **description**: emitted when when `NuxtIsland` fails to fetch the new island.

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-layout.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-layout.md

# <NuxtLayout>

> Nuxt provides the <NuxtLayout> component to show layouts on pages and error pages.

You can use `<NuxtLayout />` component to activate the `default` layout on `app.vue` or `error.vue`.

```vue [app/app.vue]
<template>
  <NuxtLayout>
    some page content
  </NuxtLayout>
</template>
```

<read-more to="/docs/4.x/directory-structure/app/layouts">



</read-more>

## Props

- `name`: Specify a layout name to be rendered, can be a string, reactive reference or a computed property. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory, or `false` to disable the layout.

  - **type**: `string | false`
  - **default**: `default`

```vue [app/pages/index.vue]
<script setup lang="ts">
// layouts/custom.vue
const layout = 'custom'
</script>

<template>
  <NuxtLayout :name="layout">
    <NuxtPage />
  </NuxtLayout>
</template>
```

<note>

Please note the layout name is normalized to kebab-case, so if your layout file is named `errorLayout.vue`, it will become `error-layout` when passed as a `name` property to `<NuxtLayout />`.

</note>

```vue [error.vue]
<template>
  <NuxtLayout name="error-layout">
    <NuxtPage />
  </NuxtLayout>
</template>
```

<read-more to="/docs/4.x/directory-structure/app/layouts">

Read more about dynamic layouts.

</read-more>

- `fallback`: If an invalid layout is passed to the `name` prop, no layout will be rendered. Specify a `fallback` layout to be rendered in this scenario. It **must** match the name of the corresponding layout file in the [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) directory.

  - **type**: `string`
  - **default**: `null`

## Additional Props

`NuxtLayout` also accepts any additional props that you may need to pass to the layout. These custom props are then made accessible as attributes.

```vue [app/pages/some-page.vue]
<template>
  <div>
    <NuxtLayout
      name="custom"
      title="I am a custom layout"
    >
      <!-- ... -->
    </NuxtLayout>
  </div>
</template>
```

In the above example, the value of `title` will be available using `$attrs.title` in the template or `useAttrs().title` in `<script setup>` at custom.vue.

```vue [app/layouts/custom.vue]
<script setup lang="ts">
const layoutCustomProps = useAttrs()

console.log(layoutCustomProps.title) // I am a custom layout
</script>
```

## Transitions

`<NuxtLayout />` renders incoming content via `<slot />`, which is then wrapped around Vue’s `<Transition />` component to activate layout transition. For this to work as expected, it is recommended that `<NuxtLayout />` is **not** the root element of the page component.

<code-group>

```vue [app/pages/index.vue]
<template>
  <div>
    <NuxtLayout name="custom">
      <template #header>
        Some header template content.
      </template>
    </NuxtLayout>
  </div>
</template>
```

```vue [app/layouts/custom.vue]
<template>
  <div>
    <!-- named slot -->
    <slot name="header" />
    <slot />
  </div>
</template>
```

</code-group>

<read-more to="/docs/4.x/getting-started/transitions">



</read-more>

## Layout's Ref

To get the ref of a layout component, access it through `ref.value.layoutRef`.

<code-group>

```vue [app/app.vue]
<script setup lang="ts">
const layout = ref()

function logFoo () {
  layout.value.layoutRef.foo()
}
</script>

<template>
  <NuxtLayout ref="layout">
    default layout
  </NuxtLayout>
</template>
```

```vue [app/layouts/default.vue]
<script setup lang="ts">
const foo = () => console.log('foo')
defineExpose({
  foo,
})
</script>

<template>
  <div>
    default layout
    <slot />
  </div>
</template>
```

</code-group>

<read-more to="/docs/4.x/directory-structure/app/layouts">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/nuxt-lifecycle.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/nuxt-lifecycle.md

# Nuxt Lifecycle

> Understanding the lifecycle of Nuxt applications can help you gain deeper insights into how the framework operates, especially for both server-side and client-side rendering.

The goal of this chapter is to provide a high-level overview of the different parts of the framework, their execution order, and how they work together.

## Server lifecycle

On the server, the following steps are executed for every initial request to your application:

<steps>

### Server plugins <badge className="align-middle" color="info">once</badge>

Nuxt is powered by [Nitro](https://nitro.build/), a modern server engine.

When Nitro starts, it initializes and executes the plugins under the [`/server/plugins`](/docs/4.x/directory-structure/server#server-plugins) directory. These plugins can:

- Capture and handle application-wide errors.
- Register hooks that execute when Nitro shuts down.
- Register hooks for request lifecycle events, such as modifying responses.

<callout icon="i-lucide-lightbulb">

Nitro plugins are executed only once when the server starts. In a serverless environment, the server boots on each incoming request, and so do the Nitro plugins. However, they are not awaited.

</callout>

<read-more to="/docs/4.x/directory-structure/server#server-plugins">



</read-more>

### Server middleware

After initializing the Nitro server, middleware under `server/middleware/` is executed for every request. Middleware can be used for tasks such as authentication, logging, or request transformation.

<warning>

Returning a value from middleware will terminate the request and send the returned value as the response. This behavior should generally be avoided to ensure proper request handling!

</warning>

<read-more to="/docs/4.x/directory-structure/server#server-middleware">



</read-more>

### App plugins

The Vue and Nuxt instances are created first. Afterward, Nuxt executes its app plugins. This includes:

- Built-in plugins, such as Vue Router and `unhead`.
- Custom plugins located in the `app/plugins/` directory, including those without a suffix (e.g., `myPlugin.ts`) and those with the `.server` suffix (e.g., `myServerPlugin.server.ts`).

Plugins execute in a specific order and may have dependencies on one another. For more details, including execution order and parallelism, refer to the [Plugins documentation](/docs/4.x/directory-structure/app/plugins).

<callout icon="i-lucide-lightbulb">

After this step, Nuxt calls the [`app:created`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic.

</callout>

<read-more to="/docs/4.x/directory-structure/app/plugins">



</read-more>

### Route validation

After initializing plugins and before executing middleware, Nuxt calls the `validate` method if it is defined in the `definePageMeta` function. The `validate` method, which can be synchronous or asynchronous, is often used to validate dynamic route parameters.

- The `validate` function should return `true` if the parameters are valid.
- If validation fails, it should return `false` or an object containing a `status` and/or `statusText` to terminate the request.

For more information, see the [Route Validation documentation](/docs/4.x/getting-started/routing#route-validation).

<read-more to="/docs/4.x/getting-started/routing#route-validation">



</read-more>

### App middleware

Middleware allows you to run code before navigating to a particular route. It is often used for tasks such as authentication, redirection, or logging.

In Nuxt, there are three types of middleware:

- **Global route middleware**
- **Named route middleware**
- **Anonymous (or inline) route middleware**

Nuxt executes all global middleware on the initial page load (both on server and client) and then again before any client-side navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.

For details about each type and examples, see the [Middleware documentation](/docs/4.x/directory-structure/app/middleware).

Any redirection on the server will result in a `Location:` header being sent to the browser; the browser then makes a fresh request to this new location. All application state will be reset when this happens, unless persisted in a cookie.

<read-more to="/docs/4.x/directory-structure/app/middleware">



</read-more>

### Page and components

Nuxt renders the page and its components and fetches any required data with `useFetch` and `useAsyncData` during this step. Since there are no dynamic updates and no DOM operations occur on the server, Vue lifecycle hooks such as `onBeforeMount`, `onMounted`, and subsequent hooks are **NOT** executed during SSR.

By default, Vue pauses dependency tracking during SSR for better performance.

<callout icon="i-lucide-lightbulb">

There is no reactivity on the server side because Vue SSR renders the app top-down as static HTML, making it impossible to go back and modify content that has already been rendered.

</callout>

<important>

You should avoid code that produces side effects that need cleanup in root scope of `<script setup>`. An example of such side effects is setting up timers with `setInterval`. In client-side only code we may setup a timer and then tear it down in `onBeforeUnmount` or `onUnmounted`. However, because the unmount hooks will never be called during SSR, the timers will stay around forever. To avoid this, move your side-effect code into `onMounted` instead.

</important>

<tip icon="i-lucide-video" target="_blank" to="https://youtu.be/dZSNW07sO-A">

Watch a video from Daniel Roe explaining Server Rendering and Global State.

</tip>

### HTML Output

After all required data is fetched and the components are rendered, Nuxt combines the rendered components with settings from `unhead` to generate a complete HTML document. This HTML, along with the associated data, is then sent back to the client to complete the SSR process.

<callout icon="i-lucide-lightbulb">

After rendering the Vue application to HTML, Nuxt calls the [`app:rendered`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook.

</callout>

<callout icon="i-lucide-lightbulb">

Before finalizing and sending the HTML, Nitro will call the [`render:html`](/docs/4.x/api/advanced/hooks#nitro-app-hooks-runtime-server-side) hook. This hook allows you to manipulate the generated HTML, such as injecting additional scripts or modifying meta tags.

</callout>
</steps>

## Client lifecycle

This part of the lifecycle is fully executed in the browser, no matter which Nuxt mode you've chosen.

<steps>

### App plugins

This step is similar to the server-side execution and includes both built-in and custom plugins.

Custom plugins in the `app/plugins/` directory, such as those without a suffix (e.g., `myPlugin.ts`) and with the `.client` suffix (e.g., `myClientPlugin.client.ts`), are executed on the client side.

<callout icon="i-lucide-lightbulb">

After this step, Nuxt calls the [`app:created`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook, which can be used to execute additional logic.

</callout>

<read-more to="/docs/4.x/directory-structure/app/plugins">



</read-more>

### Route validation

This step is the same as the server-side execution and includes the `validate` method if defined in the `definePageMeta` function.

### App middleware

Nuxt middleware runs on both the server and the client. If you want certain code to run in specific environments, consider splitting it by using `import.meta.client` for the client and `import.meta.server` for the server.

<read-more to="/docs/4.x/directory-structure/app/middleware#when-middleware-runs">



</read-more>

### Mount Vue app and hydrate

Calling `app.mount('#__nuxt')` mounts the Vue application to the DOM. If the application uses SSR or SSG mode, Vue performs a hydration step to make the client-side application interactive. During hydration, Vue recreates the application (excluding [Server Components](/docs/4.x/directory-structure/app/components#server-components)), matches each component to its corresponding DOM nodes, and attaches DOM event listeners.

To ensure proper hydration, it's important to maintain consistency between the data on the server and the client. For API requests, it is recommended to use `useAsyncData`, `useFetch`, or other SSR-friendly composables. These methods ensure that the data fetched on the server side is reused during hydration, avoiding repeated requests. Any new requests should only be triggered after hydration, preventing hydration errors.

<callout icon="i-lucide-lightbulb">

Before mounting the Vue application, Nuxt calls the [`app:beforeMount`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook.

</callout>

<callout icon="i-lucide-lightbulb">

After mounting the Vue application, Nuxt calls the [`app:mounted`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) hook.

</callout>

### Vue lifecycle

Unlike on the server, the browser executes the full [Vue lifecycle](https://vuejs.org/guide/essentials/lifecycle).

</steps>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-link.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-link.md

# <NuxtLink>

> Nuxt provides <NuxtLink> component to handle any kind of links within your application.

<note>

`<NuxtLink>` is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is *internal* or *external* and renders it accordingly with available optimizations (prefetching, default attributes, etc.)

</note>

## Internal Routing

In this example, we use `<NuxtLink>` component to link to another page of the application.

<code-group>

```vue [app/pages/index.vue]
<template>
  <NuxtLink to="/about">About page</NuxtLink>
</template>
```

```html [(Renders as) index.html]
<!-- (Vue Router & Smart Prefetching) -->
<a href="/about">About page</a>
```

</code-group>

### Passing Params to Dynamic Routes

In this example, we pass the `id` param to link to the route `~/pages/posts/[id].vue`.

<code-group>

```vue [app/pages/index.vue]
<template>
  <NuxtLink :to="{ name: 'posts-id', params: { id: 123 } }">
    Post 123
  </NuxtLink>
</template>
```

```html [(Renders as) index.html]
<a href="/posts/123">Post 123</a>
```

</code-group>

<tip>

Check out the Pages panel in Nuxt DevTools to see the route name and the params it might take.

</tip>

<tip>

When you pass an object into the `to` prop, `<NuxtLink>` will inherit Vue Router’s handling of query parameters. Keys and values will be automatically encoded, so you don’t need to call `encodeURI` or `encodeURIComponent` manually.

</tip>

### Handling Static File and Cross-App Links

By default, `<NuxtLink>` uses Vue Router's client side navigation for relative route. When linking to static files in the `/public` directory or to another application hosted on the same domain, it might result in unexpected 404 errors because they are not part of the client routes. In such cases, you can use the `external` prop with `<NuxtLink>` to bypass Vue Router's internal routing mechanism.

The `external` prop explicitly indicates that the link is external. `<NuxtLink>` will render the link as a standard HTML `<a>` tag. This ensures the link behaves correctly, bypassing Vue Router’s logic and directly pointing to the resource.

#### Linking to Static Files

For static files in the `/public` directory, such as PDFs or images, use the `external` prop to ensure the link resolves correctly.

```vue [app/pages/index.vue]
<template>
  <NuxtLink
    to="/example-report.pdf"
    external
  >
    Download Report
  </NuxtLink>
</template>
```

#### Linking to a Cross-App URL

When pointing to a different application on the same domain, using the `external` prop ensures the correct behavior.

```vue [app/pages/index.vue]
<template>
  <NuxtLink
    to="/another-app"
    external
  >
    Go to Another App
  </NuxtLink>
</template>
```

Using the `external` prop or relying on automatic handling ensures proper navigation, avoids unexpected routing issues, and improves compatibility with static resources or cross-application scenarios.

## External Routing

In this example, we use `<NuxtLink>` component to link to a website.

```vue [app/app.vue]
<template>
  <NuxtLink to="https://nuxtjs.org">
    Nuxt website
  </NuxtLink>
  <!-- <a href="https://nuxtjs.org" rel="noopener noreferrer">...</a> -->
</template>
```

## `rel` and `noRel` Attributes

A `rel` attribute of `noopener noreferrer` is applied by default to links with a `target` attribute or to absolute links (e.g., links starting with `http://`, `https://`, or `//`).

- `noopener` solves a [security bug](https://mathiasbynens.github.io/rel-noopener/) in older browsers.
- `noreferrer` improves privacy for your users by not sending the `Referer` header to the linked site.

These defaults have no negative impact on SEO and are considered [best practice](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener).

When you need to overwrite this behavior you can use the `rel` or `noRel` props.

```vue [app/app.vue]
<template>
  <NuxtLink to="https://twitter.com/nuxt_js">
    Nuxt Twitter
  </NuxtLink>
  <!-- <a href="https://twitter.com/nuxt_js" rel="noopener noreferrer">...</a> -->

  <NuxtLink
    to="https://discord.nuxtjs.org"
    rel="noopener"
  >
    Nuxt Discord
  </NuxtLink>
  <!-- <a href="https://discord.nuxtjs.org" rel="noopener">...</a> -->

  <NuxtLink
    to="/about"
    target="_blank"
  >About page</NuxtLink>
  <!-- <a href="/about" target="_blank" rel="noopener noreferrer">...</a> -->
</template>
```

A `noRel` prop can be used to prevent the default `rel` attribute from being added to the absolute links.

```vue [app/app.vue]
<template>
  <NuxtLink
    to="https://github.com/nuxt"
    no-rel
  >
    Nuxt GitHub
  </NuxtLink>
  <!-- <a href="https://github.com/nuxt">...</a> -->
</template>
```

<note>

`noRel` and `rel` cannot be used together. `rel` will be ignored.

</note>

## Prefetch Links

Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link. Nuxt only loads the resources when the browser isn't busy and skips prefetching if your connection is offline or if you only have 2g connection.

```vue [app/pages/index.vue]
<NuxtLink to="/about" no-prefetch>
About page not pre-fetched
</NuxtLink>

<NuxtLink to="/about" :prefetch="false">
About page not pre-fetched
</NuxtLink>
```

### Custom Prefetch Triggers

We now support custom prefetch triggers for `<NuxtLink>` after `v3.13.0`. You can use the `prefetchOn` prop to control when to prefetch links.

```vue
<template>
  <NuxtLink prefetch-on="visibility">
    This will prefetch when it becomes visible (default)
  </NuxtLink>

  <NuxtLink prefetch-on="interaction">
    This will prefetch when hovered or when it gains focus
  </NuxtLink>
</template>
```

- `visibility`: Prefetches when the link becomes visible in the viewport. Monitors the element's intersection with the viewport using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API). Prefetching is triggered when the element is scrolled into view.
- `interaction`: Prefetches when the link is hovered or focused. This approach listens for `pointerenter` and `focus` events, proactively prefetching resources when the user indicates intent to interact.

You can also use an object to configure `prefetchOn`:

```vue
<template>
  <NuxtLink :prefetch-on="{ interaction: true }">
    This will prefetch when hovered or when it gains focus
  </NuxtLink>
</template>
```

That you probably don't want both enabled!

```vue
<template>
  <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
    This will prefetch when hovered/focus - or when it becomes visible
  </NuxtLink>
</template>
```

This configuration will observe when the element enters the viewport and also listen for `pointerenter` and `focus` events. This may result in unnecessary resource usage or redundant prefetching, as both triggers can prefetch the same resource under different conditions.

### Enable Cross-origin Prefetch

To enable cross-origin prefetching, you can set the `crossOriginPrefetch` option in your `nuxt.config`. This will enable cross-origin prefetching using the [Speculation Rules API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    crossOriginPrefetch: true,
  },
})
```

### Disable prefetch globally

It's also possible to enable/disable prefetching all links globally for your app.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: false,
      },
    },
  },
})
```

## Props

### RouterLink

When not using `external`, `<NuxtLink>` supports all Vue Router's [`RouterLink` props](https://router.vuejs.org/api/interfaces/routerlinkprops)

- `to`: Any URL or a [route location object](https://router.vuejs.org/api/type-aliases/routelocation) from Vue Router
- `custom`: Whether `<NuxtLink>` should wrap its content in an `<a>` element. It allows taking full control of how a link is rendered and how navigation works when it is clicked. Works the same as [Vue Router's `custom` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#custom-)
- `exactActiveClass`: A class to apply on exact active links. Works the same as [Vue Router's `exactActiveClass` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#exactActiveClass-) on internal links. Defaults to Vue Router's default (`"router-link-exact-active"`)
- `activeClass`: A class to apply on active links. Works the same as [Vue Router's `activeClass` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#activeClass-) on internal links. Defaults to Vue Router's default (`"router-link-active"`)
- `replace`: Works the same as [Vue Router's `replace` prop](https://router.vuejs.org/api/interfaces/routelocationoptions#replace-) on internal links
- `ariaCurrentValue`: An `aria-current` attribute value to apply on exact active links. Works the same as [Vue Router's `ariaCurrentValue` prop](https://router.vuejs.org/api/interfaces/routerlinkprops#ariaCurrentValue-) on internal links

### NuxtLink

- `href`: An alias for `to`. If used with `to`, `href` will be ignored
- `noRel`: If set to `true`, no `rel` attribute will be added to the external link
- `external`: Forces the link to be rendered as an `<a>` tag instead of a Vue Router `RouterLink`.
- `prefetch`: When enabled will prefetch middleware, layouts and payloads (when using [payloadExtraction](/docs/4.x/guide/going-further/experimental-features#payloadextraction)) of links in the viewport. Used by the experimental [crossOriginPrefetch](/docs/4.x/guide/going-further/experimental-features#crossoriginprefetch) config.
- `prefetchOn`: Allows custom control of when to prefetch links. Possible options are `interaction` and `visibility` (default). You can also pass an object for full control, for example: `{ interaction: true, visibility: true }`. This prop is only used when `prefetch` is enabled (default) and `noPrefetch` is not set.
- `noPrefetch`: Disables prefetching.
- `prefetchedClass`: A class to apply to links that have been prefetched.

### Anchor

- `target`: A `target` attribute value to apply on the link
- `rel`: A `rel` attribute value to apply on the link. Defaults to `"noopener noreferrer"` for external links.

<tip>

Defaults can be overwritten, see [overwriting defaults](/docs/4.x/api/components/nuxt-link#overwriting-defaults) if you want to change them.

</tip>

## Overwriting Defaults

### In Nuxt Config

You can overwrite some `<NuxtLink>` defaults in your [`nuxt.config`](/docs/4.x/guide/going-further/experimental-features#defaults)

<important>

These options will likely be moved elsewhere in the future, such as into `app.config` or into the `app/` directory.

</important>

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        // default values
        componentName: 'NuxtLink',
        externalRelAttribute: 'noopener noreferrer',
        activeClass: 'router-link-active',
        exactActiveClass: 'router-link-exact-active',
        prefetchedClass: undefined, // can be any valid string class name
        trailingSlash: undefined, // can be 'append' or 'remove'
        prefetch: true,
        prefetchOn: { visibility: true },
      },
    },
  },
})
```

### Custom Link Component

You can overwrite `<NuxtLink>` defaults by creating your own link component using `defineNuxtLink`.

```ts [app/components/MyNuxtLink.ts]
export default defineNuxtLink({
  componentName: 'MyNuxtLink',
  /* see signature below for more */
})
```

You can then use `<MyNuxtLink />` component as usual with your new defaults.

### `defineNuxtLink` Signature

```ts
interface NuxtLinkOptions {
  componentName?: string
  externalRelAttribute?: string
  activeClass?: string
  exactActiveClass?: string
  trailingSlash?: 'append' | 'remove'
  prefetch?: boolean
  prefetchedClass?: string
  prefetchOn?: Partial<{
    visibility: boolean
    interaction: boolean
  }>
}
function defineNuxtLink (options: NuxtLinkOptions): Component {}
```

- `componentName`: A name for the component. Default is `NuxtLink`.
- `externalRelAttribute`: A default `rel` attribute value applied on external links. Defaults to `"noopener noreferrer"`. Set it to `""` to disable
- `activeClass`: A default class to apply on active links. Works the same as [Vue Router's `linkActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkActiveClass-). Defaults to Vue Router's default (`"router-link-active"`)
- `exactActiveClass`: A default class to apply on exact active links. Works the same as [Vue Router's `linkExactActiveClass` option](https://router.vuejs.org/api/interfaces/routeroptions#linkExactActiveClass-). Defaults to Vue Router's default (`"router-link-exact-active"`)
- `trailingSlash`: An option to either add or remove trailing slashes in the `href`. If unset or not matching the valid values `append` or `remove`, it will be ignored.
- `prefetch`: Whether or not to prefetch links by default.
- `prefetchOn`: Granular control of which prefetch strategies to apply by default.
- `prefetchedClass`: A default class to apply to links that have been prefetched.

<link-example to="/docs/4.x/examples/routing/pages">



</link-example>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-loading-indicator.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-loading-indicator.md

# <NuxtLoadingIndicator>

> Display a progress bar between page navigations.

## Usage

Add `<NuxtLoadingIndicator/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts).

```vue [app/app.vue]
<template>
  <NuxtLoadingIndicator />
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>
```

<link-example to="/docs/4.x/examples/routing/pages">



</link-example>

## Slots

You can pass custom HTML or components through the loading indicator's default slot.

## Props

- `color`: The color of the loading bar. It can be set to `false` to turn off explicit color styling.
- `errorColor`: The color of the loading bar when `error` is set to `true`.
- `height`: Height of the loading bar, in pixels (default `3`).
- `duration`: Duration of the loading bar, in milliseconds (default `2000`).
- `throttle`: Throttle the appearing and hiding, in milliseconds (default `200`).
- `estimatedProgress`: By default Nuxt will back off as it approaches 100%. You can provide a custom function to customize the progress estimation, which is a function that receives the duration of the loading bar (above) and the elapsed time. It should return a value between 0 and 100.

<note>

This component is optional. <br />


To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-loading-indicator.ts).

</note>

<note>

You can hook into the underlying indicator instance using [the `useLoadingIndicator` composable](/docs/4.x/api/composables/use-loading-indicator), which will allow you to trigger start/finish events yourself.

</note>

<tip>

The loading indicator's speed gradually decreases after reaching a specific point controlled by `estimatedProgress`. This adjustment provides a more accurate reflection of longer page loading times and prevents the indicator from prematurely showing 100% completion.

</tip>

---

# Source: https://nuxt.com/raw/blog/nuxt-on-the-edge.md

# Nuxt on the Edge

> Learn how we made Nuxt 3 capable of running on edge runtimes to run with server-side rendering close to your users.

## Introduction

In September 2017, Cloudflare [introduced Cloudflare Workers](https://blog.cloudflare.com/introducing-cloudflare-workers/), giving the ability to run JavaScript on their [edge network](https://www.cloudflare.com/network/). This means your code will deploy on the entire edge network in over a hundred locations worldwide in about 30 seconds. This technology allows you to focus on writing your application close to your users, wherever they are in the world (~50ms latency).

The worker's runtime is not the same as Node.js or the Browser, it executes the code using V8, the JavaScript engine developed by Google Chrome. Until now, what you could run on their platform were small scripts running on the edge before hitting your server to increase the performance or add some logic based on request headers, for example.

In November 2020, while working on Nuxt 3, **we made the bet to run Nuxt in-production on edge runtimes / V8 isolates**.

It unlocks the ability to server-render pages in ~50ms from all over the world when using a platform like CloudFlare Workers, without having to deal with servers, load balancers and caching, for about [$0.3 per million requests](https://developers.cloudflare.com/workers/platform/pricing/). As of today, new platforms are coming to let run apps on V8 isolates such as Deno Deploy.

<note>

**2024 update:** I released [NuxtHub](https://hub.nuxt.com) to let you build full-stack applications with Nuxt on the edge, on your Cloudflare account with zero configuration. It includes a database, blob storage, KV, remote storage and more.

</note>

## The Challenge

In order to make Nuxt run in workers, we had to rewrite some parts of Nuxt to be environmentally agnostic (runs in Node.js, Browser or V8).

We started with our server and created [unjs/h3](http://github.com/unjs/h3): a minimal http framework built for high performance and portability. It replaces [Connect](https://github.com/senchalabs/connect) we used in Nuxt 2 but has compatibility with it so you can keep using Connect/Express middleware. In the workers, for each incoming request, it starts Nuxt in production, sends the request to it and sends back the response.

In Nuxt 2, the duration to start the server in production in memory (also named cold start) was about ~300ms, because we had to load all the dependencies of your server and application in order to handle the request.

By working on h3, we decided to code-split each handler attached to the server and lazy-load them only when requested. When you start Nuxt 3, we only load h3 in memory and the corresponding handlers. When a request comes in, we load the handler corresponding to the route and execute it.

<video :controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1689236511/nuxt3/nuxt3-server-performance.jpg" src="https://res.cloudinary.com/nuxt/video/upload/v1689236511/nuxt3/nuxt3-server-performance.mp4">



</video>

By adopting this approach, **we reduced the cold start from ~300ms to ~2ms**.

We had another challenge in order to run Nuxt on the edge: the production bundle size. This includes the server, Vue app and Node.js dependencies combined. Cloudflare workers currently have a limit of 1MB (free plan) and 5MB ($5 per month plan) for the worker size.

In order to achieve this, we created [unjs/nitro](https://nitro.unjs.io/), our server engine, when running the `nuxt build` command, it bundles your whole project and includes all dependencies into the final output. It uses [Rollup](https://rollupjs.org/) and [vercel/nft](https://github.com/vercel/nft) to trace only the code used by the `node_modules` to remove unnecessary code. **The total size of the generated output for a basic Nuxt 3 application is about 700kB gzip.**

Lastly, to provide the same developer experience between development (Node.js) and production on Cloudflare (Edge runtime), we created [unjs/unenv](https://github.com/unjs/unenv): a library to convert JavaScript code to run everywhere (platform agnostic) by mocking or adding polyfills for known dependencies.

**At Nuxt, we believe that you should have the freedom to choose the hosting provider that fits you best.**

This is why you can deploy a Nuxt application with edge-side rendering on:

- [NuxtHub](https://hub.nuxt.com)
- [Cloudflare Page](https://nitro.unjs.io/deploy/providers/cloudflare#cloudflare-pages)
- [Deno Deploy](https://nitro.unjs.io/deploy/providers/deno-deploy)
- [Vercel Edge Functions](https://nitro.unjs.io/deploy/providers/vercel#vercel-edge-functions) (using CloudFlare Workers under the hood)
- [Netlify Edge Functions](https://nitro.unjs.io/deploy/providers/netlify#netlify-edge-functions) (using Deno under the hood)

We also support many other deployment providers, including [static hosting](/docs/getting-started/deployment#static-hosting) or [traditional Node.js serverless and server hosts](/docs/getting-started/deployment#nodejs-server).

## Pushing Full-stack Capabilities

Now that we have Nuxt running on edge runtime, we can do more than render a Vue application. Thanks to the [server directory](/docs/guide/directory-structure/server), creating an API route is a TypeScript file away.

To add the `/api/hello` route, create a `server/api/hello.ts` file:

```ts [server/api/hello.ts]
export default defineEventHandler((event) => {
  return {
    hello: 'world'
  }
})
```

You can now universally call this API in your pages and components:

```vue [pages/index.vue]
<script setup>
const { data } = await useFetch('/api/hello')
</script>

<template>
  <pre>{{ data }}</pre>
</template>
```

One important thing to note when we created [useFetch](/docs/api/composables/use-fetch) and [$fetch](/docs/api/utils/dollarfetch) is that during server-side rendering, if you call your API routes, it will emulate the request and call the function code directly: **avoiding an HTTP request and reducing page’s rendering time**.

In terms of developer experience, you will notice that when creating server files, the Nuxt server keeps running without rebuilding the Vue app. **This is because Nuxt 3 supports Hot Module Replacement (HMR) when creating API and server routes.**

Furthermore, by leveraging Object Relational Mapping (ORM) like [drizzle-orm](https://orm.drizzle.team/), developers can connect Edge & Serverless databases such as [D1](https://developers.cloudflare.com/d1/), [Turso](https://turso.tech/), [Neon](https://neon.tech), [Planetscale](https://planetscale.com/) and more.

I created [Atidone](https://todos.nuxt.dev/), an open source demo to showcase a full-stack application with authentication and a database running on the edge. The source code is available on GitHub under the MIT license at [atinux/atidone](https://github.com/atinux/atidone).

## Conclusion

We are excited about edge-side rendering and what it unlocks. Our team at Nuxt can’t wait to see what you will build on top of this!

Feel free to join our [Discord server](https://discord.com/invite/nuxt) or mention [@nuxt_js](https://x.com/nuxt_js) on Twitter to share your work.

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-page.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-page.md

# <NuxtPage>

> The <NuxtPage> component is required to display pages located in the pages/ directory.

`<NuxtPage>` is a built-in component that comes with Nuxt. It lets you display top-level or nested pages located in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory.

<note>

`<NuxtPage>` is a wrapper around [`<RouterView>`](https://router.vuejs.org/api/interfaces/routerviewprops) from Vue Router. It should be used instead of `<RouterView>` because the former takes additional care of internal states. Otherwise, `useRoute()` may return incorrect paths.

</note>

`<NuxtPage>` includes the following components:

```vue
<template>
  <RouterView v-slot="{ Component }">
    <!-- Optional, when using transitions -->
    <Transition>
      <!-- Optional, when using keep-alive -->
      <KeepAlive>
        <Suspense>
          <component :is="Component" />
        </Suspense>
      </KeepAlive>
    </Transition>
  </RouterView>
</template>
```

By default, Nuxt does not enable `<Transition>` and `<KeepAlive>`. You can enable them in the nuxt.config file or by setting the `transition` and `keepalive` properties on `<NuxtPage>`. If you want to define a specific page, you can set it in `definePageMeta` in the page component.

<warning>

If you enable `<Transition>` in your page component, ensure that the page has a single root element.

</warning>

Since `<NuxtPage>` uses `<Suspense>` under the hood, the component lifecycle behavior during page changes differs from that of a typical Vue application.

In a typical Vue application, a new page component is mounted **only after** the previous one has been fully unmounted. However, in Nuxt, due to how Vue `<Suspense>` is implemented, the new page component is mounted **before** the previous one is unmounted.

## Props

- `name`: tells `<RouterView>` to render the component with the corresponding name in the matched route record's components option.

  - type: `string`
- `route`: route location that has all of its components resolved.

  - type: `RouteLocationNormalized`
- `pageKey`: control when the `NuxtPage` component is re-rendered.

  - type: `string` or `function`
- `transition`: define global transitions for all pages rendered with the `NuxtPage` component.

  - type: `boolean` or [`TransitionProps`](https://vuejs.org/api/built-in-components#transition)
- `keepalive`: control state preservation of pages rendered with the `NuxtPage` component.

  - type: `boolean` or [`KeepAliveProps`](https://vuejs.org/api/built-in-components#keepalive)

<tip>

Nuxt automatically resolves the `name` and `route` by scanning and rendering all Vue component files found in the `/pages` directory.

</tip>

## Example

For example, if you pass a key that never changes, the `<NuxtPage>` component will be rendered only once - when it is first mounted.

```vue [app/app.vue]
<template>
  <NuxtPage page-key="static" />
</template>
```

You can also use a dynamic key based on the current route:

```html
<NuxtPage :page-key="route => route.fullPath" />
```

<warning>

Don't use `$route` object here as it can cause problems with how `<NuxtPage>` renders pages with `<Suspense>`.

</warning>

Alternatively, `pageKey` can be passed as a `key` value via [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) from the `<script>` section of your Vue component in the `/pages` directory.

```vue [app/pages/my-page.vue]
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,
})
</script>
```

<link-example to="/docs/4.x/examples/routing/pages">



</link-example>

## Page's Ref

To get the `ref` of a page component, access it through `ref.value.pageRef`

```vue [app/app.vue]
<script setup lang="ts">
const page = ref()

function logFoo () {
  page.value.pageRef.foo()
}
</script>

<template>
  <NuxtPage ref="page" />
</template>
```

```vue [my-page.vue]
<script setup lang="ts">
const foo = () => {
  console.log('foo method called')
}

defineExpose({
  foo,
})
</script>
```

## Custom Props

`<NuxtPage>` also accepts custom props that you may need to pass further down the hierarchy.

For example, in the below example, the value of `foobar` will be passed to the `NuxtPage` component and then to the page components.

```vue [app/app.vue]
<template>
  <NuxtPage :foobar="123" />
</template>
```

We can access the `foobar` prop in the page component:

```vue [app/pages/page.vue]
<script setup lang="ts">
const props = defineProps<{ foobar: number }>()

console.log(props.foobar) // Outputs: 123
```

If you have not defined the prop with `defineProps`, any props passed down to `NuxtPage` can still be accessed directly from the page `attrs`:

```vue [app/pages/page.vue]
<script setup lang="ts">
const attrs = useAttrs()
console.log(attrs.foobar) // Outputs: 123
</script>
```

<read-more to="/docs/4.x/directory-structure/app/pages">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-picture.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-picture.md

# <NuxtPicture>

> Nuxt provides a <NuxtPicture> component to handle automatic image optimization.

`<NuxtPicture>` is a drop-in replacement for the native `<picture>` tag.

Usage of `<NuxtPicture>` is almost identical to [`<NuxtImg>`](/docs/4.x/api/components/nuxt-img) but it also allows serving modern formats like `webp` when possible.

Learn more about the [`<picture>` tag on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/picture).

## Setup

In order to use `<NuxtPicture>` you should install and enable the Nuxt Image module:

```bash [Terminal]
npx nuxt module add image
```

<read-more target="_blank" to="https://image.nuxt.com/usage/nuxt-picture">

Read more about the `<NuxtPicture>` component.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-route-announcer.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-route-announcer.md

# <NuxtRouteAnnouncer>

> The <NuxtRouteAnnouncer> component adds a hidden element with the page title to announce route changes to assistive technologies.

<important>

This component is available in Nuxt v3.12+.

</important>

## Usage

Add `<NuxtRouteAnnouncer/>` in your [`app.vue`](/docs/4.x/directory-structure/app/app) or [`app/layouts/`](/docs/4.x/directory-structure/app/layouts) to enhance accessibility by informing assistive technologies about page title changes. This ensures that navigational changes are announced to users relying on screen readers.

```vue [app/app.vue]
<template>
  <NuxtRouteAnnouncer />
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>
```

## Slots

You can pass custom HTML or components through the route announcer's default slot.

```vue
<template>
  <NuxtRouteAnnouncer>
    <template #default="{ message }">
      <p>{{ message }} was loaded.</p>
    </template>
  </NuxtRouteAnnouncer>
</template>
```

## Props

- `atomic`: Controls if screen readers only announce changes or the entire content. Set to true for full content readouts on updates, false for changes only. (default `false`)
- `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately). (default `polite`)

<callout>

This component is optional. <br />


To achieve full customization, you can implement your own one based on [its source code](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/components/nuxt-route-announcer.ts).

</callout>

<callout>

You can hook into the underlying announcer instance using [the `useRouteAnnouncer` composable](/docs/4.x/api/composables/use-route-announcer), which allows you to set a custom announcement message.

</callout>

---

# Source: https://nuxt.com/raw/blog/nuxt-scripts.md

# Introducing Nuxt Scripts

> Nuxt Scripts provides better performance, privacy, security, and developer experience for third-party scripts.

The Nuxt team, in collaboration with the [Chrome Aurora](https://developer.chrome.com/aurora) team at Google, is excited to announce the public beta release of [Nuxt Scripts](https://scripts.nuxt.com).

Nuxt Scripts is a better way to work with third-party scripts, providing improved performance, privacy, security, and developer experience.

![Nuxt Scripts Banner](/assets/blog/nuxt-scripts/banner.png)

## Getting to Nuxt Scripts

Over a year ago, Daniel published the initial [Nuxt Scripts RFC](https://github.com/nuxt/nuxt/discussions/22016). The RFC proposed a module that would "allow third-party scripts to be managed and optimized, following best practices for performant and compliant websites".

Having [personal experience](https://github.com/harlan-zw/nuxt-delay-hydration) with solving performance issues related to third-party scripts, I knew how difficult these performance optimizations could be. Nonetheless, I was keen to tackle the problem and took over the project.

With the RFC as the seed of the idea, I started prototyping what it could [look like](https://github.com/nuxt/nuxt/discussions/22016#discussioncomment-6527001) using [Unhead](https://unhead.unjs.io/).

Thinking about what I wanted to build exactly, I found that the real issue wasn't just how to load "optimized" third-party scripts but how to make working with third-party scripts a better experience overall.

## Why Build a Third-Party Script Module?

[94% of sites use at least one third-party provider](https://almanac.httparchive.org/en/2022/third-parties#prevalence), with the average site having [five third-party providers](https://docs.google.com/spreadsheets/d/1YqoRRsyiNsrEabVLu2nRU98JIG_0zLLuoQhC2nX8xbM/edit?gid=1428106498#gid=1428106498).

We know that third-party scripts aren't perfect; they [slow down the web](https://web.dev/articles/optimizing-content-efficiency-loading-third-party-javascript#), cause privacy and security issues, and are a pain to work with.

However, they are fundamentally useful and aren't going anywhere soon.

By exploring the issues with third-party scripts, we can see where improvements can be made.

### 😒 Developer Experience: A Full-Stack Headache

Let's walk through adding a third-party script to your Nuxt app using a fictional `tracker.js` script that adds a `track` function to the window.

We start by loading the script using `useHead`.

```ts
useHead({ script: [{ src: '/tracker.js', defer: true }] })
```

However, let's now try to get the script functionality working in our app.

The following steps are common when working with third-party scripts in Nuxt:

- Everything has to be wrapped for SSR safety.
- Flaky checks for if the script has loaded.
- Augmenting the window object for types.

<code-group>

```vue [1: SSR Safety]
<script setup>
// ❌ Oops, window is not defined! 
// 💡 The window can't be directly accessed if we use SSR in Nuxt.
// 👉 We need to make this SSR safe
window.track('page_view', useRoute().path)
</script>
```

```vue [2: Script Timing]
<script setup>
if (import.meta.client) {
  // ❌ Oops, the script hasn't finished loading yet!
  // 💡 A `defer` script may not be available while our Nuxt app hydrates.
  // 👉 We need to wait for the script to be loaded
  window.track('page_view', useRoute().path)
}
</script>
```

```vue [3: Broken types]
<script lang="ts" setup>
if (import.meta.client) {
  useTimeoutFn(() => {
    // ✅ It's working!
    // ❌ Oops, types are broken.
    // 💡 The `window` has strict types and nothing is defined yet.
    // 👉 We need to manually augment the window
    window.track('page_view', useRoute().path)
  }, 1000 /* should be loaded in 1 second!? */)
}
</script>
```

```vue [4: It works?]
<script lang="ts" setup>
declare global {
  interface Window {
    track: (e: string, p: string) => void
  }
}
if (import.meta.client) {
  useTimeoutFn(() => {
    // ✅ It's working and types are valid! 
    // ❌ Oops, ad-blockers, GDPR and duplicate scripts
    // 💡 There's a lot of hidden complexity in third-party scripts
    // 👉 We need a better API
    window.track('page_view', useRoute().path)
  }, 1000)
}
</script>
```

</code-group>

### 🐌 Performance: "Why can't I get 100 on Lighthouse?"

For a visitor to start interacting with your Nuxt site, the app bundle needs to be downloaded and Vue needs to hydrate the app instance.

Loading third-party scripts can interfere with this hydration process, even when using `async` or `defer`. This slows down the network and blocks the main thread, leading to a degraded user experience and poor [Core Web Vitals](https://web.dev/vitals/).

The [Chrome User Experience Report](https://developer.chrome.com/docs/crux) shows Nuxt sites with numerous third-party resources typically have poorer [Interaction to Next Paint (INP)](https://web.dev/articles/inp) and [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp) scores.

To see how third-party scripts degrade performance, we can look at the [Web Almanac 2022](https://almanac.httparchive.org/en/2022/third-parties#impact-on-performance). The report shows that the top 10 third-party scripts **average median blocking time is 1.4 seconds**.

### 🛡️ Privacy & Security: Do *no* evil?

Of the top 10,000 sites, 58% of them have third-party scripts that [exchange tracking IDs stored in external cookies](https://www3.cs.stonybrook.edu/~mikepo/papers/firstparty.www21.pdf), meaning they can track users across sites even with third-party cookies disabled.

While in many cases our hands are tied with the providers we use, we should try to minimize the amount of our end-users' data that we're leaking where possible.

When we do take on the privacy implications, it can then be difficult to accurately convey these in our privacy policies and build the consent management required to comply with regulations such as GDPR.

Security when using third-party scripts is also a concern. Third-party scripts are common attack vectors for malicious actors, most do not provide `integrity` hashes for their scripts, meaning they can be compromised and inject malicious code into your app at any time.

## What does Nuxt Scripts do about these issues?

### Composable: useScript

This composable sits between the `<script>` tag and the functionality added to `window.{thirdPartyKey}`.

For the `<script>` tag, the composable:

- Gives full visibility into the script's loading and error states
- Loads scripts as Nuxt is hydrating the app by default, for slightly better performance.
- Restricts `crossorigin` and `referrerpolicy` to improve privacy and security.
- Provides a way to [delay loading the script](https://scripts.nuxt.com/docs/guides/script-triggers) until you need it.

For the scripts API, it:

- Provides full type-safety around the script's functions
- Adds a proxy layer allowing your app to run when the script functions in unsafe contexts (SSR, before the script is loaded, the script is blocked)

<code-group>

```ts [hello.ts]
const { proxy, onLoaded } = useScript('/hello.js', {
  trigger: 'onNuxtReady',
  use() {
    return window.helloWorld
  }
})

onLoaded(({ greeting }) => {
  // ✅ script is loaded! Hooks into Vue lifecycle
})

// ✅ OR use the proxy API - SSR friendly, called when script is loaded
proxy.greeting() // Hello, World!

declare global {
  interface Window {
    helloWorld: {
      greeting: () => 'Hello World!'
    }
  }
}
```

```ts [hello.js]
window.helloWorld = {
  greeting() {
    console.log('Hello, World!')
  }
}
```

</code-group>

### Script Registry

The [script registry](https://scripts.nuxt.com/scripts) is a collection of first-party integrations for common third-party scripts. As of release, we support 21 scripts, with more to come.

![Nuxt Scripts Registry](/assets/blog/nuxt-scripts/registry.png)

These registry scripts are fine-tuned wrappers around `useScript` with full type-safety, runtime validation of the script options (dev only) and environment variable support

For example, we can look at the [Fathom Analytics](https://scripts.nuxt.com/scripts/analytics/fathom-analytics) script.

```ts
const { proxy } = useScriptFathomAnalytics({
  // ✅ options are validated at runtime
  site: undefined
})
// ✅ typed
proxy.trackPageview()
```

### Facade Components

The registry includes several [facade components](https://scripts.nuxt.com/docs/guides/facade-components), such as
[Google Maps](https://scripts.nuxt.com/scripts/content/google-maps), [YouTube](https://scripts.nuxt.com/scripts/content/youtube-player) and [Intercom](https://scripts.nuxt.com/scripts/support/intercom).

Facade components are "fake" components that get hydrated when the third-party script loads. Facade components
have trade-offs but can drastically improve your performance. See the [What are Facade Components?](https://scripts.nuxt.com/docs/guides/facade-components#what-are-facade-components)
guide for more information.

Nuxt Scripts provides facade components as accessible but headless, meaning they are not styled by default but add the necessary
a16y data.

<tabs>
<tabs-item label="Output">
<youtube-demo>



</youtube-demo>
</tabs-item>

<tabs-item label="Input">

```vue
<script setup lang="ts">
const isLoaded = ref(false)
const isPlaying = ref(false)
const video = ref()
function play() {
  video.value?.player.playVideo()
}
function stateChange(state) {
  isPlaying.value = state.data === 1
}
</script>

<template>
  <ScriptYouTubePlayer ref="video" video-id="d_IFKP1Ofq0" @ready="isLoaded = true" @state-change="stateChange">
    <template #awaitingLoad>
      <div class="absolute left-1/2 top-1/2 transform -translate-x-1/2 -translate-y-1/2 h-[48px] w-[68px]">
        <svg height="100%" version="1.1" viewBox="0 0 68 48" width="100%"><path d="M66.52,7.74c-0.78-2.93-2.49-5.41-5.42-6.19C55.79,.13,34,0,34,0S12.21,.13,6.9,1.55 C3.97,2.33,2.27,4.81,1.48,7.74C0.06,13.05,0,24,0,24s0.06,10.95,1.48,16.26c0.78,2.93,2.49,5.41,5.42,6.19 C12.21,47.87,34,48,34,48s21.79-0.13,27.1-1.55c2.93-0.78,4.64-3.26,5.42-6.19C67.94,34.95,68,24,68,24S67.94,13.05,66.52,7.74z" fill="#f00" /><path d="M 45,24 27,14 27,34" fill="#fff" /></svg>
      </div>
    </template>
  </ScriptYouTubePlayer>
</template>
```

</tabs-item>
</tabs>

### Consent Management & Element Event Triggers

The `useScript` composable gives you full control over how and when your scripts are loaded, by either providing a custom `trigger` or manually calling the `load()` function.

Building on top of this, Nuxt Scripts provides advanced triggers to make it even easier.

- [Consent Management](https://scripts.nuxt.com/docs/guides/consent) - Load scripts only after the user has given consent such as with a cookie banner.
- [Element Event Triggers](https://scripts.nuxt.com/docs/guides/script-triggers#element-event-triggers) - Load scripts based on user interactions such as scrolling, clicking, or form submissions.

```ts
const cookieConsentTrigger = useScriptTriggerConsent()
const { proxy } = useScript<{ greeting: () => void }>('/hello.js', {
  // script will only be loaded once the consent has been accepted
  trigger: cookieConsentTrigger
})
// ...
function acceptCookies() {
  cookieConsentTrigger.accept()
}
// greeting() is queued until the user accepts cookies
proxy.greeting()
```

### Bundling Scripts

In many cases, we're loading third-party scripts from a domain that we don't control. This can lead to a number of issues:

- Privacy: The third-party script can track users across sites.
- Security: The third-party script can be compromised and inject malicious code.
- Performance: Extra DNS lookups will slow down the page load.
- Developer Experience: Consented scripts may be blocked by ad blockers.

To mitigate this, Nuxt Scripts provides a way to bundle third-party scripts into your public directory without any extra work.

```ts
useScript('https://cdn.jsdelivr.net/npm/js-confetti@latest/dist/js-confetti.browser.js', {
  bundle: true,
})
```

The script will now be served from `/_scripts/{hash}` on your own domain.

## To be continued

As we saw, there are many opportunities to improve third-party scripts for developers and end-users.

The initial release of Nuxt Scripts has solved *some* of these issues, but there's still a lot of work ahead of us.

The next items on the roadmap are:

- [Add web worker support (Partytown)](https://github.com/nuxt/scripts/issues/182)
- [More Live Chat Facade Components](https://github.com/nuxt/scripts/issues/44)
- [Offload Scripts To Nuxt Server Proxy](https://github.com/nuxt/scripts/issues/87)
- [Iframe Script Sandboxing](https://github.com/nuxt/scripts/issues/131)

We'd love to have your contribution and support.

## Getting started

To get started with Nuxt Scripts, we've created a [tutorial](https://scripts.nuxt.com/docs/getting-started/confetti-tutorial) to help you get up and running.

## Credits

- [Harlan Wilton - Nuxt](https://github.com/harlan-zw) (author)
- [Julien Huang - Nuxt](https://github.com/huang-julien) (contributor)
- [Daniel Roe - Nuxt](https://github.com/danielroe) (contributor)
- [Chrome Aurora - Google](https://developer.chrome.com/aurora) (contributor)

And a big thank you to the early contributors.

![Nuxt Scripts Contributors](/assets/blog/nuxt-scripts/contributors.png)

---

# Source: https://nuxt.com/raw/blog/nuxt-static-improvements.md

# Nuxt 2 Static Improvements

> With Nuxt version 2.13, the full-static mode has been introduced. In addition, a new command nuxt export was added to pre-render your pages without triggering a webpack build with the goal to separate the rendering and build process. The only issue was that most Nuxt users weren't able to unleash the full potential of the separation... until now.

## Introduction

With Nuxt version 2.13, the [full-static mode](/blog/going-full-static) has been introduced. In addition, a new command `nuxt export` was added to pre-render your pages without triggering a webpack build with the goal to separate the rendering and build process. The only issue was that most Nuxt users weren't able to unleash the full potential of the separation... **until now.**

## Faster Static Deployments

With v2.14, `nuxt generate` will **automagically skip webpack build step when no code has been changed** and use the previous build using cache. This will help to drastically improve static deployments time by avoiding unnecessary builds which is usually the most time-consuming part of generation process. Cache support is **platform-agnostic** and works on Netlify, Vercel, or any other CI/CD setup that is caching `node_modules`.

<video :autoplay="true" :controls="true" autoPlay="true" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1595852304/nuxt-smart-generate_pjaat1.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1595852304/nuxt-smart-generate_pjaat1.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1595852304/nuxt-smart-generate_pjaat1.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1595852304/nuxt-smart-generate_pjaat1.ogg" type="video/ogg" />
</video>

## Generate time: cache vs full webpack build

See the comparison in seconds between two `nuxt generate`:

- `Build` is when a webpack build is required
- `Cache` is only when the content has changed (webpack build skipped)

![Comparison between build VS cache time](/assets/blog/bar-chart-cache-build.png)

<tip>

The static site generation of our projects on content changes are now **~3.6x times** faster 🚀

</tip>

Project links: [Basic](https://github.com/pi0/nuxt-static-demo), [Strapi Module Docs](https://github.com/nuxt-community/strapi-module/tree/master/docs), [Content Module Docs](https://github.com/nuxt/content/tree/master/docs) and [Nuxt 2 Docs](https://github.com/nuxt/website-v2).

## Using in your projects

1. Update `nuxt` to the latest minor version, which is v2.14.

<code-group>

```bash [npm]
npm update
```

```bash [yarn]
yarn upgrade nuxt
```

</code-group>

1. Ensure `target` is `static` inside your `nuxt.config.js`

```js [nuxt.config.js]
export default {
  target: 'static'
  // ...
}
```

`nuxt generate` will behave as before to avoid breaking changes and provide legacy compatibility if you keep `target: ‘server’` or don't specify target.

1. That’s it 🙌

Now, the `nuxt generate` command will build the project only if necessary, which is the case when files inside the project have been changed. It will always re-render your routes to static HTML files, like `nuxt export` is doing already.

Now you only have to change your build command back from `nuxt build && nuxt export` to `nuxt generate` on the platform you are using. If you are using a CI, ensure that you are properly caching `node_modules`.

### Excluding Files from Cache

By default, nuxt ignores these directories so if any change happens inside them, build will not be triggered:

- Build directory (`.nuxt/`)
- Static directory (`static/`)
- Generate dist (`dist/`)
- `node_modules`
- `README.md`
- Hidden dotfiles (like `.npmrc`)

You can add more patterns using [generate.cache.ignore](https://v2.nuxt.com/docs/configuration-glossary/configuration-generate/#cache) option in `nuxt.config`:

```js [nuxt.config.js]
export default {
  generate: {
    cache: {
      ignore: [
        // When something changed in the docs folder, do not re-build via webpack
        'docs'
      ]
    }
  }
}
```

It is also possible to use a function for `ignore` option to override default ignore entries.

### Module Authors

What if you are developing a nuxt module that is working with files that should not trigger a rebuild? The best example is for [@nuxt/content](https://content.nuxt.com) module that reads markdown files from the repository. In this case, these files are used within a runtime module, which is the case when using `@nuxt/content`, the module itself can tell nuxt to ignore these files for you already so you don't have to do anything! Module authors can use the new `generate:cache:ignore` hook to do so:

```js
nuxt.hook('generate:cache:ignore', ignore => ignore.push('content'))
```

## How it works

When using the new `nuxt generate` with `static` target, a snapshot including checksum of non-ignored project files as well as nuxt version and some other configuration will be written `.nuxt/build.json`. In addition, we also move the build directory to `node_modules/.cache/nuxt`. Because `node_modules` is cached by all major platforms (Netlify, Vercel, ...) and common CI/CD scripts, this solution works out of the box without additional configuration.

When `nuxt generate` is called subsequently, it will again create a checksum based on your project files and then compare it to the existing one inside `node_modules/.cache/nuxt/build.json`.

If they match, it means that nothing is changed that needs rebuild so we can directly start rendering pages.

If a mismatch is detected, it means that a full rebuild would be necessary. You can also see what file caused rebuild by checking console logs. After the build, nuxt generate will save the new checksum inside `.nuxt/build.json`. You can check full implementation [here](https://github.com/nuxt/nuxt.js/pull/7712).

### Back to old school commands

With Nuxt v2.13, we introduced `nuxt export` and `nuxt serve` specially designed for the static target. With Nuxt v2.14, they are deprecated as `nuxt generate` and `nuxt start` is smart to detect the target and build when necessary.

Server target:

- `nuxt dev` = development server
- `nuxt build` = build your application for production
- `nuxt start` = start the production server (use it for Node.js hosting like Heroku, DigitalOcean, etc)

Static target:

- `nuxt dev` = development server
- `nuxt generate` = build if needed and statically export to `dist/`
- `nuxt start` = serve the `dist/` directory like your static hosting would do (Netlify, Vercel, Surge, etc), great for testing before deploying

## What to do next

- Upgrade your project to [nuxt@2.14.0](https://github.com/nuxt/nuxt.js/releases/tag/v2.14.0)
- Use `nuxt generate` instead of `nuxt export`
- Use `nuxt start` instead of `nuxt serve`
- Enjoy fast deployments 🤙

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-time.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-time.md

# <NuxtTime>

> The <NuxtTime> component displays time in a locale-friendly format with server-client consistency.

<important>

This component is available in Nuxt v3.17+.

</important>

The `<NuxtTime>` component lets you display dates and times in a locale-friendly format with proper `<time>` HTML semantics. It ensures consistent rendering between server and client without hydration mismatches.

## Usage

You can use the `<NuxtTime>` component anywhere in your app:

```vue
<template>
  <NuxtTime :datetime="Date.now()" />
</template>
```

## Props

### `datetime`

- Type: `Date | number | string`
- Required: `true`

The date and time value to display. You can provide:

- A `Date` object
- A timestamp (number)
- An ISO-formatted date string

```vue
<template>
  <NuxtTime :datetime="Date.now()" />
  <NuxtTime :datetime="new Date()" />
  <NuxtTime datetime="2023-06-15T09:30:00.000Z" />
</template>
```

### `locale`

- Type: `string`
- Required: `false`
- Default: Uses the browser or server's default locale

The [BCP 47 language tag](https://datatracker.ietf.org/doc/html/rfc5646) for formatting (e.g., 'en-US', 'fr-FR', 'ja-JP'):

```vue
<template>
  <NuxtTime
    :datetime="Date.now()"
    locale="fr-FR"
  />
</template>
```

### Formatting Props

The component accepts any property from the [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) options:

```vue
<template>
  <NuxtTime
    :datetime="Date.now()"
    year="numeric"
    month="long"
    day="numeric"
    hour="2-digit"
    minute="2-digit"
  />
</template>
```

This would output something like: "April 22, 2025, 08:30 AM"

### `relative`

- Type: `boolean`
- Required: `false`
- Default: `false`

Enables relative time formatting using the Intl.RelativeTimeFormat API:

```vue
<template>
  <!-- Shows something like "5 minutes ago" -->
  <NuxtTime
    :datetime="Date.now() - 5 * 60 * 1000"
    relative
  />
</template>
```

### Relative Time Formatting Props

When `relative` is set to `true`, the component also accepts properties from [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat):

<warning>

Due to `style` being a reserved prop, `relativeStyle` prop is used instead.

</warning>

```vue
<template>
  <NuxtTime
    :datetime="Date.now() - 3 * 24 * 60 * 60 * 1000"
    relative
    numeric="auto"
    relative-style="long"
  />
</template>
```

This would output something like: "3 days ago" or "last Friday" depending on the `numeric` setting.

## Examples

### Basic Usage

```vue
<template>
  <NuxtTime :datetime="Date.now()" />
</template>
```

### Custom Formatting

```vue
<template>
  <NuxtTime
    :datetime="Date.now()"
    weekday="long"
    year="numeric"
    month="short"
    day="numeric"
    hour="numeric"
    minute="numeric"
    second="numeric"
    time-zone-name="short"
  />
</template>
```

### Relative Time

```vue
<template>
  <div>
    <p>
      <NuxtTime
        :datetime="Date.now() - 30 * 1000"
        relative
      />
      <!-- 30 seconds ago -->
    </p>
    <p>
      <NuxtTime
        :datetime="Date.now() - 45 * 60 * 1000"
        relative
      />
      <!-- 45 minutes ago -->
    </p>
    <p>
      <NuxtTime
        :datetime="Date.now() + 2 * 24 * 60 * 60 * 1000"
        relative
      />
      <!-- in 2 days -->
    </p>
  </div>
</template>
```

### With Custom Locale

```vue
<template>
  <div>
    <NuxtTime
      :datetime="Date.now()"
      locale="en-US"
      weekday="long"
    />
    <NuxtTime
      :datetime="Date.now()"
      locale="fr-FR"
      weekday="long"
    />
    <NuxtTime
      :datetime="Date.now()"
      locale="ja-JP"
      weekday="long"
    />
  </div>
</template>
```

---

# Source: https://nuxt.com/raw/blog/nuxt-ui-v3.md

# Nuxt UI v3

> Nuxt UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS v4 support, and full Vue compatibility

We are thrilled to announce the release of Nuxt UI v3, a complete redesign of our UI library that brings significant improvements in accessibility, performance, and developer experience. This major update represents over 1500 commits of hard work, collaboration, and innovation from our team and the community.

## 🚀 Reimagined from the Ground Up

Nuxt UI v3 represents a major leap forward in our journey to provide the most comprehensive UI solution for Vue and Nuxt developers. This version has been rebuilt from the ground up with modern technologies and best practices in mind.

### **From HeadlessUI to Reka UI**

With Reka UI at its core, Nuxt UI v3 delivers:

• Proper keyboard navigation across all interactive components

• ARIA attributes automatically handled for you

• Focus management that just works

• Screen reader friendly components out of the box

This means you can build applications that work for everyone without becoming an accessibility expert.

### **Tailwind CSS v4 Integration**

The integration with Tailwind CSS v4 brings huge performance improvements:

• **5x faster runtime** with optimized component rendering

• **100x faster build times** thanks to the new CSS-first engine

• Smaller bundle sizes with more efficient styling

Your applications will feel snappier, build quicker, and load faster for your users.

## 🎨 A Brand New Design System

```html
<!-- Before: Inconsistent color usage with duplicate dark mode classes -->
<div class="bg-gray-100 dark:bg-gray-800 p-4 rounded-lg">
  <h2 class="text-gray-900 dark:text-white text-xl mb-2">User Profile</h2>
  <p class="text-gray-600 dark:text-gray-300">Account settings and preferences</p>
  <button class="bg-blue-500 text-white px-3 py-1 rounded mt-2">Edit Profile</button>
</div>
```

```html
<!-- After: Semantic design tokens with automatic dark mode support -->
<div class="bg-muted p-4 rounded-lg">
  <h2 class="text-highlighted text-xl mb-2">User Profile</h2>
  <p class="text-muted">Account settings and preferences</p>
  <UButton color="primary" size="sm" class="mt-2">Edit Profile</UButton>
</div>
```

Our new color system includes 7 semantic color aliases:

<table>
<thead>
  <tr>
    <th>
      Color
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code className="text-primary">
        primary
      </code>
    </td>
    
    <td>
      <code>
        blue
      </code>
    </td>
    
    <td>
      Primary color to represent the brand.
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="text-secondary">
        secondary
      </code>
    </td>
    
    <td>
      <code>
        blue
      </code>
    </td>
    
    <td>
      Secondary color to complement the primary color.
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="text-success">
        success
      </code>
    </td>
    
    <td>
      <code>
        green
      </code>
    </td>
    
    <td>
      Used for success states.
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="text-info">
        info
      </code>
    </td>
    
    <td>
      <code>
        blue
      </code>
    </td>
    
    <td>
      Used for informational states.
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="text-warning">
        warning
      </code>
    </td>
    
    <td>
      <code>
        yellow
      </code>
    </td>
    
    <td>
      Used for warning states.
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="text-error">
        error
      </code>
    </td>
    
    <td>
      <code>
        red
      </code>
    </td>
    
    <td>
      Used for form error validation states.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        neutral
      </code>
    </td>
    
    <td>
      <code>
        slate
      </code>
    </td>
    
    <td>
      Neutral color for backgrounds, text, etc.
    </td>
  </tr>
</tbody>
</table>

This approach makes your codebase more maintainable and your UI more consistent—especially when working in teams. With these semantic tokens, light and dark mode transitions become effortless, as the system automatically handles the appropriate color values for each theme without requiring duplicate class definitions.

## 💚 Complete Vue Compatibility

We're really happy to expand the scope of Nuxt UI beyond the Nuxt framework. With v3, both Nuxt UI and Nuxt UI Pro now work seamlessly in any Vue project, this means you can:

• Use the same components across all your Vue projects

• Benefit from Nuxt UI's theming system in any Vue application

• Enjoy auto-imports and TypeScript support outside of Nuxt

• Leverage both basic components and advanced Pro components in any Vue project

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})
```

## 📦 Components for Every Need

With 54 core components, 50 Pro components, and 42 Prose components, Nuxt UI v3 provides solutions for virtually any UI challenge:

• **Data Display**: Tables, charts, and visualizations that adapt to your data

• **Navigation**: Menus, tabs, and breadcrumbs that guide users intuitively

• **Feedback**: Toasts, alerts, and modals that communicate clearly

• **Forms**: Inputs, selectors, and validation that simplify data collection

• **Layout**: Grids, containers, and responsive systems that organize content beautifully

Each component is designed to be both beautiful out of the box and deeply customizable when needed.

## 🔷 Improved TypeScript Integration

We've completely revamped our TypeScript integration, with features that make you more productive:

- Complete type safety with helpful autocompletion
- Generic-based components for flexible APIs
- Type-safe theming through a clear, consistent API

```ts
export default defineAppConfig({
  ui: {
    button: {
      // Your IDE will show all available options
      slots: {
        base: 'font-bold rounded-lg'
      },
      defaultVariants: {
        size: 'md',
        color: 'error'
      }
    }
  }
})
```

## ⬆️ Upgrading to v3

We've prepared a comprehensive [migration](https://ui.nuxt.com/getting-started/migration) guide to help you upgrade from v2 to v3. While there are breaking changes due to our complete overhaul, we've worked hard to make the transition as smooth as possible.

## 🎯 Getting Started

Whether you're starting a new project or upgrading an existing one, getting started with Nuxt UI v3 is easy:

```bash
# Create a new Nuxt project with Nuxt UI
npx nuxi@latest init my-app -t ui
```

<code-group sync="pm">

```bash [pnpm]
pnpm add @nuxt/ui@latest
```

```bash [yarn]
yarn add @nuxt/ui@latest
```

```bash [npm]
npm install @nuxt/ui@latest
```

```bash [bun]
bun add @nuxt/ui@latest
```

</code-group>

<warning>

If you're using **pnpm**, ensure that you either set [`shamefully-hoist=true`](https://pnpm.io/npmrc#shamefully-hoist) in your `.npmrc` file or install `tailwindcss` in your project's root directory.

</warning>

Visit our [documentation](https://ui.nuxt.com/getting-started) to explore all the components and features available in Nuxt UI v3.

## 🙏 Thank You

This release represents thousands of hours of work from our team and the community. We'd like to thank everyone who contributed to making Nuxt UI v3 a reality.

We're excited to see what you'll build with Nuxt UI v3!

---

# Source: https://nuxt.com/raw/blog/nuxt-ui-v4.md

# Nuxt UI v4

> Nuxt UI v4 unifies Nuxt UI and Nuxt UI Pro into one powerful, completely free library. With over 110 components, 12 templates, and a comprehensive Figma kit, all of this is available for free.

Today, we’re releasing [**Nuxt UI v4**](https://ui.nuxt.com), a major milestone that sets a new standard for our component library. With this release, we are unifying Nuxt UI and Nuxt UI Pro into a single, powerful, and completely free open-source library.

This marks an exciting new chapter for the Vue and Nuxt ecosystems, made possible by [NuxtLabs joining Vercel](https://nuxtlabs.com). Our shared commitment to the open-source community has allowed us to make every component, from a [simple button](https://ui.nuxt.com/docs/components/button) to the most advanced [dashboard sidebar](https://ui.nuxt.com/docs/components/dashboard-sidebar), accessible to everyone.

What was previously a premium offering is now available to all. Over 100 components, advanced sections, and [production-ready templates](https://ui.nuxt.com/templates) are now yours to build with, unified in one place.

## Build anything, faster than ever

Nuxt UI v4 makes it easy to build modern, polished apps quickly. You can create complex interfaces like landing pages, pricing pages, docs, blogs, portfolios, etc. without starting from scratch.

This is possible because Nuxt UI v4 unifies everything you need into a single `@nuxt/ui` package:

- **110+ components:** An extensive library to build anything from simple websites to complex applications.
- **12 free templates:** Start your next project in minutes with a production-ready template for a [Landing Page](https://landing-template.nuxt.dev), [SaaS](https://saas-template.nuxt.dev), [Dashboard](https://dashboard-template.nuxt.dev), [Docs site](https://docs-template.nuxt.dev), [Portfolio](https://portfolio-template.nuxt.dev), [Chat app](https://chat-template.nuxt.dev), or [Changelog](https://changelog-template.nuxt.dev).
- **Rich Content & Typography:** Beautifully render Markdown and build content-rich sites with our advanced prose components, fully integrated with Nuxt Content.
- **Vue and Nuxt Compatibility:** Works in any Vue or Nuxt project, as well as [Adonis](https://github.com/nuxt-ui-templates/starter-adonis) and [Laravel](https://github.com/nuxt-ui-templates/starter-laravel).

The entire Pro suite is now yours. Build with powerful components previously exclusive to our paid users, now free for everyone.

<tabs className="gap-0">
<div label="index.vue">

```vue
<template>
    <UApp>
      <UHeader>
        <UNavigationMenu :items="navigation" />
        <template #right>
          <UColorModeButton />
          <UButton icon="i-simple-icons-github" />
        </template>
      </UHeader>

      <UPageHero
        title="Nuxt UI - Starter"
        description="Nuxt UI is a free and open-source UI library for Nuxt applications. Create beautiful & responsive applications in minutes."
        :links="heroLinks"
      />

      <UPageSection
        title="The freedom to build anything"
        description="Nuxt UI ships with a comprehensive set of components that cover a wide range of use-cases. Carefully crafted to reduce boilerplate code without sacrificing flexibility."
        :features="features"
      />

      <UPageSection title="Pricing">
        <UPricingPlans :plans="plans" />
      </UPageSection>

      <UPageSection>
        <UPageCTA
          title="Start with Nuxt UI today!"
          description="Nuxt UI is a free and open-source UI library for Nuxt applications."
          variant="subtle"
          :links="ctaLinks"
        />
      </UPageSection>

      <UFooter :items="footerItems" />
    </UApp>
  </template>
```

</div>

<code-preview :ui="{"preview":"p-0"}" className="[&>div]:*:my-0,w-full" label="Preview">
<index-example>



</index-example>
</code-preview>
</tabs>

## From design to code, seamlessly

A successful project starts with a solid design system. In v4, we are releasing the **complete Figma Kit** for free, mirroring the entire component library.

With over **2,000 component variants and design tokens**, you now have a single Figma entry point that contains every component along with detailed explanations about structure and usage. Designers and developers work from the same comprehensive source, making collaboration seamless and ensuring a perfect match between design and implementation.

<u-button className="mb-4" icon="i-simple-icons-figma" label="Get the Figma Kit →" target="_blank" to="https://go.nuxt.com/figma-ui">



</u-button>

<carousel :items="["/assets/blog/figma-kit/1.png","/assets/blog/figma-kit/2.png","/assets/blog/figma-kit/3.png"]">



</carousel>

## An upgraded developer experience

Beyond new components, v4 brings significant improvements to your workflow.

### Effortless migration

Unlike the major overhaul from v2 to v3, the migration to v4 is simple. This release focuses on unification, not breaking changes. Most components work identically, and your existing code will remain largely intact.

Check out our [migration guide](https://ui.nuxt.com/getting-started/migration/v4) for a complete walkthrough.

### A refined documentation

We've completely overhauled our documentation to make it clearer and more intuitive. We’ve restructured the layout and split complex topics into dedicated pages, ensuring you can find the information you need, faster.

Our documentation is also now fully AI-ready. It's powered by our new **Model Context Protocol (MCP) server**, which allows AI tools like Cursor to access component documentation and metadata directly. In addition, we provide **LLMs.txt files**, a structured format that enables any AI assistant to understand our components, theming, and best practices. Your AI tools now have first-class access to our entire library, right inside your editor.

### Ready for the next wave of AI

Our AI chat components now support **Vercel's AI SDK v5**. The new `Chat` class and message format (with `parts`) ensure compatibility with the latest AI SDK improvements, keeping you at the forefront of AI development.

## A thank you to our pro users

We want to extend a special thanks to everyone who supported Nuxt UI Pro. Your early adoption and feedback were instrumental in shaping Nuxt UI. You helped us fund, maintain, and improve the project, allowing us to reach this milestone where we can now offer these powerful tools to the entire community.

Your support made this moment possible.

## Start building today

Get started with Nuxt UI v4 by creating a new project with any of our free templates:

<code-group>

```bash [Starter]
npm create nuxt@latest -- -t ui
```

```bash [Landing]
npm create nuxt@latest -- -t github:nuxt-ui-templates/landing
```

```bash [Docs]
npm create nuxt@latest -- -t github:nuxt-ui-templates/docs
```

```bash [SaaS]
npm create nuxt@latest -- -t github:nuxt-ui-templates/saas
```

```bash [Dashboard]
npm create nuxt@latest -- -t github:nuxt-ui-templates/dashboard
```

```bash [Chat]
npm create nuxt@latest -- -t github:nuxt-ui-templates/chat
```

```bash [Portfolio]
npm create nuxt@latest -- -t github:nuxt-ui-templates/portfolio
```

```bash [Changelog]
npm create nuxt@latest -- -t github:nuxt-ui-templates/changelog
```

</code-group>

Or add it to your existing project:

```bash
npm install @nuxt/ui@latest
```

## The future is open

With a unified codebase and the backing of Vercel, we're more excited than ever to push the boundaries of component development. This release wouldn't have been possible without the support of our amazing community, and every contributor who has helped shape Nuxt UI.

We can't wait to see what you build. The future of UI development is free, open, and more powerful than ever.

---

*Ready to get started? Check out the documentation and join our Discord community to connect with other developers building amazing things with Nuxt UI.*

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/nuxt-welcome.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/nuxt-welcome.md

# <NuxtWelcome>

> The <NuxtWelcome> component greets users in new projects made from the starter template.

It includes links to the Nuxt documentation, source code, and social media accounts.

```vue [app/app.vue]
<template>
  <NuxtWelcome />
</template>
```

<read-more target="_blank" to="https://templates.ui.nuxtjs.org/templates/welcome">

Preview the `<NuxtWelcome />` component.

</read-more>

<tip>

This component is part of [`@nuxt/ui-templates`](https://github.com/nuxt/nuxt/tree/main/packages/ui-templates) package.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/nuxt.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/nuxt.md

# .nuxt

> Nuxt uses the .nuxt/ directory in development to generate your Vue application.

<important>

This directory should be added to your [`.gitignore`](/docs/4.x/directory-structure/gitignore) file to avoid pushing the dev build output to your repository.

</important>

This directory is interesting if you want to learn more about the files Nuxt generates based on your directory structure.

Nuxt also provides a Virtual File System (VFS) for modules to add templates to this directory without writing them to disk.

You can explore the generated files by opening the [Nuxt DevTools](https://devtools.nuxt.com) in development mode and navigating to the **Virtual Files** tab.

<warning>

You should not touch any files inside since the whole directory will be re-created when running [`nuxt dev`](/docs/4.x/api/commands/dev).

</warning>

---

# Source: https://nuxt.com/raw/blog/nuxt2-eol.md

# Nuxt 2 End-of-Life (EOL)

> Nuxt 2 will reach End of Life (EOL) on June 30th, 2024. We've partnered with HeroDevs on offering Never-Ending Support (NES).

Released in 2018, Nuxt 2.0 marked a major milestone, establishing it as a mainstream framework. Over the past six years, many developers adopted Nuxt 2, leading to the creation of numerous impressive projects across the web.

However, looking forward, maintaining Nuxt 2 is no longer sustainable. With the recent end-of-life of Vue 2 and the maturity of Nuxt 3 and its ecosystem, it's time for our team to concentrate our efforts on the latest major version and upcoming versions.

<tip target="_blank" to="https://www.herodevs.com/support/nuxt-nes?utm_source=nuxt&utm_medium=nuxt-eol-article">

Jump over HeroDevs' Nuxt Never-Ending Support (NES)

</tip>

## What happens on June 30th, 2024?

After this date, Nuxt 2 will continue to be available on the NPM package manager, but will no longer receive updates, such as security and browser compatibility fixes. In other words, your applications will continue to work, but you may get deprecation warnings from your package manager reminding you that Nuxt 2 is no longer a supported version.

<note>

Vue 2 reached its end-of-life date on December 31st, 2023.

</note>

## What’s Next?

Nuxt 3 has been the default version of Nuxt since November 16th, 2022.

On top of using Vue 3 and the composition API, it is shipped with features and innovations:

- Universal & Hybrid Rendering: Benefits of both SPA and SSR, with fine-grained control over route rendering
- Support for serverless environments (AWS Lambda, Deno, Cloudflare Workers) with minimal cold-start.
- First-Class TypeScript Support: Full typing across all components and configurations.
- Vite integration for a faster developer experience
- Server & API routes with end-to-end typing powered by Nitro
- Auto import of composables & utils
- Layers feature for domain driven development

When and if you can, consider migrating to Nuxt 3 to take advantage of these powerful features.

<read-more to="/docs/getting-started/upgrade#nuxt-2-vs-nuxt-3">

See a full comparison table between Nuxt 2 and Nuxt 3, as well as detailed upgrade guides to Nuxt 3 and Nuxt Bridge (as a part of upgrading to Nuxt 3).

</read-more>

<read-more to="/enterprise/support" icon="i-lucide-life-buoy">

If you need support, including upgrading to Nuxt 3, NuxtLabs provides professional support and consultancy in a wide range of areas.

</read-more>

## Still on Nuxt 2? Here Are Your Options.

Recognizing the various situations that arise during transitions, we are fully aware that users may need other options until they can migrate, or maybe migration simply isn't a feasible path. Here are some other options to consider:

### Update to the Nuxt 2 latest release

We expect to release 2.18.0 at the end of June 2024, which will include a few final fixes.

<note>

We strongly encourage you to update to 2.18.0 once it's out. This will be the starting point for extended support mentioned below.

</note>

### Purchase Extended Support for Nuxt 2

If you have to stay on Nuxt 2 post-EOL, we have partnered with HeroDevs to offer Nuxt 2 Never-Ending Support (NES). Nuxt 2 NES provides ongoing security and compatibility patches for Nuxt 2 and all official Nuxt Modules (modules released by the Nuxt team, labeled `@nuxt/...` in the marketplace) even after EOL so that applications with strict compliance requirements remain secure and compliant. It also guarantees that Nuxt 2 applications will continue to operate effectively in modern browsers and maintain compatibility with essential libraries like Vue 2. Moreover, Nuxt 2 NES has continuous security monitoring and an enterprise level SLA with respect to support and fixes.

Nuxt 2 NES is the continuation of the flavor of security support you’ve enjoyed during the Nuxt 2 LTS period — but indefinitely.

<tip target="_blank" to="https://www.herodevs.com/support/nuxt-nes?utm_source=nuxt&utm_medium=nuxt-eol-article">

Read more about HeroDevs' Nuxt Never-Ending Support (NES)

</tip>

### Notify Your Users of Your Nuxt 2 Post-EOL Plan

If migrating to Nuxt 3 or using Nuxt 2 NES isn't feasible right now, but you're still on Nuxt 2, it's essential to plan how you'll communicate your security strategy to your customers.

This doesn't affect all Nuxt users, but many teams face restrictions against deploying unsupported software due to SLAs, contracts, or other obligations to clients and partners. These requirements might come from customers, regulatory bodies, or internal company policies. Increasingly, regulatory bodies are setting higher standards for software accountability.

For those with such responsibilities, informing your customers, managers, CISO, or other stakeholders about your plans to handle support and manage potential CVEs is crucial. While Nuxt 2 has only had few vulnerabilities, CVEs can emerge even in well-maintained EOL projects through direct vulnerabilities or compromised dependencies. Staying updated with CVE notifications from organizations like [OpenCVE](https://www.opencve.io), and [Snyk](https://snyk.io) can help you identify issues as they arise. Additionally, browsers occasionally update in ways that can affect legacy libraries—though rare, it’s a possibility to be aware of.

## Looking Forward

It is with a heavy heart that I am saying goodbye to Nuxt 2. After many years of working on it and seeing so many websites made with it, this famous loading bar at the top of each Nuxt 2 website will be something I’ll miss a lot! It is with excitement and energy that I will keep working with the core team on the future of Nuxt to keep innovating like we've been doing over these past 8 years.

---

# Source: https://nuxt.com/raw/blog/nuxt3-beta.md

# Introducing Nuxt 3 Beta

> 468 days after the first commit, the Nuxt 3 beta has finally arrived. Discover what's inside and what to expect from it. Yes, it includes Vue 3 and Vite ⚡️

We are excited to open source Nuxt 3 after more than a year of intense development. The repository is available on GitHub on [nuxt/nuxt](https://github.com/nuxt/nuxt) under the [MIT](https://github.com/nuxt/nuxt/blob/main/LICENSE) license.

<tip>

The documentation is available on [https://nuxt.com](https://nuxt.com).

</tip>

## A new foundation

On top of supporting [Vue 3](https://vuejs.org) or [Vite](https://vitejs.dev), Nuxt 3 contains a new [server engine](https://nuxt.com/docs/guide/concepts/server-engine), unlocking new full-stack capabilities to Nuxt server and beyond. It's the first JavaScript application server that is portable across a variety of modern cloud hosting providers.

In production, it builds your Vue application and server into one universal `.output` directory. This output is light: minified and without any other Node.js dependencies (except polyfills). You can deploy this output on any system supporting JavaScript, whether Node.js, Serverless, Workers, Edge-side rendering or purely static.

**Bonus:** this server engine can be used on existing Nuxt 2 projects with [Nuxt Bridge](https://nuxt.com/docs/getting-started/bridge) 🚀

Head over the [Nuxt 3 homepage](https://nuxt.com) to learn more about Nuxt Nitro and Nuxt Bridge.

## Important notes

Nuxt 3 is currently in beta, so expect things to break (and be fixed quickly). We have [plenty of work left](https://github.com/nuxt/nuxt/issues) but we want to open it publicly to gather feedback and contributions from the community 💚

**Do not use it for production until we reach the first release candidate.**

During the beta, almost every commit will [trigger a new npm release](https://github.com/nuxt/nuxt/blob/main/.github/workflows/ci.yml#L111-L119); you may want to look at the [merged pull requests](https://github.com/nuxt/nuxt/pulls?q=is%3Apr+is%3Amerged) until we begin generating automated changelogs in the documentation.

We are working every day to improve the documentation, explaining as much as possible all the concepts, features and usage of Nuxt 3.

Check out the community section of the Nuxt 3 website for [getting help](https://nuxt.com/docs/community/getting-help), [reporting bugs](https://nuxt.com/docs/community/reporting-bugs) or [contributing to the framework](https://nuxt.com/docs/community/contribution).

## Timeline

Here some major milestones we've achieved on the way to Nuxt 3:

- **Jul 2, 2020**: Nuxt 3 first commit with full TypeScript rewrite
- **Aug 7, 2020**: Webpack 5 support
- **Sep 15, 2020**: [`pages/`](https://nuxt.com/docs/guide/directory-structure/pages) support
- **Oct 29, 2020**: [Vue 3](https://vuejs.org) support with bundle-renderer
- **Nov 2, 2020**: [Nuxt Nitro](https://nuxt.com/guide/concepts/server-engine) initial work
- **Jan 22, 2021**: Initial [Vite](https://vitejs.dev) support
- **Feb 4, 2021**: Nuxt can deploy on [major serverless platforms](https://nuxt.com/docs/getting-started/deployment)
- **Mar 6, 2021**: [UnJS](https://github.com/unjs) organisation created on GitHub
- **Mar 28, 2021**: Init Nuxt Kit and Nuxt CLI ([nuxi](https://nuxt.com/docs/api/commands/add))
- **May 20, 2021**: [`app.vue`](https://nuxt.com/docs/guide/directory-structure/app) support (`pages/` becomes optional)
- **Jun 30, 2021**: [`layouts/`](https://nuxt.com/docs/guide/directory-structure/layouts) support
- **Jul 15, 2021**: Native ESM support
- **Aug 10, 2021**: Auto import of composables and components
- **Sep 5, 2021**: Init [Nuxt Bridge](https://nuxt.com/docs/bridge/overview) for improving Nuxt 2 experience
- **Sep 7, 2021**: Support Vite build for production
- **Oct 11, 2021**: Add [`useState`](https://nuxt.com/docs/getting-started/state-management) and [`useFetch`](https://nuxt.com/docs/api/composables/use-fetch) composables

So far, we've merged [385 pull requests](https://github.com/nuxt/nuxt/pulls?q=is%3Apr+is%3Amerged), closed [229 issues](https://github.com/nuxt/nuxt/issues?q=is%3Aissue+is%3Aclosed) and made [925+ commits](https://github.com/nuxt/nuxt/commits/main).

We are excited to hear your thoughts and we thank you for your patience.

Now you can go over the [Nuxt 3 documentation](https://nuxt.com) 😊

Don't forget to follow us on [Twitter](https://x.com/nuxt_js) to get the latest news about Nuxt!

---

# Source: https://nuxt.com/raw/docs/3.x/bridge/nuxt3-compatible-api.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/nuxt3-compatible-api.md

# New Composition API

> Nuxt Bridge implements composables compatible with Nuxt 3.

By migrating from `@nuxtjs/composition-api` to the Nuxt 3 compatible API, there will be less rewriting when migrating to Nuxt 3.

## `ssrRef` and `shallowSsrRef`

These two functions have been replaced with a new composable that works very similarly under the hood: `useState`.

The key differences are that you must provide a *key* for this state (which Nuxt generated automatically for `ssrRef` and `shallowSsrRef`), and that it can only be called within a Nuxt 3 plugin (which is defined by `defineNuxtPlugin`) or a component instance. (In other words, you cannot use [`useState`](/docs/4.x/api/composables/use-state) with a global/ambient context, because of the danger of shared state across requests.)

```diff
- import { ssrRef } from '@nuxtjs/composition-api'

- const ref1 = ssrRef('initialData')
- const ref2 = ssrRef(() => 'factory function')
+ const ref1 = useState('ref1-key', () => 'initialData')
+ const ref2 = useState('ref2-key', () => 'factory function')
  // accessing the state
  console.log(ref1.value)
```

Because the state is keyed, you can access the same state from multiple locations, as long as you are using the same key.

You can read more about how to use this composable in [the Nuxt 3 docs](/docs/4.x/api/composables/use-state).

## `ssrPromise`

This function has been removed, and you will need to find an alternative implementation if you were using it. If you have a use case for `ssrPromise`, please let us know via a discussion.

## `onGlobalSetup`

This function has been removed, but its use cases can be met by using [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) or [`useState`](/docs/4.x/api/composables/use-state) within `defineNuxtPlugin`. You can also run any custom code within the `setup()` function of a layout.

```diff
- import { onGlobalSetup } from '@nuxtjs/composition-api'

- export default () => {
-   onGlobalSetup(() => {
+ export default defineNuxtPlugin((nuxtApp) => {
+   nuxtApp.hook('vue:setup', () => {
      // ...
    })
- }
+ })
```

## `useStore`

In order to access Vuex store instance, you can use `useNuxtApp().$store`.

```diff
- import { useStore } from '@nuxtjs/composition-api`
+ const { $store } = useNuxtApp()
```

## `useContext` and `withContext`

You can access injected helpers using `useNuxtApp`.

```diff
- import { useContext } from '@nuxtjs/composition-api`
+ const { $axios } = useNuxtApp()
```

<note>

`useNuxtApp()` also provides a key called `nuxt2Context` which contains all the same properties you would normally access from Nuxt 2 context, but it's advised *not* to use this directly, as it won't exist in Nuxt 3. Instead, see if there is another way to access what you need. (If not, please raise a feature request or discussion.)

</note>

## `wrapProperty`

This helper function is not provided any more but you can replace it with the following code:

```ts
import { computed, getCurrentInstance } from 'vue'

const wrapProperty = (property: string, makeComputed = true) => () => {
  const vm = getCurrentInstance().proxy
  return makeComputed ? computed(() => vm[property]) : vm[property]
}
```

## `useAsync` and `useFetch`

These two composables can be replaced with `useLazyAsyncData` and `useLazyFetch`, which are documented [in the Nuxt 3 docs](/docs/4.x/getting-started/data-fetching). Just like the previous `@nuxtjs/composition-api` composables, these composables do not block route navigation on the client-side (hence the 'lazy' part of the name).

<important>

Note that the API is entirely different, despite similar sounding names. Importantly, you should not attempt to change the value of other variables outside the composable (as you may have been doing with the previous `useFetch`).

</important>

<warning>

The `useLazyFetch` must have been configured for [Nitro](/docs/4.x/bridge/nitro).

</warning>

Migrating to the new composables from `useAsync`:

```diff
<script setup>
- import { useAsync } from '@nuxtjs/composition-api'
- const posts = useAsync(() => $fetch('/api/posts'))
+ const { data: posts } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // or, more simply!
+ const { data: posts } = useLazyFetch('/api/posts')
</script>
```

Migrating to the new composables from `useFetch`:

```diff
<script setup>
- import { useFetch } from '@nuxtjs/composition-api'
- const posts = ref([])
- const { fetch } = useFetch(() => { posts.value = await $fetch('/api/posts') })
+ const { data: posts, refresh } = useLazyAsyncData('posts', () => $fetch('/api/posts'))
+ // or, more simply!
+ const { data: posts, refresh } = useLazyFetch('/api/posts')
  function updatePosts() {
-   return fetch()
+   return refresh()
  }
</script>
```

### `useMeta`

In order to interact with `vue-meta`, you may use `useNuxt2Meta`, which will work in Nuxt Bridge (but not Nuxt 3) and will allow you to manipulate your meta tags in a `vue-meta`-compatible way.

```diff
<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useNuxt2Meta({
    title: 'My Nuxt App',
  })
</script>
```

You can also pass in computed values or refs, and the meta values will be updated reactively:

```vue
<script setup>
const title = ref('my title')
useNuxt2Meta({
  title,
})
title.value = 'new title'
</script>
```

<note>

Be careful not to use both `useNuxt2Meta()` and the Options API `head()` within the same component, as behavior may be unpredictable.

</note>

Nuxt Bridge also provides a Nuxt 3-compatible meta implementation that can be accessed with the [`useHead`](/docs/4.x/api/composables/use-head) composable.

```diff
<script setup>
- import { useMeta } from '@nuxtjs/composition-api'
  useHead({
    title: 'My Nuxt App',
  })
</script>
```

You will also need to enable it explicitly in your `nuxt.config`:

```js
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    meta: true,
  },
})
```

This [`useHead`](/docs/4.x/api/composables/use-head) composable uses `@unhead/vue` under the hood (rather than `vue-meta`) to manipulate your `<head>`. Accordingly, it is recommended not to use both the native Nuxt 2 `head()` properties as well as [`useHead`](/docs/4.x/api/composables/use-head) , as they may conflict.

For more information on how to use this composable, see [the Nuxt 3 docs](/docs/4.x/getting-started/seo-meta).

### Explicit Imports

Nuxt exposes every auto-import with the `#imports` alias that can be used to make the import explicit if needed:

```vue
<script setup lang="ts">
import { computed, ref } from '#imports'

const count = ref(1)
const double = computed(() => count.value * 2)
</script>
```

### Disabling Auto-imports

If you want to disable auto-importing composables and utilities, you can set `imports.autoImport` to `false` in the `nuxt.config` file.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})
```

This will disable auto-imports completely but it's still possible to use [explicit imports](/docs/4.x/bridge/nuxt3-compatible-api#explicit-imports) from `#imports`.

---

# Source: https://nuxt.com/raw/blog/nuxt3-rc.md

# Announcing Nuxt 3 Release Candidate

> Nuxt 3 beta was announced on October 12, 2021 after 16 months of work, introducing a new foundation based on Vue 3, Vite and Nitro. Six months later, we are happy to announce the first release candidate of Nuxt 3, code named “Mount Hope“ 🚀

We are excited to open source Nuxt 3 after more than a year of intense development. The repository is available on GitHub on [nuxt/nuxt](https://go.nuxt.com/github) under the [MIT](https://go.nuxt.com/license) license.

<tip>

The documentation is available on [https://nuxt.com](https://nuxt.com).

</tip>

## A new foundation

On top of supporting [Vue 3](https://vuejs.org) or [Vite](https://vitejs.dev), Nuxt 3 contains a new [server engine](https://nuxt.com/docs/guide/concepts/server-engine), unlocking new full-stack capabilities to Nuxt server and beyond. It's the first JavaScript application server that is portable across a variety of modern cloud hosting providers.

In production, it builds your Vue application and server into one universal `.output` directory. This output is light: minified and without any other Node.js dependencies (except polyfills). You can deploy this output on any system supporting JavaScript, whether Node.js, Serverless, Workers, Edge-side rendering or purely static.

**Bonus:** this server engine can be used on existing Nuxt 2 projects with [Nuxt Bridge](https://nuxt.com/docs/getting-started/bridge) 🚀

Head over the [Nuxt 3 homepage](https://nuxt.com) to learn more about Nuxt Nitro and Nuxt Bridge.

## Important notes

Nuxt 3 is currently in beta, so expect things to break (and be fixed quickly). We have [plenty of work left](https://github.com/nuxt/nuxt/issues) but we want to open it publicly to gather feedback and contributions from the community 💚

**Do not use it for production until we reach the first release candidate.**

During the beta, almost every commit will [trigger a new npm release](https://github.com/nuxt/nuxt/blob/main/.github/workflows/ci.yml#L111-L119); you may want to look at the [merged pull requests](https://github.com/nuxt/nuxt/pulls?q=is%3Apr+is%3Amerged) until we begin generating automated changelogs in the documentation.

We are working every day to improve the documentation, explaining as much as possible all the concepts, features and usage of Nuxt 3.

Check out the community section of the Nuxt 3 website for [getting help](https://nuxt.com/docs/community/getting-help), [reporting bugs](https://nuxt.com/docs/community/reporting-bugs) or [contributing to the framework](https://nuxt.com/docs/community/contribution).

## Timeline

Here some major milestones we've achieved on the way to Nuxt 3:

- **Jul 2, 2020**: Nuxt 3 first commit with full TypeScript rewrite
- **Aug 7, 2020**: Webpack 5 support
- **Sep 15, 2020**: [`pages/`](https://nuxt.com/docs/guide/directory-structure/pages) support
- **Oct 29, 2020**: [Vue 3](https://vuejs.org) support with bundle-renderer
- **Nov 2, 2020**: [Nuxt Nitro](https://nuxt.com/guide/concepts/server-engine) initial work
- **Jan 22, 2021**: Initial [Vite](https://vitejs.dev) support
- **Feb 4, 2021**: Nuxt can deploy on [major serverless platforms](https://nuxt.com/docs/getting-started/deployment)
- **Mar 6, 2021**: [UnJS](https://github.com/unjs) organisation created on GitHub
- **Mar 28, 2021**: Init Nuxt Kit and Nuxt CLI ([nuxi](https://nuxt.com/docs/api/commands/add))
- **May 20, 2021**: [`app.vue`](https://nuxt.com/docs/guide/directory-structure/app) support (`pages/` becomes optional)
- **Jun 30, 2021**: [`layouts/`](https://nuxt.com/docs/guide/directory-structure/layouts) support
- **Jul 15, 2021**: Native ESM support
- **Aug 10, 2021**: Auto import of composables and components
- **Sep 5, 2021**: Init [Nuxt Bridge](https://nuxt.com/docs/bridge/overview) for improving Nuxt 2 experience
- **Sep 7, 2021**: Support Vite build for production
- **Oct 11, 2021**: Add [`useState`](https://nuxt.com/docs/getting-started/state-management) and [`useFetch`](https://nuxt.com/docs/api/composables/use-fetch) composables

So far, we've merged [385 pull requests](https://github.com/nuxt/nuxt/pulls?q=is%3Apr+is%3Amerged), closed [229 issues](https://github.com/nuxt/nuxt/issues?q=is%3Aissue+is%3Aclosed) and made [925+ commits](https://github.com/nuxt/nuxt/commits/main).

We are excited to hear your thoughts and we thank you for your patience.

Now you can go over the [Nuxt 3 documentation](https://nuxt.com) 😊

Don't forget to follow us on [Twitter](https://x.com/nuxt_js) to get the latest news about Nuxt!

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/nuxtignore.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/nuxtignore.md

# .nuxtignore

> The .nuxtignore file lets Nuxt ignore files in your project’s root directory during the build phase.

The `.nuxtignore` file tells Nuxt to ignore files in your project’s root directory ([`rootDir`](/docs/4.x/api/nuxt-config#rootdir)) during the build phase.

It is subject to the same specification as [`.gitignore`](/docs/4.x/directory-structure/gitignore) and `.eslintignore` files, in which each line is a glob pattern indicating which files should be ignored.

<tip>

You can also configure [`ignoreOptions`](/docs/4.x/api/nuxt-config#ignoreoptions), [`ignorePrefix`](/docs/4.x/api/nuxt-config#ignoreprefix) and [`ignore`](/docs/4.x/api/nuxt-config#ignore) in your `nuxt.config` file.

</tip>

## Usage

```bash [.nuxtignore]
# ignore layout foo.vue
app/layouts/foo.vue
# ignore layout files whose name ends with -ignore.vue
app/layouts/*-ignore.vue

# ignore page bar.vue
app/pages/bar.vue
# ignore page inside ignore folder
app/pages/ignore/*.vue

# ignore route middleware files under foo folder except foo/bar.js
app/middleware/foo/*.js
!app/middleware/foo/bar.js
```

<read-more icon="i-simple-icons-git" target="_blank" title="the git documentation" to="https://git-scm.com/docs/gitignore">

More details about the spec are in the **gitignore documentation**.

</read-more>

---

# Source: https://nuxt.com/raw/blog/nuxtjs-from-terminal-to-browser.md

# Nuxt 2: From Terminal to Browser

> How we changed the developer experience to stop switching between the terminal and browser.

> Nuxt is a Vue.js framework to create different kind of web applications with the **same directory structure & conventions**: Universal, Single Page, PWA or Static Generated.

*ℹ️ These features are all available with v2.8.0 release.*

## Problems

1. Developing JavaScript applications with Webpack or any bundler requires to switch between your browser and terminal for debugging purpose.
2. Using `console.log` to debug when the app is server rendered requires to remember that logs will be displayed on the terminal when refreshing the page.

## Solutions

1. Forwarding Webpack build state right in the browser and display them in a fancy manner.

![forward-webpack-build-state](/assets/blog/forward-webpack-build-state.gif)

1. Same for Hot Module Replacement (really useful when the project gets bigger and takes more time to re-build).

![nuxt-build-indicator-hmr](/assets/blog/nuxt-build-indicator-hmr.gif)

1. Forwarding SSR logs to the browser in development mode

![nuxt-ssr-logs-forwarding](/assets/blog/nuxt-ssr-logs-forwarding.gif)

## Nuxt Vision

The purpose to these changes is to use the terminal for commands only.

Now you can focus right on your code and its visual result 🙂

> Be lazy, be smart, be Nuxt.

Links:

- Nuxt 2 docs: [https://v2.nuxt.com](https://v2.nuxt.com)
- GitHub: [https://github.com/nuxt/nuxt.js](https://github.com/nuxt/nuxt.js)
- Loading Screen source code: [https://github.com/nuxt/loading-screen](https://github.com/nuxt/loading-screen)
- Twitter: [https://x.com/nuxt_js](https://x.com/nuxt_js)

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/nuxtrc.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/nuxtrc.md

# .nuxtrc

> The .nuxtrc file allows you to define nuxt configurations in a flat syntax.

The `.nuxtrc` file can be used to configure Nuxt with a flat syntax. It is based on [`unjs/rc9`](https://github.com/unjs/rc9).

<tip>

For more advanced configurations, use [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config).

</tip>

## Usage

```bash [.nuxtrc]
# Disable SSR
ssr=false

# Configuration for `@nuxt/devtools`
devtools.enabled=true

# Add Nuxt modules
modules[]=@nuxt/image
modules[]=nuxt-security

# Module setups (automatically added by Nuxt)
setups.@nuxt/test-utils="3.23.0"
```

If present, the properties in the `nuxt.config` file will overwrite the properties in `.nuxtrc` file.

<note>

Nuxt automatically adds a `setups` section to track module installation and upgrade state. This is used internally for [module lifecycle hooks](/docs/4.x/api/kit/modules#using-lifecycle-hooks-for-module-installation-and-upgrade) and should not be modified manually.

</note>

<read-more to="/docs/4.x/api/configuration/nuxt-config">

Discover all the available options in the **Nuxt configuration** documentation.

</read-more>

## Global `.nuxtrc` File

You can also create a global `.nuxtrc` file in your home directory to apply configurations globally.

- On macOS/Linux, this file is located at:```md
~/.nuxtrc
```
- On Windows, it is located at:```md
C:\Users\{username}\.nuxtrc
```

This global `.nuxtrc` file allows you to define default settings that apply to all Nuxt projects on your system. However, project-level `.nuxtrc` files will override these global settings, and `nuxt.config` will take precedence over both.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/on-before-route-leave.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/on-before-route-leave.md

# onBeforeRouteLeave

> The onBeforeRouteLeave composable allows registering a route guard within a component.

<read-more icon="i-simple-icons-vuedotjs" target="_blank" title="Vue Router Docs" to="https://router.vuejs.org/api/functions/onbeforerouteleave">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/on-before-route-update.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/on-before-route-update.md

# onBeforeRouteUpdate

> The onBeforeRouteUpdate composable allows registering a route guard within a component.

<read-more icon="i-simple-icons-vuedotjs" target="_blank" title="Vue Router Docs" to="https://router.vuejs.org/api/functions/onbeforerouteupdate">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/on-nuxt-ready.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/on-nuxt-ready.md

# onNuxtReady

> The onNuxtReady composable allows running a callback after your app has finished initializing.

<important>

`onNuxtReady` only runs on the client-side. <br />


It is ideal for running code that should not block the initial rendering of your app.

</important>

```ts [app/plugins/ready.client.ts]
export default defineNuxtPlugin(() => {
  onNuxtReady(async () => {
    const myAnalyticsLibrary = await import('my-big-analytics-library')
    // do something with myAnalyticsLibrary
  })
})
```

It is 'safe' to run even after your app has initialized. In this case, then the code will be registered to run in the next idle callback.

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/on-prehydrate.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/on-prehydrate.md

# onPrehydrate

> Use onPrehydrate to run a callback on the client immediately before Nuxt hydrates the page.

<important>

This composable is available in Nuxt v3.12+.

</important>

`onPrehydrate` is a composable lifecycle hook that allows you to run a callback on the client immediately before Nuxt hydrates the page.

<note>

This is an advanced utility and should be used with care. For example, [`nuxt-time`](https://github.com/danielroe/nuxt-time/pull/251) and [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode/blob/main/src/script.js) manipulate the DOM to avoid hydration mismatches.

</note>

## Usage

Call `onPrehydrate` in the setup function of a Vue component (e.g., in `<script setup>`) or in a plugin. It only has an effect when called on the server and will not be included in your client build.

## Type

```ts [Signature]
export function onPrehydrate (callback: (el: HTMLElement) => void): void
export function onPrehydrate (callback: string | ((el: HTMLElement) => void), key?: string): undefined | string
```

## Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        callback
      </code>
    </td>
    
    <td>
      <code>
        ((el: HTMLElement) => void) | string
      </code>
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      A function (or stringified function) to run before Nuxt hydrates. It will be stringified and inlined in the HTML. Should not have external dependencies or reference variables outside the callback. Runs before Nuxt runtime initializes, so it should not rely on Nuxt or Vue context.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      No
    </td>
    
    <td>
      (Advanced) A unique key to identify the prehydrate script, useful for advanced scenarios like multiple root nodes.
    </td>
  </tr>
</tbody>
</table>

## Return Values

- Returns `undefined` when called with only a callback function.
- Returns a string (the prehydrate id) when called with a callback and a key, which can be used to set or access the `data-prehydrate-id` attribute for advanced use cases.

## Example

```vue [app/app.vue]twoslash
<script setup lang="ts">
declare const window: Window
// ---cut---
// Run code before Nuxt hydrates
onPrehydrate(() => {
  console.log(window)
})

// Access the root element
onPrehydrate((el) => {
  console.log(el.outerHTML)
  // <div data-v-inspector="app.vue:15:3" data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
})

// Advanced: access/set `data-prehydrate-id` yourself
const prehydrateId = onPrehydrate((el) => {})
</script>

<template>
  <div>
    Hi there
  </div>
</template>
```

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/output.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/output.md

# .output

> Nuxt creates the .output/ directory when building your application for production.

<important>

This directory should be added to your [`.gitignore`](/docs/4.x/directory-structure/gitignore) file to avoid pushing the build output to your repository.

</important>

Use this directory to deploy your Nuxt application to production.

<read-more to="/docs/4.x/getting-started/deployment">



</read-more>

<warning>

You should not touch any files inside since the whole directory will be re-created when running [`nuxt build`](/docs/4.x/api/commands/build).

</warning>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/overview.md

# Source: https://nuxt.com/raw/docs/3.x/bridge/overview.md

# Source: https://nuxt.com/raw/docs/4.x/migration/overview.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/overview.md

# Overview

> Reduce the differences with Nuxt 3 and reduce the burden of migration to Nuxt 3.

<note>

If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 Installation](/docs/4.x/getting-started/introduction).

</note>

<warning>

Nuxt Bridge provides identical features to Nuxt 3 ([docs](/docs/4.x/guide/concepts/auto-imports)) but there are some limitations, notably that [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch) composables are not available. Please read the rest of this page for details.

</warning>

Bridge is a forward-compatibility layer that allows you to experience many of the new Nuxt 3 features by simply installing and enabling a Nuxt module.

Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 and you can gradually proceed with the transition to Nuxt 3.

## First Step

### Upgrade Nuxt 2

Make sure your dev server (`nuxt dev`) isn't running, remove any package lock files (`package-lock.json` and `yarn.lock`), and install the latest Nuxt 2 version:

```diff [package.json]
- "nuxt": "^2.16.3"
+ "nuxt": "^2.17.3"
```

Then, reinstall your dependencies:

<code-group sync="pm">

```bash [npm]
npm install
```

```bash [yarn]
yarn install
```

```bash [pnpm]
pnpm install
```

```bash [bun]
bun install
```

```bash [deno]
deno install
```

</code-group>

<note>

Once the installation is complete, make sure both development and production builds are working as expected before proceeding.

</note>

### Install Nuxt Bridge

Install `@nuxt/bridge` and `nuxi` as development dependencies:

<code-group sync="pm">

```bash [npm]
npm install -D @nuxt/bridge nuxi
```

```bash [yarn]
yarn add --dev @nuxt/bridge nuxi
```

```bash [pnpm]
pnpm add -D @nuxt/bridge nuxi
```

```bash [bun]
bun add -D @nuxt/bridge nuxi
```

```bash [deno]
deno add -D npm:@nuxt/bridge npm:nuxi
```

</code-group>

### Update `nuxt.config`

Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in your config file. It will soon be deprecated and unsupported.

You can use static `import`, dynamic `import()` and `export default` instead. Using TypeScript by renaming to [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) is also possible and recommended.

```ts [nuxt.config.ts]
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: false,
})
```

### Update Commands

The `nuxt` command should now be changed to the `nuxt2` command.

```diff
{
  "scripts": {
-   "dev": "nuxt",
+   "dev": "nuxt2",
-   "build": "nuxt build",
+   "build": "nuxt2 build",
-   "start": "nuxt start",
+   "start": "nuxt2 start"
  }
}
```

Try running `nuxt2` once here. You will see that the application works as before.

(If 'bridge' is set to false, your application will operate without any changes as before.)

## Upgrade Steps

With Nuxt Bridge, the migration to Nuxt 3 can proceed in steps.
The below `Upgrade Steps` does not need to be done all at once.

- [TypeScript](/docs/4.x/bridge/typescript)
- [Migrate Legacy Composition API](/docs/4.x/bridge/bridge-composition-api)
- [Plugins and Middleware](/docs/4.x/bridge/plugins-and-middleware)
- [Migrate New Composition API](/docs/4.x/bridge/nuxt3-compatible-api)
- [Meta Tags](/docs/4.x/bridge/meta)
- [Runtime Config](/docs/4.x/bridge/runtime-config)
- [Nitro](/docs/4.x/bridge/nitro)
- [Vite](/docs/4.x/bridge/vite)

## Migrate from CommonJS to ESM

Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/docs/4.x/guide/concepts/esm) for more info and upgrading.

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/package.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/package.md

# package.json

> The package.json file contains all the dependencies and scripts for your application.

The minimal `package.json` of your Nuxt application should looks like:

```json [package.json]
{
  "name": "nuxt-app",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare"
  },
  "dependencies": {
    "nuxt": "latest",
    "vue": "latest",
    "vue-router": "latest"
  }
}
```

<read-more icon="i-simple-icons-npm" target="_blank" to="https://docs.npmjs.com/cli/configuring-npm/package-json/">

Read more about the `package.json` file.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/pages-and-layouts.md

# Source: https://nuxt.com/raw/docs/4.x/migration/pages-and-layouts.md

# Pages and Layouts

> Learn how to migrate from Nuxt 2 to Nuxt 3 pages and layouts.

## `app.vue`

Nuxt 3 provides a central entry point to your app via `~/app.vue`.

<note>

If you don't have an `app.vue` file in your source directory, Nuxt will use its own default version.

</note>

This file is a great place to put any custom code that needs to be run once when your app starts up, as well as any components that are present on every page of your app. For example, if you only have one layout, you can move this to `app.vue` instead.

<read-more to="/docs/4.x/directory-structure/app/app">



</read-more>

<link-example to="/docs/4.x/examples/hello-world">



</link-example>

### Migration

Consider creating an `app.vue` file and including any logic that needs to run once at the top-level of your app. You can check out [an example here](/docs/4.x/directory-structure/app/app).

## Layouts

If you are using layouts in your app for multiple pages, there is only a slight change required.

In Nuxt 2, the `<Nuxt>` component is used within a layout to render the current page. In Nuxt 3, layouts use slots instead, so you will have to replace that component with a `<slot />`. This also allows advanced use cases with named and scoped slots. [Read more about layouts](/docs/4.x/directory-structure/app/layouts).

You will also need to change how you define the layout used by a page using the `definePageMeta` compiler macro. Layouts will be kebab-cased. So `app/layouts/customLayout.vue` becomes `custom-layout` when referenced in your page.

### Migration

1. Replace `<Nuxt />` with `<slot />````diff [app/layouts/custom.vue]
<template>
    <div id="app-layout">
      <main>
-       <Nuxt />
+       <slot />
      </main>
    </div>
  </template>
```
2. Use [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) to select the layout used by your page.
```diff [app/pages/index.vue]
+ <script setup>
+ definePageMeta({
+   layout: 'custom'
+ })
- <script>
- export default {
-   layout: 'custom'
- }
  </script>
```
3. Move `~/layouts/_error.vue` to `~/error.vue`. See [the error handling docs](/docs/4.x/getting-started/error-handling). If you want to ensure that this page uses a layout, you can use [`<NuxtLayout>`](/docs/4.x/directory-structure/app/layouts) directly within `error.vue`:
```vue [error.vue]
<template>
  <div>
    <NuxtLayout name="default">
      <!-- -->
    </NuxtLayout>
  </div>
</template>
```

## Pages

Nuxt 3 ships with an optional `vue-router` integration triggered by the existence of a [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory in your source directory. If you only have a single page, you may consider instead moving it to `app.vue` for a lighter build.

### Dynamic Routes

The format for defining dynamic routes in Nuxt 3 is slightly different from Nuxt 2, so you may need to rename some of the files within `app/pages/`.

1. Where you previously used `_id` to define a dynamic route parameter you now use `[id]`.
2. Where you previously used `_.vue` to define a catch-all route, you now use `[...slug].vue`.

### Nested Routes

In Nuxt 2, you will have defined any nested routes (with parent and child components) using `<Nuxt>` and `<NuxtChild>`. In Nuxt 3, these have been replaced with a single `<NuxtPage>` component.

### Page Keys and Keep-alive Props

If you were passing a custom page key or keep-alive props to `<Nuxt>`, you will now use `definePageMeta` to set these options.

<read-more to="/docs/4.x/directory-structure/app/pages#special-metadata">



</read-more>

### Page and Layout Transitions

If you have been defining transitions for your page or layout directly in your component options, you will now need to use `definePageMeta` to set the transition. Since Vue 3, [-enter and -leave CSS classes have been renamed](https://v3-migration.vuejs.org/breaking-changes/transition.html). The `style` prop from `<Nuxt>` no longer applies to transition when used on `<slot>`, so move the styles to your `-active` class.

<read-more to="/docs/4.x/getting-started/transitions">



</read-more>

### Migration

1. Rename any pages with dynamic parameters to match the new format.
2. Update `<Nuxt>` and `<NuxtChild>` to be `<NuxtPage>`.
3. If you're using the Composition API, you can also migrate `this.$route` and `this.$router` to use [`useRoute`](/docs/4.x/api/composables/use-route) and [`useRouter`](/docs/4.x/api/composables/use-router)  composables.

#### Example: Dynamic Routes

<code-group>

```text [Nuxt 2]
- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/_user.vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/_user/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/_.vue
- Usage: params.pathMatch
```

```text [Nuxt 3]
- URL: /users
- Page: /pages/users/index.vue

- URL: /users/some-user-name
- Page: /pages/users/[user].vue
- Usage: params.user

- URL: /users/some-user-name/edit
- Page: /pages/users/[user]/edit.vue
- Usage: params.user

- URL: /users/anything-else
- Page: /pages/users/[...slug].vue
- Usage: params.slug
```

</code-group>

#### Example: Nested Routes and `definePageMeta`

<code-group>

```vue [Nuxt 2]
<template>
  <div>
    <NuxtChild
      keep-alive
      :keep-alive-props="{ exclude: ['modal'] }"
      :nuxt-child-key="$route.slug"
    />
  </div>
</template>

<script>
export default {
  transition: 'page', // or { name: 'page' }
}
</script>
```

```vue [Nuxt 3]
<template>
  <div>
    <NuxtPage />
  </div>
</template>

<script setup lang="ts">
// This compiler macro works in both <script> and <script setup>
definePageMeta({
  // you can also pass a string or a computed property
  key: route => route.slug,
  transition: {
    name: 'page',
  },
  keepalive: {
    exclude: ['modal'],
  },
})
</script>
```

</code-group>

## `<NuxtLink>` Component

Most of the syntax and functionality are the same for the global [NuxtLink](/docs/4.x/api/components/nuxt-link) component. If you have been using the shortcut `<NLink>` format, you should update this to use `<NuxtLink>`.

`<NuxtLink>` is now a drop-in replacement for *all* links, even external ones. You can read more about it, and how to extend it to provide your own link component.

<read-more to="/docs/4.x/api/components/nuxt-link">



</read-more>

## Programmatic Navigation

When migrating from Nuxt 2 to Nuxt 3, you will have to update how you programmatically navigate your users. In Nuxt 2, you had access to the underlying Vue Router with `this.$router`. In Nuxt 3, you can use the `navigateTo()` utility method which allows you to pass a route and parameters to Vue Router.

<warning>

Make sure to always `await` on [`navigateTo`](/docs/4.x/api/utils/navigate-to) or chain its result by returning from functions.

</warning>

<code-group>

```vue [Nuxt 2]
<script>
export default {
  methods: {
    navigate () {
      this.$router.push({
        path: '/search',
        query: {
          name: 'first name',
          type: '1',
        },
      })
    },
  },
}
</script>
```

```vue [Nuxt 3]
<script setup lang="ts">
function navigate () {
  return navigateTo({
    path: '/search',
    query: {
      name: 'first name',
      type: '1',
    },
  })
}
</script>
```

</code-group>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/routing/pages.md

# Source: https://nuxt.com/raw/docs/3.x/api/kit/pages.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/pages.md

# Source: https://nuxt.com/raw/docs/4.x/examples/routing/pages.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/pages.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/pages.md

# pages

> Nuxt provides file-based routing to create routes within your web application.

<note>

To reduce your application's bundle size, this directory is **optional**, meaning that [`vue-router`](https://router.vuejs.org) won't be included if you only use [`app.vue`](/docs/4.x/directory-structure/app/app). To force the pages system, set `pages: true` in `nuxt.config` or have a [`router.options.ts`](/docs/4.x/guide/recipes/custom-routing#using-routeroptions).

</note>

## Usage

Pages are Vue components and can have any [valid extension](/docs/4.x/api/nuxt-config#extensions) that Nuxt supports (by default `.vue`, `.js`, `.jsx`, `.mjs`, `.ts` or `.tsx`).

Nuxt will automatically create a route for every page in your `~/pages/` directory.

<code-group>

```vue [app/pages/index.vue]
<template>
  <h1>Index page</h1>
</template>
```

```ts [pages/index.ts]twoslash
// https://vuejs.org/guide/extras/render-function.html
export default defineComponent({
  render () {
    return h('h1', 'Index page')
  },
})
```

```tsx [pages/index.tsx]twoslash
// https://nuxt.com/docs/4.x/examples/advanced/jsx
// https://vuejs.org/guide/extras/render-function.html#jsx-tsx
export default defineComponent({
  render () {
    return <h1>Index page</h1>
  },
})
```

</code-group>

The `app/pages/index.vue` file will be mapped to the `/` route of your application.

If you are using [`app.vue`](/docs/4.x/directory-structure/app/app), make sure to use the [`<NuxtPage/>`](/docs/4.x/api/components/nuxt-page) component to display the current page:

```vue [app/app.vue]
<template>
  <div>
    <!-- Markup shared across all pages, ex: NavBar -->
    <NuxtPage />
  </div>
</template>
```

Pages **must have a single root element** to allow [route transitions](/docs/4.x/getting-started/transitions) between pages. HTML comments are considered elements as well.

This means that when the route is server-rendered, or statically generated, you will be able to see its contents correctly, but when you navigate towards that route during client-side navigation the transition between routes will fail and you'll see that the route will not be rendered.

Here are some examples to illustrate what a page with a single root element looks like:

<code-group>

```vue [app/pages/working.vue]
<template>
  <div>
    <!-- This page correctly has only one single root element -->
    Page content
  </div>
</template>
```

```vue [app/pages/bad-1.vue]
<template>
  <!-- This page will not render when route changes during client side navigation, because of this comment -->
  <div>Page content</div>
</template>
```

```vue [app/pages/bad-2.vue]
<template>
  <div>This page</div>
  <div>Has more than one root element</div>
  <div>And will not render when route changes during client side navigation</div>
</template>
```

</code-group>

## Dynamic Routes

If you place anything within square brackets, it will be turned into a [dynamic route](https://router.vuejs.org/guide/essentials/dynamic-matching) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory.

If you want a parameter to be *optional*, you must enclose it in double square brackets - for example, `~/pages/[[slug]]/index.vue` or `~/pages/[[slug]].vue` will match both `/` and `/test`.

```bash [Directory Structure]
-| pages/
---| index.vue
---| users-[group]/
-----| [id].vue
```

Given the example above, you can access group/id within your component via the `$route` object:

```vue [app/pages/users-[group]/[id].vue]
<template>
  <p>{{ $route.params.group }} - {{ $route.params.id }}</p>
</template>
```

Navigating to `/users-admins/123` would render:

```html
<p>admins - 123</p>
```

If you want to access the route using Composition API, there is a global [`useRoute`](/docs/4.x/api/composables/use-route) function that will allow you to access the route just like `this.$route` in the Options API.

```vuetwoslash
<script setup lang="ts">
const route = useRoute()

if (route.params.group === 'admins' && !route.params.id) {
  console.log('Warning! Make sure user is authenticated!')
}
</script>
```

<note>

Named parent routes will take priority over nested dynamic routes. For the `/foo/hello` route, `~/pages/foo.vue` will take priority over `~/pages/foo/[slug].vue`. <br />

 Use `~/pages/foo/index.vue` and `~/pages/foo/[slug].vue` to match `/foo` and `/foo/hello` with different pages,.

</note>

<video-accordion platform="vimeo" title="Watch a video from Vue School on dynamic routes" video-id="754465699">



</video-accordion>

## Catch-all Route

If you need a catch-all route, you create it by using a file named like `[...slug].vue`. This will match *all* routes under that path.

```vue [app/pages/[...slug].vue]
<template>
  <p>{{ $route.params.slug }}</p>
</template>
```

Navigating to `/hello/world` would render:

```html
<p>["hello", "world"]</p>
```

## Nested Routes

It is possible to display [nested routes](https://router.vuejs.org/guide/essentials/nested-routes) with `<NuxtPage>`.

Example:

```bash [Directory Structure]
-| pages/
---| parent/
-----| child.vue
---| parent.vue
```

This file tree will generate these routes:

```js
[
  {
    path: '/parent',
    component: '~/pages/parent.vue',
    name: 'parent',
    children: [
      {
        path: 'child',
        component: '~/pages/parent/child.vue',
        name: 'parent-child',
      },
    ],
  },
]
```

To display the `child.vue` component, you have to insert the `<NuxtPage>` component inside `app/pages/parent.vue`:

```vue [pages/parent.vue]
<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :foobar="123" />
  </div>
</template>
```

```vue [pages/parent/child.vue]
<script setup lang="ts">
const props = defineProps({
  foobar: String,
})

console.log(props.foobar)
</script>
```

### Child Route Keys

If you want more control over when the `<NuxtPage>` component is re-rendered (for example, for transitions), you can either pass a string or function via the `pageKey` prop, or you can define a `key` value via `definePageMeta`:

```vue [pages/parent.vue]
<template>
  <div>
    <h1>I am the parent view</h1>
    <NuxtPage :page-key="route => route.fullPath" />
  </div>
</template>
```

Or alternatively:

```vue [pages/parent/child.vue]twoslash
<script setup lang="ts">
definePageMeta({
  key: route => route.fullPath,
})
</script>
```

<link-example to="/docs/4.x/examples/routing/pages">



</link-example>

## Route Groups

In some cases, you may want to group a set of routes together in a way which doesn't affect file-based routing. For this purpose, you can put files in a folder which is wrapped in parentheses - `(` and `)`.

For example:

```bash [Directory structure]
-| pages/
---| index.vue
---| (marketing)/
-----| about.vue
-----| contact.vue
```

This will produce `/`, `/about` and `/contact` pages in your app. The `marketing` group is ignored for purposes of your URL structure.

### Accessing Route Groups

Route groups are automatically available in the route metadata as `route.meta.groups`.
This allows you to access the group information in your components for conditional logic, styling, or other purposes.

```vue [pages/(marketing)/about.vue]
<script setup lang="ts">
const route = useRoute()

console.log(route.meta.groups) // Output: ['marketing']
</script>

<template>
  <div>
    <p v-if="route.meta.groups?.includes('marketing')">
      This is a marketing page
    </p>
  </div>
</template>
```

## Page Metadata

You might want to define metadata for each route in your app. You can do this using the `definePageMeta` macro, which will work both in `<script>` and in `<script setup>`:

```vuetwoslash
<script setup lang="ts">
definePageMeta({
  title: 'My home page',
})
</script>
```

This data can then be accessed throughout the rest of your app from the `route.meta` object.

```vuetwoslash
<script setup lang="ts">
const route = useRoute()

console.log(route.meta.title) // My home page
</script>
```

If you are using nested routes, the page metadata from all these routes will be merged into a single object. For more on route meta, see the [vue-router docs](https://router.vuejs.org/guide/advanced/meta).

Much like `defineEmits` or `defineProps` (see [Vue docs](https://vuejs.org/api/sfc-script-setup#defineprops-defineemits)), `definePageMeta` is a **compiler macro**. It will be compiled away so you cannot reference it within your component. Instead, the metadata passed to it will be hoisted out of the component.
Therefore, the page meta object cannot reference the component. However, it can reference imported bindings, as well as locally defined **pure functions**.

<warning>

Make sure not to reference any reactive data or functions that cause side effects. This can lead to unexpected behavior.

</warning>

```vue
<script setup lang="ts">
import { someData } from '~/utils/example'

function validateIdParam (route) {
  return route.params.id && !Number.isNaN(Number(route.params.id))
}

const title = ref('')

definePageMeta({
  validate: validateIdParam,
  someData,
  title, // do not do this, the ref will be hoisted out of the component
})
</script>
```

### Special Metadata

Of course, you are welcome to define metadata for your own use throughout your app. But some metadata defined with `definePageMeta` has a particular purpose:

#### `alias`

You can define page aliases. They allow you to access the same page from different paths. It can be either a string or an array of strings as defined [in the vue-router documentation](https://router.vuejs.org/guide/essentials/redirect-and-alias#Alias).

#### `keepalive`

Nuxt will automatically wrap your page in [the Vue `<KeepAlive>` component](https://vuejs.org/guide/built-ins/keep-alive#keepalive) if you set `keepalive: true` in your `definePageMeta`. This might be useful to do, for example, in a parent route that has dynamic child routes, if you want to preserve page state across route changes.

When your goal is to preserve state for parent routes use this syntax: `<NuxtPage keepalive />`. You can also set props to be passed to `<KeepAlive>` (see [a full list](https://vuejs.org/api/built-in-components#keepalive)).

You can set a default value for this property [in your `nuxt.config`](/docs/4.x/api/nuxt-config#keepalive).

#### `key`

[See above](/docs/4.x/directory-structure/app/pages#child-route-keys).

#### `layout`

You can define the layout used to render the route. This can be either false (to disable any layout), a string or a ref/computed, if you want to make it reactive in some way. [More about layouts](/docs/4.x/directory-structure/app/layouts).

#### `layoutTransition` and `pageTransition`

You can define transition properties for the `<transition>` component that wraps your pages and layouts, or pass `false` to disable the `<transition>` wrapper for that route. You can see [a list of options that can be passed](https://vuejs.org/api/built-in-components#transition) or read [more about how transitions work](https://vuejs.org/guide/built-ins/transition#transition).

You can set default values for these properties [in your `nuxt.config`](/docs/4.x/api/nuxt-config#layouttransition).

#### `middleware`

You can define middleware to apply before loading this page. It will be merged with all the other middleware used in any matching parent/child routes. It can be a string, a function (an anonymous/inlined middleware function following [the global before guard pattern](https://router.vuejs.org/guide/advanced/navigation-guards#Global-Before-Guards)), or an array of strings/functions. [More about named middleware](/docs/4.x/directory-structure/app/middleware).

#### `name`

You may define a name for this page's route.

#### `path`

You may define a path matcher, if you have a more complex pattern than can be expressed with the file name. See [the `vue-router` docs](https://router.vuejs.org/guide/essentials/route-matching-syntax#Custom-regex-in-params) for more information.

#### `props`

Allows accessing the route `params` as props passed to the page component. See [the `vue-router` docs](https://router.vuejs.org/guide/essentials/passing-props) for more information.

### Typing Custom Metadata

If you add custom metadata for your pages, you may wish to do so in a type-safe way. It is possible to augment the type of the object accepted by `definePageMeta`:

```ts [index.d.ts]
declare module '#app' {
  interface PageMeta {
    pageType?: string
  }
}

// It is always important to ensure you import/export something when augmenting a type
export {}
```

## Navigation

To navigate between pages of your app, you should use the [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) component.

This component is included with Nuxt and therefore you don't have to import it as you do with other components.

A simple link to the `index.vue` page in your `app/pages` folder:

```vue
<template>
  <NuxtLink to="/">Home page</NuxtLink>
</template>
```

<read-more to="/docs/4.x/api/components/nuxt-link">

Learn more about `<NuxtLink>` usage.

</read-more>

## Programmatic Navigation

Nuxt allows programmatic navigation through the `navigateTo()` utility method. Using this utility method, you will be able to programmatically navigate the user in your app. This is great for taking input from the user and navigating them dynamically throughout your application. In this example, we have a simple method called `navigate()` that gets called when the user submits a search form.

<note>

Make sure to always `await` on `navigateTo` or chain its result by returning from functions.

</note>

```vuetwoslash
<script setup lang="ts">
const name = ref('')
const type = ref(1)

function navigate () {
  return navigateTo({
    path: '/search',
    query: {
      name: name.value,
      type: type.value,
    },
  })
}
</script>
```

## Client-Only Pages

You can define a page as [client only](/docs/4.x/directory-structure/app/components#client-components) by giving it a `.client.vue` suffix. None of the content of this page will be rendered on the server.

## Server-Only Pages

You can define a page as [server only](/docs/4.x/directory-structure/app/components#server-components) by giving it a `.server.vue` suffix. While you will be able to navigate to the page using client-side navigation, controlled by `vue-router`, it will be rendered with a server component automatically, meaning the code required to render the page will not be in your client-side bundle.

<warning>

Server-only pages must have a single root element. (HTML comments are considered elements as well.)

</warning>

## Custom Routing

As your app gets bigger and more complex, your routing might require more flexibility. For this reason, Nuxt directly exposes the router, routes and router options for customization in different ways.

<read-more to="/docs/4.x/guide/recipes/custom-routing">



</read-more>

## Multiple Pages Directories

By default, all your pages should be in one `app/pages` directory at the root of your project.

However, you can use [Nuxt Layers](/docs/4.x/getting-started/layers) to create groupings of your app's pages:

```bash [Directory Structure]
-| some-app/
---| nuxt.config.ts
---| pages/
-----| app-page.vue
-| nuxt.config.ts
```

```ts [some-app/nuxt.config.ts]twoslash
// some-app/nuxt.config.ts
export default defineNuxtConfig({
})
```

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  extends: ['./some-app'],
})
```

<read-more to="/docs/4.x/guide/going-further/layers">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/best-practices/performance.md

# Source: https://nuxt.com/raw/docs/4.x/guide/best-practices/performance.md

# Nuxt performance

> Best practices for improving performance of Nuxt apps.

Nuxt comes with built-in features designed to improve your application's performance and contribute to better [Core Web Vitals](https://web.dev/articles/vitals). There are also multiple Nuxt core modules that assist in improving performance in specific areas. This guide outlines best practices to optimize performance of your Nuxt application.

## Built-in Features

Nuxt offers several built-in features that help you optimize performance of your website. Understanding how these features work is crucial for achieving blazingly-fast performance.

### Links

[`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) is a drop-in replacement for both Vue Router's `<RouterLink>` component and HTML's `<a>` tag. It intelligently determines whether the link is internal or external and renders it accordingly with available optimizations (prefetching, default attributes, etc.)

```html
<template>
  <NuxtLink to="/about">About page</NuxtLink>
</template>

<!-- Which will render to with Vue Router & Smart Prefetching -->
<a href="/about">About page</a>
```

Nuxt automatically includes smart prefetching. That means it detects when a link is visible (by default), either in the viewport or when scrolling and prefetches the JavaScript for those pages so that they are ready when the user clicks the link.

You can also opt for prefetching on interaction instead:

```ts
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetchOn: 'interaction',
      },
    },
  },
})
```

<read-more title="NuxtLink" to="/docs/4.x/api/components/nuxt-link">



</read-more>

### Hybrid Rendering

In more complex applications, we may need a full control over how our application is rendered to support cases where some pages could be generated at build time, while others should be client-side rendered

Hybrid rendering allows different caching rules per route using Route Rules and decides how the server should respond to a new request on a given URL:

```ts
export default defineNuxtConfig({
  routeRules: {
    '/': {
      prerender: true,
    },
    '/products/**': {
      swr: 3600,
    },
    '/blog': {
      isr: 3600,
    },
    '/admin/**': {
      ssr: false,
    },
  },
})
```

Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using Nitro caching layer.

<read-more title="Hybrid rendering" to="/docs/4.x/guide/concepts/rendering#hybrid-rendering">



</read-more>

### Lazy Loading Components

To dynamically import a component (also known as lazy-loading a component) all you need to do is add the Lazy prefix to the component's name. This is useful if the component is not always needed.

```html
<script setup lang="ts">
const show = ref(false)
</script>

<template>
  <div>
    <h1>Mountains</h1>
    <LazyMountainsList v-if="show" />
    <button v-if="!show" @click="show = true">Show List</button>
  </div>
</template>
```

By using the Lazy prefix you can delay loading the component code until the right moment, which can be helpful for optimizing your JavaScript bundle size.

<read-more title="Lazy loading components" to="/docs/4.x/directory-structure/app/components#dynamic-imports">



</read-more>

### Lazy Hydration

It is not always necessary to hydrate (or make interactive) all the components of your site on the initial load. Using lazy hydration, you can control when components can have their code loaded, which can improve the time-to-interactive metric for your app. Nuxt allows you to control when components become interactive with lazy hydration (added in Nuxt v3.16).

```html
<template>
  <div>
    <LazyMyComponent hydrate-on-visible />
  </div>
</template>
```

To optimize your app, you may want to delay the hydration of some components until they're visible, or until the browser is done with more important tasks.

<read-more title="Lazy hydration" to="/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration">



</read-more>

### Fetching data

To avoid fetching same data twice (once on the server and once on client) Nuxt provides [`useFetch`](/docs/4.x/api/composables/use-fetch) and [`useAsyncData`](/docs/4.x/api/composables/use-async-data). They ensure that if an API call is made on the server, the data is forwarded to the client in the payload instead of being fetched again.

<read-more title="Data fetching" to="/docs/4.x/getting-started/data-fetching">



</read-more>

## Core Nuxt Modules

Apart from Nuxt's built-in features, there are also core modules maintained by the Nuxt team which help improve performance even further. These modules help handle assets such as images, custom fonts, or third party scripts.

### Images

Unoptimized images can have a significant negative impact on your website performance, specifically the [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp) score.

In Nuxt we can use [Nuxt Image](https://image.nuxt.com/) module that is a plug-and-play image optimization for Nuxt apps. It allows resizing and transforming your images using built-in optimizer or your favorite images CDN.

<video-accordion title="Watch the video by LearnVue about Nuxt Image" video-id="_UBff2eqGY0">



</video-accordion>

[`<NuxtImg>`](/docs/4.x/api/components/nuxt-img) is a drop-in replacement for the native `<img>` tag that comes with following enhancements:

- Uses built-in provider to optimize local and remote images
- Converts `src` to provider optimized URLs with modern formats such as WebP or Avif
- Automatically resizes images based on `width` and `height`
- Generates responsive `sizes` when providing sizes option
- Supports native `lazy loading` as well as other `<img>` attributes

Images in your website can usually be separated by importance; the ones that are needed to be delivered first at initial load (i.e. `Largest Contentful Paint`), and the ones that can be loaded later or when specifically needed. For that, we could use the following optimizations:

```html
<template>
  <!-- 🚨 Needs to be loaded ASAP -->
  <NuxtImg
    src="/hero-banner.jpg"
    format="webp"
    preload
    loading="eager"
    fetch-priority="high"
    width="200"
    height="100"
  />

  <!-- 🐌 Can be loaded later -->
  <NuxtImg
    src="/facebook-logo.jpg"
    format="webp"
    loading="lazy"
    fetch-priority="low"
    width="200"
    height="100"
  />
</template>
```

<read-more title="Nuxt Image" to="https://image.nuxt.com/usage/nuxt-img">



</read-more>

### Fonts

[Nuxt Fonts](https://fonts.nuxt.com/) will automatically optimize your fonts (including custom fonts) and remove external network requests for improved privacy and performance.

It includes built-in automatic self-hosting for any font file which means you can optimally load web fonts with reduced layout shift, thanks to the underlying package [fontaine](https://github.com/unjs/fontaine).

<video-accordion title="Watch the talk by Daniel Roe about the idea behind Nuxt Fonts" video-id="D3F683UViBY">



</video-accordion>

Nuxt Fonts processes all your CSS and does the following things automatically when it encounters a font-family declaration.

1. **Resolves fonts** – Looks for font files in public/, then checks web providers like Google, Bunny, and Fontshare.
2. **Generates @font-face rules** – Injects CSS rules to load fonts from the correct sources.
3. **Proxies & caches fonts** – Rewrites URLs to `/_fonts`, downloads and caches fonts locally.
4. **Creates fallback metrics** – Adjusts local system fonts to match web fonts, reducing layout shift ([CLS](https://web.dev/articles/cls)).
5. **Includes fonts in build** – Bundles fonts with your project, hashing file names and setting long-lived cache headers.

It supports multiple providers that are designed to be pluggable and extensible, so no matter your setup you should be able to use an existing provider or write your own.

### Scripts

Third-party resources like analytics tools, video embeds, maps, and social media integrations enhance website functionality but can significantly degrade user experience and negatively impact [Interaction to Next Paint (INP)](https://web.dev/articles/inp) and Largest Contentful Paint (LCP) scores.

[Nuxt Scripts](https://scripts.nuxt.com/) lets you load third-party scripts with better performance, privacy, security and DX.

<video-accordion title="Watch the video by Alex Lichter about Nuxt Scripts" video-id="sjMqUUvH9AE">



</video-accordion>

Nuxt Scripts provides an abstraction layer on top of third-party scripts, providing SSR support and type-safety and while still giving you full low-level control over how a script is loaded.

```ts
const { onLoaded, proxy } = useScriptGoogleAnalytics(
  {
    id: 'G-1234567',
    scriptOptions: {
      trigger: 'manual',
    },
  },
)
// queue events to be sent when ga loads
proxy.gtag('config', 'UA-123456789-1')
// or wait until ga is loaded
onLoaded((gtag) => {
  // script loaded
})
```

<read-more title="Nuxt Scripts" to="https://scripts.nuxt.com/scripts">



</read-more>

## Profiling Tools

To improve performance, we need to first know how to measure it, starting with measuring performance during development - on local environment, and then moving to auditing application that are deployed on production.

### Nuxi Analyze

[This](/docs/4.x/api/commands/analyze) command of `nuxi` allows to analyze the production bundle or your Nuxt application. It leverages `vite-bundle-visualizer` (similar to `webpack-bundle-analyzer`) to generate a visual representation of your application's bundle, making it easier to identify which components take up the most space.

When you see a large block in the visualization, it often signals an opportunity for optimization—whether by splitting it into smaller parts, implementing lazy loading, or replacing it with a more efficient alternative, especially for third-party libraries.

Large blocks containing multiple elements can often be reduced by importing only the necessary components rather than entire modules while large standalone blocks may be better suited for lazy loading rather than being included in the main bundle.

### Nuxt DevTools

The [Nuxt DevTools](https://devtools.nuxt.com/) gives you insights and transparency about your Nuxt App to identify performance gaps and seamlessly manage your app configurations.

![Nuxt DevTools example](https://user-images.githubusercontent.com/11247099/217670806-fb39aeff-3881-44e5-b9c8-6c757f5925fc.png)

It comes with several features we can use to measure performance of Nuxt apps:

1. **Timeline** – Tracks time spent on rendering, updating, and initializing components to identify performance bottlenecks.
2. **Assets** – Displays file sizes (e.g., images) without transformations.
3. **Render Tree** – Shows connections between Vue components, scripts, and styles to optimize dynamic loading.
4. **Inspect** – Lists all files used in the Vue app with their size and evaluation time.

### Chrome DevTools

Chrome DevTools come with two useful tabs for measuring performance; `Performance` and `Lighthouse`.

When you open the [Performance](https://developer.chrome.com/docs/devtools/performance/overview) panel, it instantly shows your local **Largest Contentful Paint (LCP)** and **Cumulative Layout Shift (CLS)** scores (good, needs improvement, or bad).

If you interact with the page, it also captures **Interaction to Next Paint (INP)**, giving you a full view of your Core Web Vitals based on your device and network.

![Chrome DevTools Performance Panel](https://developer.chrome.com/static/docs/devtools/performance/image/cpu-throttling_856.png)

[Lighthouse](https://developer.chrome.com/docs/devtools/lighthouse) audits performance, accessibility, SEO, progressive web apps, and best practices. It runs tests on your page and generates a report. Use failing audits as a guide to improve your site.

![Lighthouse](https://developer.chrome.com/static/docs/lighthouse/images/lighthouse-overview_720.png)

Each audit has a reference document explaining why the audit is important, as well as how to fix it.

### PageSpeed Insights

[PageSpeed Insights (PSI)](https://developers.google.com/speed/docs/insights/v5/about) reports on the user experience of a page on both mobile and desktop devices, and provides suggestions on how that page may be improved.

It provides both lab and field data about a page. Lab data is useful for debugging issues, as it is collected in a controlled environment while field data is useful for capturing true, real-world user experience.

### Web Page Test

[WebPageTest](https://www.webpagetest.org/) is a web performance tool providing deep diagnostic information about how a page performs under a variety of conditions.

Each test can be run from different locations around the world, on real browsers, over any number of customizable network conditions.

## Common problems

When building more complex Nuxt applications, you will probably encounter some of the problems listed below. Understanding these problems and fixing them will help you improve performance of your website.

### Overusing plugins

**Problem**: A large number of plugins can cause performance issues, especially if they require expensive computations or take too long to initialize. Since plugins run during the hydration phase, inefficient setups can block rendering and degrade the user experience.

**Solution**: Inspect your plugins and see if some of them could be implemented rather as a composable or utility function instead.

### Unused code / dependencies

**Problem**: With the development of the project, there can be a case where there will be some unused code or a dependency. This additional functionality may not be used or needed while it will be increase the bundle size of our project.

**Solution**: Inspect your `package.json` for unused dependencies and analyze your code for unused utils/composables/functions.

### Not using Vue Performance tips

**Problem**: [Vue documentation](https://vuejs.org/guide/best-practices/performance) lists several Performance improvements we can use in our Nuxt projects as well but as they are part of Vue documentation, developers tend to forget about it and focus on Nuxt specific improvements only - while Nuxt application is still a Vue project.

**Solution**: Use concepts such as `shallowRef`, `v-memo`, `v-once`, etc to improve performance.

### Not following patterns

**Problem**: The more people are currently working on the project, the more difficult it will be to maintain the stable codebase. Developers have a tendency to introduce new concepts they've seen in another project which can cause conflicts and problems with performance.

**Solution**: Establish rules and patterns in the project such as [Good practices and Design Patterns for Vue Composables](https://dev.to/jacobandrewsky/good-practices-and-design-patterns-for-vue-composables-24lk)

### Trying to load everything at the same time

**Problem**: When a page is loaded and it is not correctly instructed about the order of loading elements it will result in fetching everything at the same time - which can be slow and result in bad User Experience.

**Solution**: Use concepts such as Progressive Enhancement where core webpage content is set first, then more nuanced and technically rigorous layers of presentation and features are added on top as the browser/internet connection allow.

## Useful Resources

To learn more about various techniques for improving performance, take a look at the following resources:

1. [Apply instant loading with the PRPL pattern](https://web.dev/articles/apply-instant-loading-with-prpl)
2. [Perceived performance](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Performance/Perceived_performance)
3. [Understanding Critical Rendering Path](https://developer.mozilla.org/en-US/docs/Web/Performance/Guides/Critical_rendering_path)

---

# Source: https://nuxt.com/raw/docs/3.x/migration/plugins-and-middleware.md

# Source: https://nuxt.com/raw/docs/3.x/bridge/plugins-and-middleware.md

# Source: https://nuxt.com/raw/docs/4.x/migration/plugins-and-middleware.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/plugins-and-middleware.md

# Plugins and Middleware

> Learn how to migrate from Nuxt 2 to Nuxt Bridge new plugins and middleware.

## New Plugins Format

You can now migrate to the Nuxt 3 plugins API, which is slightly different in format from Nuxt 2.

Plugins now take only one argument (`nuxtApp`). You can find out more in [the docs](/docs/4.x/directory-structure/app/plugins).

```ts [app/plugins/hello.ts]
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.provide('injected', () => 'my injected function')
  // now available on `nuxtApp.$injected`
})
```

<note>

If you want to use the new Nuxt composables (such as [`useNuxtApp`](/docs/4.x/api/composables/use-nuxt-app) or `useRuntimeConfig`) within your plugins, you will need to use the `defineNuxtPlugin` helper for those plugins.

</note>

<warning>

Although a compatibility interface is provided via `nuxtApp.vueApp` you should avoid registering plugins, directives, mixins or components this way without adding your own logic to ensure they are not installed more than once, or this may cause a memory leak.

</warning>

## New Middleware Format

You can now migrate to the Nuxt 3 middleware API, which is slightly different in format from Nuxt 2.

Middleware now take only two argument (`to`, `from`). You can find out more in [the docs](/docs/4.x/directory-structure/app/middleware).

```tstwoslash
export default defineNuxtRouteMiddleware((to) => {
  if (to.path !== '/') {
    return navigateTo('/')
  }
})
```

<important>

Use of `defineNuxtRouteMiddleware` is not supported outside of the `app/middleware` directory.

</important>

## definePageMeta

You can also use [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) in Nuxt Bridge.

It can be enabled with the `macros.pageMeta` option in your configuration file

```ts [nuxt.config.ts]
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    macros: {
      pageMeta: true,
    },
  },
})
```

<note>

But only for `middleware` and `layout`.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/plugins.md

# Source: https://nuxt.com/raw/docs/3.x/guide/best-practices/plugins.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/plugins.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/plugins.md

# Source: https://nuxt.com/raw/docs/4.x/guide/best-practices/plugins.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/plugins.md

# plugins

> Nuxt has a plugins system to use Vue plugins and more at the creation of your Vue application.

Nuxt automatically reads the files in the `app/plugins/` directory and loads them at the creation of the Vue application.

<note>

All plugins inside are auto-registered, you don't need to add them to your `nuxt.config` separately.

</note>

<note>

You can use `.server` or `.client` suffix in the file name to load a plugin only on the server or client side.

</note>

## Registered Plugins

Only files at the top level of the directory (or index files within any subdirectories) will be auto-registered as plugins.

```bash [Directory structure]
-| plugins/
---| foo.ts      // scanned
---| bar/
-----| baz.ts    // not scanned
-----| foz.vue   // not scanned
-----| index.ts  // currently scanned but deprecated
```

Only `foo.ts` and `bar/index.ts` would be registered.

To add plugins in subdirectories, you can use the [`app/plugins`](/docs/4.x/api/nuxt-config#plugins-1) option in `nuxt.config.ts`:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  plugins: [
    '~/plugins/bar/baz',
    '~/plugins/bar/foz',
  ],
})
```

## Creating Plugins

The only argument passed to a plugin is [`nuxtApp`](/docs/4.x/api/composables/use-nuxt-app).

```ts [plugins/hello.ts]twoslash
export default defineNuxtPlugin((nuxtApp) => {
  // Doing something with nuxtApp
})
```

### Object Syntax Plugins

It is also possible to define a plugin using an object syntax, for more advanced use cases. For example:

```ts [plugins/hello.ts]twoslash
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre', // or 'post'
  async setup (nuxtApp) {
    // this is the equivalent of a normal functional plugin
  },
  hooks: {
    // You can directly register Nuxt app runtime hooks here
    'app:created' () {
      const nuxtApp = useNuxtApp()
      // do something in the hook
    },
  },
  env: {
    // Set this value to `false` if you don't want the plugin to run when rendering server-only or island components.
    islands: true,
  },
})
```

<video-accordion title="Watch a video from Alexander Lichter about the Object Syntax for Nuxt plugins" video-id="2aXZyXB1QGQ">



</video-accordion>

<note>

If you are using the object-syntax, the properties are statically analyzed to produce a more optimized build. So you should not define them at runtime. <br />


For example, setting `enforce: import.meta.server ? 'pre' : 'post'` would defeat any future optimization Nuxt is able to do for your plugins.
Nuxt does statically pre-load any hook listeners when using object-syntax, allowing you to define hooks without needing to worry about order of plugin registration.

</note>

## Registration Order

You can control the order in which plugins are registered by prefixing with 'alphabetical' numbering to the file names.

```bash [Directory structure]
plugins/
 | - 01.myPlugin.ts
 | - 02.myOtherPlugin.ts
```

In this example, `02.myOtherPlugin.ts` will be able to access anything that was injected by `01.myPlugin.ts`.

This is useful in situations where you have a plugin that depends on another plugin.

<note>

In case you're new to 'alphabetical' numbering, remember that filenames are sorted as strings, not as numeric values. For example, `10.myPlugin.ts` would come before `2.myOtherPlugin.ts`. This is why the example prefixes single digit numbers with `0`.

</note>

## Loading Strategy

### Parallel Plugins

By default, Nuxt loads plugins sequentially. You can define a plugin as `parallel` so Nuxt won't wait until the end of the plugin's execution before loading the next plugin.

```ts [plugins/my-plugin.ts]twoslash
export default defineNuxtPlugin({
  name: 'my-plugin',
  parallel: true,
  async setup (nuxtApp) {
    // the next plugin will be executed immediately
  },
})
```

### Plugins With Dependencies

If a plugin needs to wait for another plugin before it runs, you can add the plugin's name to the `dependsOn` array.

```ts [plugins/depending-on-my-plugin.ts]twoslash
export default defineNuxtPlugin({
  name: 'depends-on-my-plugin',
  dependsOn: ['my-plugin'],
  async setup (nuxtApp) {
    // this plugin will wait for the end of `my-plugin`'s execution before it runs
  },
})
```

## Using Composables

You can use [composables](/docs/4.x/directory-structure/app/composables) as well as [utils](/docs/4.x/directory-structure/app/utils) within Nuxt plugins:

```ts [app/plugins/hello.ts]
export default defineNuxtPlugin((nuxtApp) => {
  const foo = useFoo()
})
```

However, keep in mind there are some limitations and differences:

<important>

**If a composable depends on another plugin registered later, it might not work.** <br />



Plugins are called in order sequentially and before everything else. You might use a composable that depends on another plugin which has not been called yet.

</important>

<important>

**If a composable depends on the Vue.js lifecycle, it won't work.** <br />



Normally, Vue.js composables are bound to the current component instance while plugins are only bound to [`nuxtApp`](/docs/4.x/api/composables/use-nuxt-app) instance.

</important>

## Providing Helpers

If you would like to provide a helper on the [`NuxtApp`](/docs/4.x/api/composables/use-nuxt-app) instance, return it from the plugin under a `provide` key.

<code-group>

```ts [plugins/hello.ts]twoslash
export default defineNuxtPlugin(() => {
  return {
    provide: {
      hello: (msg: string) => `Hello ${msg}!`,
    },
  }
})
```

```ts [plugins/hello-object-syntax.ts]twoslash
export default defineNuxtPlugin({
  name: 'hello',
  setup () {
    return {
      provide: {
        hello: (msg: string) => `Hello ${msg}!`,
      },
    }
  },
})
```

</code-group>

You can then use the helper in your components:

```vue [app/components/Hello.vue]
<script setup lang="ts">
// alternatively, you can also use it here
const { $hello } = useNuxtApp()
</script>

<template>
  <div>
    {{ $hello('world') }}
  </div>
</template>
```

<important>

Note that we highly recommend using [`composables`](/docs/4.x/directory-structure/app/composables) instead of providing helpers to avoid polluting the global namespace and keep your main bundle entry small.

</important>

<warning>

**If your plugin provides a ref or computed, it will not be unwrapped in a component <template>.** <br />


This is due to how Vue works with refs that aren't top-level to the template. You can read more about it [in the Vue documentation](https://vuejs.org/guide/essentials/reactivity-fundamentals#caveat-when-unwrapping-in-templates).

</warning>

## Typing Plugins

If you return your helpers from the plugin, they will be typed automatically; you'll find them typed for the return of `useNuxtApp()` and within your templates.

<note>

If you need to use a provided helper *within* another plugin, you can call [`useNuxtApp()`](/docs/4.x/api/composables/use-nuxt-app) to get the typed version. But in general, this should be avoided unless you are certain of the plugins' order.

</note>

For advanced use-cases, you can declare the type of injected properties like this:

```ts [index.d.ts]
declare module '#app' {
  interface NuxtApp {
    $hello (msg: string): string
  }
}

declare module 'vue' {
  interface ComponentCustomProperties {
    $hello (msg: string): string
  }
}

export {}
```

## Vue Plugins

If you want to use Vue plugins, like [vue-gtag](https://github.com/MatteoGabriele/vue-gtag) to add Google Analytics tags, you can use a Nuxt plugin to do so.

First, install the Vue plugin dependency:

<code-group sync="pm">

```bash [npm]
npm install --save-dev vue-gtag-next
```

```bash [yarn]
yarn add --dev vue-gtag-next
```

```bash [pnpm]
pnpm add -D vue-gtag-next
```

```bash [bun]
bun add -D vue-gtag-next
```

```bash [deno]
deno add -D npm:vue-gtag-next
```

</code-group>

Then create a plugin file:

```ts [app/plugins/vue-gtag.client.ts]
import VueGtag, { trackRouter } from 'vue-gtag-next'

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(VueGtag, {
    property: {
      id: 'GA_MEASUREMENT_ID',
    },
  })
  trackRouter(useRouter())
})
```

## Vue Directives

Similarly, you can register a custom Vue directive in a plugin.

```ts [plugins/my-directive.ts]twoslash
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.directive('focus', {
    mounted (el) {
      el.focus()
    },
    getSSRProps (binding, vnode) {
      // you can provide SSR-specific props here
      return {}
    },
  })
})
```

<warning>

If you register a Vue directive, you *must* register it on both client and server side unless you are only using it when rendering one side. If the directive only makes sense from a client side, you can always move it to `~/plugins/my-directive.client.ts` and provide a 'stub' directive for the server in `~/plugins/my-directive.server.ts`.

</warning>

<read-more icon="i-simple-icons-vuedotjs" target="_blank" title="Custom Directives on Vue Docs" to="https://vuejs.org/guide/reusability/custom-directives.html">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/prefetch-components.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/prefetch-components.md

# prefetchComponents

> Nuxt provides utilities to give you control over prefetching components.

Prefetching component downloads the code in the background, this is based on the assumption that the component will likely be used for rendering, enabling the component to load instantly if and when the user requests it. The component is downloaded and cached for anticipated future use without the user making an explicit request for it.

Use `prefetchComponents` to manually prefetch individual components that have been registered globally in your Nuxt app. By default Nuxt registers these as async components. You must use the Pascal-cased version of the component name.

```ts
await prefetchComponents('MyGlobalComponent')

await prefetchComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
```

<note>

Current implementation behaves exactly the same as [`preloadComponents`](/docs/4.x/api/utils/preload-components) by preloading components instead of just prefetching we are working to improve this behavior.

</note>

<note>

On server, `prefetchComponents` will have no effect.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/preload-components.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/preload-components.md

# preloadComponents

> Nuxt provides utilities to give you control over preloading components.

Preloading components loads components that your page will need very soon, which you want to start loading early in rendering lifecycle. This ensures they are available earlier and are less likely to block the page's render, improving performance.

Use `preloadComponents` to manually preload individual components that have been registered globally in your Nuxt app. By default Nuxt registers these as async components. You must use the Pascal-cased version of the component name.

```ts
await preloadComponents('MyGlobalComponent')

await preloadComponents(['MyGlobalComponent1', 'MyGlobalComponent2'])
```

<note>

On server, `preloadComponents` will have no effect.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/preload-route-components.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/preload-route-components.md

# preloadRouteComponents

> preloadRouteComponents allows you to manually preload individual pages in your Nuxt app.

Preloading routes loads the components of a given route that the user might navigate to in future. This ensures that the components are available earlier and less likely to block the navigation, improving performance.

<tip icon="i-lucide-rocket">

Nuxt already automatically preloads the necessary routes if you're using the `NuxtLink` component.

</tip>

<read-more to="/docs/4.x/api/components/nuxt-link">



</read-more>

## Example

Preload a route when using `navigateTo`.

```ts
// we don't await this async function, to avoid blocking rendering
// this component's setup function
preloadRouteComponents('/dashboard')

const submit = async () => {
  const results = await $fetch('/api/authentication')

  if (results.token) {
    await navigateTo('/dashboard')
  }
}
```

<read-more to="/docs/4.x/api/utils/navigate-to">



</read-more>

<note>

On server, `preloadRouteComponents` will have no effect.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/prepare.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/prepare.md

# nuxt prepare

> The prepare command creates a .nuxt directory in your application and generates types.

```bash [Terminal]
npx nuxt prepare [ROOTDIR] [--dotenv] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>]
```

The `prepare` command creates a [`.nuxt`](/docs/4.x/directory-structure/nuxt) directory in your application and generates types. This can be useful in a CI environment or as a `postinstall` command in your [`package.json`](/docs/4.x/directory-structure/package).

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --envName
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The environment to use when resolving configuration overrides (default is <code>
        production
      </code>
      
       when building, and <code>
        development
      </code>
      
       when running the dev server)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
</tbody>
</table>

<note>

This command sets `process.env.NODE_ENV` to `production`.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/prerender-routes.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/prerender-routes.md

# prerenderRoutes

> prerenderRoutes hints to Nitro to prerender an additional route.

When prerendering, you can hint to Nitro to prerender additional paths, even if their URLs do not show up in the HTML of the generated page.

<important>

`prerenderRoutes` can only be called within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).

</important>

<note>

`prerenderRoutes` has to be executed during prerendering. If the `prerenderRoutes` is used in dynamic pages/routes which are not prerendered, then it will not be executed.

</note>

```ts
const route = useRoute()

prerenderRoutes('/')
prerenderRoutes(['/', '/about'])
```

<note>

In the browser, or if called outside prerendering, `prerenderRoutes` will have no effect.

</note>

You can even prerender API routes which is particularly useful for full statically generated sites (SSG) because you can then `$fetch` data as if you have an available server!

```ts
prerenderRoutes('/api/content/article/name-of-article')

// Somewhere later in App
const articleContent = await $fetch('/api/content/article/name-of-article', {
  responseType: 'json',
})
```

<warning>

Prerendered API routes in production may not return the expected response headers, depending on the provider you deploy to. For example, a JSON response might be served with an `application/octet-stream` content type.
Always manually set `responseType` when fetching prerendered API routes.

</warning>

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/prerendering.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/prerendering.md

# Prerendering

> Nuxt allows pages to be statically rendered at build time to improve certain performance or SEO metrics

Nuxt allows for select pages from your application to be rendered at build time. Nuxt will serve the prebuilt pages when requested instead of generating them on the fly.

<read-more to="/docs/4.x/guide/concepts/rendering" title="Nuxt rendering modes">



</read-more>

## Crawl-based Pre-rendering

Use the [`nuxt generate` command](/docs/4.x/api/commands/generate) to build and pre-render your application using the [Nitro](/docs/4.x/guide/concepts/server-engine) crawler. This command is similar to `nuxt build` with the `nitro.static` option set to `true`, or running `nuxt build --prerender`.

This will build your site, stand up a nuxt instance, and, by default, prerender the root page `/` along with any of your site's pages it links to, any of your site's pages they link to, and so on.

<code-group sync="pm">

```bash [npm]
npx nuxt generate
```

```bash [yarn]
yarn nuxt generate
```

```bash [pnpm]
pnpm nuxt generate
```

```bash [bun]
bun x nuxt generate
```

```bash [deno]
deno x nuxt generate
```

</code-group>

You can now deploy the `.output/public` directory to any static hosting service or preview it locally with `npx serve .output/public`.

Working of the Nitro crawler:

1. Load the HTML of your application's root route (`/`), any non-dynamic pages in your `~/pages` directory, and any other routes in the `nitro.prerender.routes` array.
2. Save the HTML and `payload.json` to the `~/.output/public/` directory to be served statically.
3. Find all anchor tags (`<a href="...">`) in the HTML to navigate to other routes.
4. Repeat steps 1-3 for each anchor tag found until there are no more anchor tags to crawl.

This is important to understand since pages that are not linked to a discoverable page can't be pre-rendered automatically.

### Payload Extraction

Nuxt generates `_payload.json` alongside HTML for:

- Prerendered routes (at build time)
- ISR/SWR routes (on first request)

Payloads contain serialized data from `useAsyncData` and `useFetch`. Client-side navigation loads these cached payloads instead of re-fetching data. Configure dynamic routes like `pages/[...slug].vue` with route rules: `'/**': { isr: true }`.

<read-more to="/docs/4.x/api/commands/generate#nuxt-generate">

Read more about the `nuxt generate` command.

</read-more>

### Selective Pre-rendering

You can manually specify routes that [Nitro](/docs/4.x/guide/concepts/server-engine) will fetch and pre-render during the build or ignore routes that you don't want to pre-render like `/dynamic` in the `nuxt.config` file:

```ts [nuxt.config.ts]twoslash
// @errors: 2353
export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/user/1', '/user/2'],
      ignore: ['/dynamic'],
    },
  },
})
```

You can combine this with the `crawlLinks` option to pre-render a set of routes that the crawler can't discover like your `/sitemap.xml` or `/robots.txt`:

```ts [nuxt.config.ts]twoslash
// @errors: 2353
export default defineNuxtConfig({
  nitro: {
    prerender: {
      crawlLinks: true,
      routes: ['/sitemap.xml', '/robots.txt'],
    },
  },
})
```

Setting `nitro.prerender` to `true` is similar to `nitro.prerender.crawlLinks` to `true`.

<read-more to="https://nitro.build/config#prerender">

Read more about pre-rendering in the Nitro documentation.

</read-more>

Lastly, you can manually configure this using routeRules.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  routeRules: {
    // Set prerender to true to configure it to be prerendered
    '/rss.xml': { prerender: true },
    // Set it to false to configure it to be skipped for prerendering
    '/this-DOES-NOT-get-prerendered': { prerender: false },
    // Everything under /blog gets prerendered as long as it
    // is linked to from another page
    '/blog/**': { prerender: true },
  },
})
```

<read-more to="https://nitro.build/config#routerules">

Read more about Nitro's `routeRules` configuration.

</read-more>

As a shorthand, you can also configure this in a page file using [`defineRouteRules`](/docs/4.x/api/utils/define-route-rules).

<read-more to="/docs/4.x/guide/going-further/experimental-features#inlinerouterules" icon="i-lucide-star">

This feature is experimental and in order to use it you must enable the `experimental.inlineRouteRules` option in your `nuxt.config`.

</read-more>

```vue [app/pages/index.vue]
<script setup>
// Or set at the page level
defineRouteRules({
  prerender: true,
})
</script>

<template>
  <div>
    <h1>Homepage</h1>
    <p>Pre-rendered at build time</p>
  </div>
</template>
```

This will be translated to:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
  },
})
```

## Runtime Prerender Configuration

### `prerenderRoutes`

You can use this at runtime within a [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context) to add more routes for Nitro to prerender.

```vue [app/pages/index.vue]
<script setup>
prerenderRoutes(['/some/other/url'])
prerenderRoutes('/api/content/article/my-article')
</script>

<template>
  <div>
    <h1>This will register other routes for prerendering when prerendered</h1>
  </div>
</template>
```

<read-more to="/docs/4.x/api/utils/prerender-routes" title="prerenderRoutes">



</read-more>

### `prerender:routes` Nuxt hook

This is called before prerendering for additional routes to be registered.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  hooks: {
    async 'prerender:routes' (ctx) {
      const { pages } = await fetch('https://api.some-cms.com/pages').then(
        res => res.json(),
      )
      for (const page of pages) {
        ctx.routes.add(`/${page.name}`)
      }
    },
  },
})
```

### `prerender:generate` Nitro hook

This is called for each route during prerendering. You can use this for fine-grained handling of each route that gets prerendered.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    hooks: {
      'prerender:generate' (route) {
        if (route.route?.includes('private')) {
          route.skip = true
        }
      },
    },
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/preview.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/preview.md

# nuxt preview

> The preview command starts a server to preview your application after the build command.

```bash [Terminal]
npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>] [-p, --port] [--dotenv]
```

The `preview` command starts a server to preview your Nuxt application after running the `build` command. The `start` command is an alias for `preview`. When running your application in production refer to the [Deployment section](/docs/4.x/getting-started/deployment).

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --envName
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      The environment to use when resolving configuration overrides (default is <code>
        production
      </code>
      
       when building, and <code>
        development
      </code>
      
       when running the dev server)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -p, --port
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Port to listen on (use <code>
        PORT
      </code>
      
       environment variable to override)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
</tbody>
</table>

This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a `.env` file or as command-line argument.

<note>

For convenience, in preview mode, your [`.env`](/docs/4.x/directory-structure/env) file will be loaded into `process.env`. (However, in production you will need to ensure your environment variables are set yourself. For example, with Node.js 20+ you could do this by running `node --env-file .env .output/server/index.mjs` to start your server.)

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/programmatic.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/programmatic.md

# Programmatic Usage

> Nuxt Kit provides a set of utilities to help you work with Nuxt programmatically. These functions allow you to load Nuxt, build Nuxt, and load Nuxt configuration.

Programmatic usage can be helpful when you want to use Nuxt programmatically, for example, when building a [CLI tool](https://github.com/nuxt/cli) or [test utils](https://github.com/nuxt/test-utils).

## `loadNuxt`

Load Nuxt programmatically. It will load the Nuxt configuration, instantiate and return the promise with Nuxt instance.

### Type

```ts
function loadNuxt (loadOptions?: LoadNuxtOptions): Promise<Nuxt>
```

### Parameters

**loadOptions**: Loading conditions for Nuxt. `loadNuxt` uses [`c12`](https://github.com/unjs/c12) under the hood, so it accepts the same options as `c12.loadConfig` with some additional options:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        dev
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , Nuxt will be loaded in development mode.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ready
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , Nuxt will be ready to use after the <code>
        loadNuxt
      </code>
      
       call. If set to <code>
        false
      </code>
      
      , you will need to call <code>
        nuxt.ready()
      </code>
      
       to make sure Nuxt is ready to use.
    </td>
  </tr>
</tbody>
</table>

## `buildNuxt`

Build Nuxt programmatically. It will invoke the builder (currently [@nuxt/vite-builder](https://github.com/nuxt/nuxt/tree/main/packages/vite) or [@nuxt/webpack-builder](https://github.com/nuxt/nuxt/tree/main/packages/webpack)) to bundle the application.

### Type

```ts
function buildNuxt (nuxt: Nuxt): Promise<any>
```

### Parameters

**nuxt**: Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.

## `loadNuxtConfig`

Load Nuxt configuration. It will return the promise with the configuration object.

### Type

```ts
function loadNuxtConfig (options: LoadNuxtConfigOptions): Promise<NuxtOptions>
```

### Parameters

**options**: Options to pass in [`c12`](https://github.com/unjs/c12#options) `loadConfig` call.

## `writeTypes`

Generates `tsconfig.json` and writes it to the project buildDir.

### Type

```ts
function writeTypes (nuxt?: Nuxt): void
```

### Parameters

**nuxt**: Nuxt instance to build. It can be retrieved from the context via `useNuxt()` call.

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/public.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/public.md

# public

> The public/ directory is used to serve your website's static assets.

Files contained within the `public/` directory are served at the root and are not modified by the build process. This is suitable for files that have to keep their names (e.g. `robots.txt`) *or* likely won't change (e.g. `favicon.ico`).

```bash [Directory structure]
-| public/
---| favicon.ico
---| og-image.png
---| robots.txt
```

```vue [app/app.vue]
<script setup lang="ts">
useSeoMeta({
  ogImage: '/og-image.png',
})
</script>
```

<tip target="_blank" to="https://v2.nuxt.com/docs/directory-structure/static/">

This is known as the <span>

`static/`

</span>

 directory in Nuxt 2.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/readme.md

# Source: https://nuxt.com/raw/docs/4.x/readme.md

# Nuxt Docs

This repository contains the documentation of Nuxt, hosted on [https://nuxt.com/docs/4.x/getting-started/introduction](https://nuxt.com/docs/4.x/getting-started/introduction)

## Contributing

Have a look at [https://github.com/nuxt/nuxt.com](https://github.com/nuxt/nuxt.com) to run the website locally.

---

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/recipes-advanced.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/recipes-advanced.md

# Use Hooks & Extend Types

> Master lifecycle hooks, virtual files and TypeScript declarations in your modules.

Here are some advanced patterns for authoring modules, including hooks, templates, and type augmentation.

## Use Lifecycle Hooks

[Lifecycle hooks](/docs/4.x/guide/going-further/hooks) allow you to expand almost every aspect of Nuxt. Modules can hook to them programmatically or through the `hooks` map in their definition.

```js
import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  // Hook to the `app:error` hook through the `hooks` map
  hooks: {
    'app:error': (err) => {
      console.info(`This error happened: ${err}`)
    },
  },
  setup (options, nuxt) {
    // Programmatically hook to the `pages:extend` hook
    nuxt.hook('pages:extend', (pages) => {
      console.info(`Discovered ${pages.length} pages`)
    })
  },
})
```

<read-more to="/docs/4.x/api/advanced/hooks">



</read-more>

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/nuxt-lifecycle-hooks?friend=nuxt">

Watch Vue School video about using Nuxt lifecycle hooks in modules.

</tip>

<note>

**Module cleanup**

<br />

<br />

If your module opens, handles, or starts a watcher, you should close it when the Nuxt lifecycle is done. The `close` hook is available for this.

```ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async (nuxt) => {
      // Your custom code here
    })
  },
})
```

</note>

### Create Custom Hooks

Modules can also define and call their own hooks, which is a powerful pattern for making your module extensible.

If you expect other modules to be able to subscribe to your module's hooks, you should call them in the `modules:done` hook. This ensures that all other modules have had a chance to be set up and register their listeners to your hook during their own `setup` function.

```ts
// my-module/module.ts
import { defineNuxtModule } from '@nuxt/kit'

export interface ModuleHooks {
  'my-module:custom-hook': (payload: { foo: string }) => void
}

export default defineNuxtModule({
  setup (options, nuxt) {
    // Call your hook in `modules:done`
    nuxt.hook('modules:done', async () => {
      const payload = { foo: 'bar' }
      await nuxt.callHook('my-module:custom-hook', payload)
    })
  },
})
```

## Add Virtual Files

If you need to add a virtual file that can be imported into the user's app, you can use the `addTemplate` utility.

```ts
import { addTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // The file is added to Nuxt's internal virtual file system and can be imported from '#build/my-module-feature.mjs'
    addTemplate({
      filename: 'my-module-feature.mjs',
      getContents: () => 'export const myModuleFeature = () => "hello world !"',
    })
  },
})
```

For the server, you should use the `addServerTemplate` utility instead.

```ts
import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // The file is added to Nitro's virtual file system and can be imported in the server code from 'my-server-module.mjs'
    addServerTemplate({
      filename: 'my-server-module.mjs',
      getContents: () => 'export const myServerModule = () => "hello world !"',
    })
  },
})
```

## Update Virtual Files

If you need to update your templates/virtual files, you can leverage the `updateTemplates` utility like this:

```ts
nuxt.hook('builder:watch', (event, path) => {
  if (path.includes('my-module-feature.config')) {
    // This will reload the template that you registered
    updateTemplates({ filter: t => t.filename === 'my-module-feature.mjs' })
  }
})
```

## Add Type Declarations

You might also want to add a type declaration to the user's project (for example, to augment a Nuxt interface
or provide a global type of your own). For this, Nuxt provides the `addTypeTemplate` utility that both
writes a template to the disk and adds a reference to it in the generated `nuxt.d.ts` file.

If your module should augment types handled by Nuxt, you can use `addTypeTemplate` to perform this operation:

```js
import { addTemplate, addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `// Generated by my-module
        interface MyModuleNitroRules {
          myModule?: { foo: 'bar' }
        }
        declare module 'nitropack/types' {
          interface NitroRouteRules extends MyModuleNitroRules {}
          interface NitroRouteConfig extends MyModuleNitroRules {}
        }
        export {}`,
    })
  },
})
```

If you need more granular control, you can use the `prepare:types` hook to register a callback that will inject your types.

```ts
const template = addTemplate({ /* template options */ })
nuxt.hook('prepare:types', ({ references }) => {
  references.push({ path: template.dst })
})
```

## Extend TypeScript Config

There are multiple ways to extend the TypeScript configuration of the user's project from your module.

The simplest way is to modify the Nuxt configuration directly like this:

```ts
// extend tsconfig.app.json
nuxt.options.typescript.tsConfig.include ??= []
nuxt.options.typescript.tsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.shared.json
nuxt.options.typescript.sharedTsConfig.include ??= []
nuxt.options.typescript.sharedTsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.node.json
nuxt.options.typescript.nodeTsConfig.include ??= []
nuxt.options.typescript.nodeTsConfig.include.push(resolve('./augments.d.ts'))

// extend tsconfig.server.json
nuxt.options.nitro.typescript ??= {}
nuxt.options.nitro.typescript.tsConfig ??= {}
nuxt.options.nitro.typescript.tsConfig.include ??= []
nuxt.options.nitro.typescript.tsConfig.include.push(resolve('./augments.d.ts'))
```

Alternatively, you can use the `prepare:types` and `nitro:prepare:types` hooks to extend the TypeScript references for specific type contexts, or modify the TypeScript configuration similar to the example above.

```ts
nuxt.hook('prepare:types', ({ references, sharedReferences, nodeReferences }) => {
  // extend app context
  references.push({ path: resolve('./augments.d.ts') })
  // extend shared context
  sharedReferences.push({ path: resolve('./augments.d.ts') })
  // extend node context
  nodeReferences.push({ path: resolve('./augments.d.ts') })
})

nuxt.hook('nitro:prepare:types', ({ references }) => {
  // extend server context
  references.push({ path: resolve('./augments.d.ts') })
})
```

<note>

TypeScript references add files to the type context [without being affected by the `exclude` option in `tsconfig.json`](https://www.typescriptlang.org/tsconfig/#exclude).

</note>

## Augment Types

Nuxt automatically includes your module's directories in the appropriate type contexts. To augment types from your module, all you need to do is place the type declaration file in the appropriate directory based on the augmented type context. Alternatively, you can [extend the TypeScript configuration](#extend-typescript-config) to augment from an arbitrary location.

- `my-module/runtime/` - app type context (except for the `runtime/server` directory)
- `my-module/runtime/server/` - server type context
- `my-module/` - node type context (except for the `runtime/` and `runtime/server` directories)

```bash [Directory Structure]
-| my-module/   # node type context
---| runtime/   # app type context
------| augments.app.d.ts
------| server/ # server type context
---------| augments.server.d.ts
---| module.ts
---| augments.node.d.ts
```

### Known Limitations

#### Type-Checking Server Routes in App Context

Server routes are also type-checked using `tsconfig.app.json` in addition to `tsconfig.server.json`.

This is required because Nuxt infers the return types of your server endpoints to provide response types in [`$fetch`](/docs/4.x/api/utils/dollarfetch) and [`useFetch`](/docs/4.x/api/composables/use-fetch).

<warning>

This can cause issues when using **server-only types** in your route files. For example, if a module creates a server-only virtual file using [`addServerTemplate`](/docs/4.x/api/kit/templates#addservertemplate) and you declare types for it in `tsconfig.server.json`, those type declarations will only be available in the server context. When the app context type-checks your server routes, it won't recognize these server-only types and will report errors.  To resolve this, you unfortunately need to declare such types in the app context as well.

</warning>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/recipes-basics.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/recipes-basics.md

# Add Plugins, Components & More

> Learn how to inject plugins, components, composables and server routes from your module.

Here are some common patterns used by module authors.

## Modify Nuxt Configuration

Nuxt configuration can be read and altered by modules. Here's an example of a module enabling an experimental feature.

```js
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // We create the `experimental` object if it doesn't exist yet
    nuxt.options.experimental ||= {}
    nuxt.options.experimental.componentIslands = true
  },
})
```

When you need to handle more complex configuration alterations, you should consider using [defu](https://github.com/unjs/defu).

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/extending-and-altering-nuxt-configuration-and-options?friend=nuxt">

Watch Vue School video about altering Nuxt configuration.

</tip>

## Expose Options to Runtime

Because modules aren't part of the application runtime, their options aren't either. However, in many cases, you might need access to some of these module options within your runtime code. We recommend exposing the needed config using Nuxt's [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig).

```js
import { defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.options.runtimeConfig.public.myModule = defu(nuxt.options.runtimeConfig.public.myModule, {
      foo: options.foo,
    })
  },
})
```

Note that we use [`defu`](https://github.com/unjs/defu) to extend the public runtime configuration the user provides instead of overwriting it.

You can then access your module options in a plugin, component, the application like any other runtime configuration:

```js
import { useRuntimeConfig } from '@nuxt/kit'

const options = useRuntimeConfig().public.myModule
```

<warning>

Be careful not to expose any sensitive module configuration on the public runtime config, such as private API keys, as they will end up in the public bundle.

</warning>

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/passing-and-exposing-module-options?friend=nuxt">

Watch Vue School video about passing and exposing Nuxt module options.

</tip>

## Add Plugins

Plugins are a common way for a module to add runtime logic. You can use the `addPlugin` utility to register them from your module.

```js
import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    // Create resolver to resolve relative paths
    const resolver = createResolver(import.meta.url)

    addPlugin(resolver.resolve('./runtime/plugin'))
  },
})
```

<read-more to="/docs/4.x/guide/going-further/kit">



</read-more>

## Add Components

If your module should provide Vue components, you can use the `addComponent` utility to add them as auto-imports for Nuxt to resolve.

```tstwoslash
import { addComponent, createResolver, defineNuxtModule, useRuntimeConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // From the runtime directory
    addComponent({
      name: 'MySuperComponent', // name of the component to be used in vue templates
      export: 'MySuperComponent', // (optional) if the component is a named (rather than default) export
      filePath: resolver.resolve('runtime/app/components/MySuperComponent.vue'),
    })

    // From a library
    addComponent({
      name: 'MyAwesomeComponent', // name of the component to be used in vue templates
      export: 'MyAwesomeComponent', // (optional) if the component is a named (rather than default) export
      filePath: '@vue/awesome-components',
    })
  },
})
```

Alternatively, you can add an entire directory by using `addComponentsDir`.

```ts
import { addComponentsDir, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addComponentsDir({
      path: resolver.resolve('runtime/app/components'),
    })
  },
})
```

<tip icon="i-lucide-lightbulb">

It is highly recommended to prefix your exports to avoid conflicts with user code or other modules.

<read-more to="/docs/4.x/guide/modules/best-practices#prefix-your-exports">



</read-more>
</tip>

<note>

Note that all components, pages, composables and other files that would be normally placed in your `app/` folder need to be in `runtime/app/`. This will mean they can be type checked properly.

</note>

## Add Composables

If your module should provide composables, you can use the `addImports` utility to add them as auto-imports for Nuxt to resolve.

```ts
import { addImports, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addImports({
      name: 'useComposable', // name of the composable to be used
      as: 'useMyComposable', // optional alias that will be available for the consuming apps
      from: resolver.resolve('runtime/app/composables/useComposable'), // path of composable
    })
  },
})
```

Multiple entries can be passed as an array:

```ts
import { addImports, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addImports([
      { name: 'useFirstComposable', from: resolver.resolve('runtime/composables/useFirstComposable') },
      { name: 'useSecondComposable', from: resolver.resolve('runtime/composables/useSecondComposable') },
    ])
  },
})
```

Alternatively, you can add an entire directory by using `addImportsDir`.

```ts
import { addImportsDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addImportsDir(resolver.resolve('runtime/composables'))
  },
})
```

<tip icon="i-lucide-lightbulb">

It is highly recommended to prefix your exports to avoid conflicts with user code or other modules.

<read-more to="/docs/4.x/guide/modules/best-practices#prefix-your-exports">



</read-more>
</tip>

<note>

Note that all components, pages, composables and other files that would be normally placed in your `app/` folder need to be in `runtime/app/`. This will mean they can be type checked properly.

</note>

## Add Server Routes

```ts
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addServerHandler({
      route: '/api/_my-module/hello',
      handler: resolver.resolve('./runtime/server/api/hello/index.get'),
    })
  },
})
```

You can also add a dynamic server route:

```ts
import { addServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addServerHandler({
      route: '/api/_my-module/hello/:name',
      handler: resolver.resolve('./runtime/server/api/hello/[name].get'),
    })

    // Or using a catch all route
    addServerHandler({
      route: '/api/_my-module/files/**:path',
      handler: resolver.resolve('./runtime/server/api/files/[...path].get'),
    })
  },
})
```

<tip icon="i-lucide-lightbulb">

It is highly recommended to prefix your server routes to avoid conflicts with user-defined routes. Common paths like `/api/auth`, `/api/login`, or `/api/user` may already be used by the application.

<read-more to="/docs/4.x/guide/modules/best-practices#prefix-your-exports">



</read-more>
</tip>

## Add Other Assets

If your module should provide other kinds of assets, they can also be injected. Here's a simple example module injecting a stylesheet through Nuxt's `css` array.

```js
import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.options.css.push(resolver.resolve('./runtime/style.css'))
  },
})
```

And a more advanced one, exposing a folder of assets through [Nitro](/docs/4.x/guide/concepts/server-engine)'s `publicAssets` option:

```js
import { createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('nitro:config', (nitroConfig) => {
      nitroConfig.publicAssets ||= []
      nitroConfig.publicAssets.push({
        dir: resolver.resolve('./runtime/public'),
        maxAge: 60 * 60 * 24 * 365, // 1 year
      })
    })
  },
})
```

## Use Other Modules

If your module depends on other modules, you can specify them using the `moduleDependencies` option. This provides a more robust way to handle module dependencies with version constraints and configuration merging:

```ts
import { createResolver, defineNuxtModule } from '@nuxt/kit'

const resolver = createResolver(import.meta.url)

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    '@nuxtjs/tailwindcss': {
      // You can specify a version constraint for the module
      version: '>=6',
      // Any configuration that should override `nuxt.options`
      overrides: {
        exposeConfig: true,
      },
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`
      defaults: {
        config: {
          darkMode: 'class',
          content: {
            files: [
              resolver.resolve('./runtime/components/**/*.{vue,mjs,ts}'),
              resolver.resolve('./runtime/*.{mjs,js,ts}'),
            ],
          },
        },
      },
    },
  },
  setup (options, nuxt) {
    // We can inject our CSS file which includes Tailwind's directives
    nuxt.options.css.push(resolver.resolve('./runtime/assets/styles.css'))
  },
})
```

<callout type="info">

The `moduleDependencies` option replaces the deprecated `installModule` function and ensures proper setup order and configuration merging.

</callout>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/refresh-cookie.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/refresh-cookie.md

# refreshCookie

> Refresh useCookie values manually when a cookie has changed

<important>

This utility is available since [Nuxt v3.10](/blog/v3-10).

</important>

## Purpose

The `refreshCookie` function is designed to refresh cookie value returned by `useCookie`.

This is useful for updating the `useCookie` ref when we know the new cookie value has been set in the browser.

## Usage

```vue [app/app.vue]
<script setup lang="ts">
const tokenCookie = useCookie('token')

const login = async (username, password) => {
  const token = await $fetch('/api/token', { /** ... */ }) // Sets `token` cookie on response
  refreshCookie('token')
}

const loggedIn = computed(() => !!tokenCookie.value)
</script>
```

<note to="/docs/4.x/guide/going-further/experimental-features#cookiestore">

Since [Nuxt v3.12.0](https://github.com/nuxt/nuxt/releases/tag/v3.12.0), the experimental `cookieStore` option is enabled by default. It automatically refreshes the `useCookie` value when cookies change in the browser.

</note>

## Type

```ts [Signature]
export function refreshCookie (name: string): void
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/refresh-nuxt-data.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/refresh-nuxt-data.md

# refreshNuxtData

> Refresh all or specific asyncData instances in Nuxt

`refreshNuxtData` is used to refetch all or specific `asyncData` instances, including those from [`useAsyncData`](/docs/4.x/api/composables/use-async-data), [`useLazyAsyncData`](/docs/4.x/api/composables/use-lazy-async-data), [`useFetch`](/docs/4.x/api/composables/use-fetch), and [`useLazyFetch`](/docs/4.x/api/composables/use-lazy-fetch).

<note>

If your component is cached by `<KeepAlive>` and enters a deactivated state, the `asyncData` inside the component will still be refetched until the component is unmounted.

</note>

## Type

```ts [Signature]
export function refreshNuxtData (keys?: string | string[])
```

## Parameters

- `keys`: A single string or an array of strings as `keys` that are used to fetch the data. This parameter is **optional**. All [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch) keys are re-fetched when no `keys` are explicitly specified.

## Return Values

`refreshNuxtData` returns a promise, resolving when all or specific `asyncData` instances have been refreshed.

## Examples

### Refresh All Data

This example below refreshes all data being fetched using `useAsyncData` and `useFetch` in Nuxt application.

```vue [app/pages/some-page.vue]
<script setup lang="ts">
const refreshing = ref(false)

async function refreshAll () {
  refreshing.value = true
  try {
    await refreshNuxtData()
  } finally {
    refreshing.value = false
  }
}
</script>

<template>
  <div>
    <button
      :disabled="refreshing"
      @click="refreshAll"
    >
      Refetch All Data
    </button>
  </div>
</template>
```

### Refresh Specific Data

This example below refreshes only data where the key matches to `count` and `user`.

```vue [app/pages/some-page.vue]
<script setup lang="ts">
const refreshing = ref(false)

async function refresh () {
  refreshing.value = true
  try {
    // you could also pass an array of keys to refresh multiple data
    await refreshNuxtData(['count', 'user'])
  } finally {
    refreshing.value = false
  }
}
</script>

<template>
  <div v-if="refreshing">
    Loading
  </div>
  <button @click="refresh">
    Refresh
  </button>
</template>
```

<note>

If you have access to the `asyncData` instance, it is recommended to use its `refresh` or `execute` method as the preferred way to refetch the data.

</note>

<read-more to="/docs/4.x/getting-started/data-fetching">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/reload-nuxt-app.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/reload-nuxt-app.md

# reloadNuxtApp

> reloadNuxtApp will perform a hard reload of the page.

<note>

`reloadNuxtApp` will perform a hard reload of your app, re-requesting a page and its dependencies from the server.

</note>

By default, it will also save the current `state` of your app (that is, any state you could access with `useState`).

<read-more icon="i-lucide-star" to="/docs/4.x/guide/going-further/experimental-features#restorestate">

You can enable experimental restoration of this state by enabling the `experimental.restoreState` option in your `nuxt.config` file.

</read-more>

## Type

```ts [Signature]
export function reloadNuxtApp (options?: ReloadNuxtAppOptions)

interface ReloadNuxtAppOptions {
  ttl?: number
  force?: boolean
  path?: string
  persistState?: boolean
}
```

### `options` (optional)

**Type**: `ReloadNuxtAppOptions`

An object accepting the following properties:

- `path` (optional)<br />

**Type**: `string`<br />

**Default**: `window.location.pathname`<br />

The path to reload (defaulting to the current path). If this is different from the current window location it
will trigger a navigation and add an entry in the browser history.
- `ttl` (optional)<br />

**Type**: `number`<br />

**Default**: `10000`<br />

The number of milliseconds in which to ignore future reload requests. If called again within this time period,
`reloadNuxtApp` will not reload your app to avoid reload loops.
- `force` (optional)<br />

**Type**: `boolean`<br />

**Default**: `false`<br />

This option allows bypassing reload loop protection entirely, forcing a reload even if one has occurred within
the previously specified TTL.
- `persistState` (optional)<br />

**Type**: `boolean`<br />

**Default**: `false`<br />

Whether to dump the current Nuxt state to sessionStorage (as `nuxt:reload:state`). By default this will have no
effect on reload unless `experimental.restoreState` is also set, or unless you handle restoring the state yourself.

---

# Source: https://nuxt.com/raw/deploy/render.md

# Render

> Deploy your Nuxt Application to Render infrastructure.

Nuxt supports deploying on [Render](https://render.com/) with minimal configuration.

## Set up application

1. [Create a new Web Service](https://dashboard.render.com/select-repo?type=web) and select the repository that contains your code.
2. Ensure the 'Node' environment is selected.
3. Depending on your package manager, set the build command to `yarn && yarn build`, `npm install && npm run build`, or `pnpm i --shamefully-hoist && pnpm build`.
4. Update the start command to `node .output/server/index.mjs`
5. Click 'Advanced' and add the following environment variables
```bash
SERVER_PRESET=render_com
NODE_VERSION=20
```
6. Click on `Create Web Service`.

## More options

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/render">

Head over **Nitro documentation** to learn more about the Render deployment presets.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/rendering.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/rendering.md

# Rendering Modes

> Learn about the different rendering modes available in Nuxt.

Nuxt supports different rendering modes, [universal rendering](/docs/4.x/guide/concepts/rendering#universal-rendering), [client-side rendering](/docs/4.x/guide/concepts/rendering#client-side-rendering) but also offers [hybrid-rendering](/docs/4.x/guide/concepts/rendering#hybrid-rendering) and the possibility to render your application on [CDN Edge Servers](/docs/4.x/guide/concepts/rendering#edge-side-rendering).

Both the browser and server can interpret JavaScript code to turn Vue.js components into HTML elements. This step is called **rendering**. Nuxt supports both **universal** and **client-side** rendering. The two approaches have benefits and downsides that we will cover.

By default, Nuxt uses **universal rendering** to provide better user experience, performance and to optimize search engine indexing, but you can switch rendering modes in [one line of configuration](/docs/4.x/api/nuxt-config#ssr).

## Universal Rendering

This step is similar to traditional **server-side rendering** performed by PHP or Ruby applications. When the browser requests a URL with universal rendering enabled, Nuxt runs the JavaScript (Vue.js) code in a server environment and returns a fully rendered HTML page to the browser. Nuxt may also return a fully rendered HTML page from a cache if the page was generated in advance. Users immediately get the entirety of the initial content of the application, contrary to client-side rendering.

Once the HTML document has been downloaded, the browser interprets this and Vue.js takes control of the document. The same JavaScript code that once ran on the server runs on the client (browser) **again** in the background now enabling interactivity (hence **Universal rendering**) by binding its listeners to the HTML. This is called **Hydration**. When hydration is complete, the page can enjoy benefits such as dynamic interfaces and page transitions.

Universal rendering allows a Nuxt application to provide quick page load times while preserving the benefits of client-side rendering. Furthermore, as the content is already present in the HTML document, crawlers can index it without overhead.

![Users can access the static content when the HTML document is loaded. Hydration then allows page's interactivity](/assets/docs/concepts/rendering/ssr.svg)

**What's server-rendered and what's client-rendered?**

It is normal to ask which parts of a Vue file runs on the server and/or the client in universal rendering mode.

```vue [app/app.vue]
<script setup lang="ts">
const counter = ref(0) // executes in server and client environments

const handleClick = () => {
  counter.value++ // executes only in a client environment
}
</script>

<template>
  <div>
    <p>Count: {{ counter }}</p>
    <button @click="handleClick">
      Increment
    </button>
  </div>
</template>
```

On the initial request, the `counter` ref is initialized in the server since it is rendered inside the `<p>` tag. The contents of `handleClick` is never executed here. During hydration in the browser, the `counter` ref is re-initialized. The `handleClick` finally binds itself to the button; Therefore it is reasonable to deduce that the body of `handleClick` will always run in a browser environment.

[Middlewares](/docs/4.x/directory-structure/app/middleware) and [pages](/docs/4.x/directory-structure/app/pages) run in the server and on the client during hydration. [Plugins](/docs/4.x/directory-structure/app/plugins) can be rendered on the server or client or both. [Components](/docs/4.x/directory-structure/app/components) can be forced to run on the client only as well. [Composables](/docs/4.x/directory-structure/app/composables) and [utilities](/docs/4.x/directory-structure/app/utils) are rendered based on the context of their usage.

**Benefits of server-side rendering:**

- **Performance**: Users can get immediate access to the page's content because browsers can display static content much faster than JavaScript-generated content. At the same time, Nuxt preserves the interactivity of a web application during the hydration process.
- **Search Engine Optimization**: Universal rendering delivers the entire HTML content of the page to the browser as a classic server application. Web crawlers can directly index the page's content, which makes Universal rendering a great choice for any content that you want to index quickly.

**Downsides of server-side rendering:**

- **Development constraints:** Server and browser environments don't provide the same APIs, and it can be tricky to write code that can run on both sides seamlessly. Fortunately, Nuxt provides guidelines and specific variables to help you determine where a piece of code is executed.
- **Cost:** A server needs to be running in order to render pages on the fly. This adds a monthly cost like any traditional server. However, the server calls are highly reduced thanks to universal rendering with the browser taking over on client-side navigation. A cost reduction is possible by leveraging [edge-side-rendering](/docs/4.x/guide/concepts/rendering#edge-side-rendering).

Universal rendering is very versatile and can fit almost any use case, and is especially appropriate for any content-oriented websites: **blogs, marketing websites, portfolios, e-commerce sites, and marketplaces.**

<tip>

For more examples about writing Vue code without hydration mismatch, see [the Vue docs](https://vuejs.org/guide/scaling-up/ssr#hydration-mismatch).

</tip>

<important>

When importing a library that relies on browser APIs and has side effects, make sure the component importing it is only called client-side. Bundlers do not treeshake imports of modules containing side effects.

</important>

## Client-Side Rendering

Out of the box, a traditional Vue.js application is rendered in the browser (or **client**). Then, Vue.js generates HTML elements after the browser downloads and parses all the JavaScript code containing the instructions to create the current interface.

![Users have to wait for the browser to download, parse and execute the JavaScript before seeing the page's content](/assets/docs/concepts/rendering/csr.svg)

**Benefits of client-side rendering:**

- **Development speed**: When working entirely on the client-side, we don't have to worry about the server compatibility of the code, for example, by using browser-only APIs like the `window` object.
- **Cheaper:** Running a server adds a cost of infrastructure as you would need to run on a platform that supports JavaScript. We can host client-only applications on any static server with HTML, CSS, and JavaScript files.
- **Offline:** Because code entirely runs in the browser, it can nicely keep working while the internet is unavailable.

**Downsides of client-side rendering:**

- **Performance**: The user has to wait for the browser to download, parse and run JavaScript files. Depending on the network for the download part and the user's device for the parsing and execution, this can take some time and impact the user's experience.
- **Search Engine Optimization**: Indexing and updating the content delivered via client-side rendering takes more time than with a server-rendered HTML document. This is related to the performance drawback we discussed, as search engine crawlers won't wait for the interface to be fully rendered on their first try to index the page. Your content will take more time to show and update in search results pages with pure client-side rendering.

Client-side rendering is a good choice for heavily interactive **web applications** that don't need indexing or whose users visit frequently. It can leverage browser caching to skip the download phase on subsequent visits, such as **SaaS, back-office applications, or online games**.

You can enable client-side only rendering with Nuxt in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ssr: false,
})
```

<note>

If you do use `ssr: false`, you should also place an HTML file in `~/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated.

<read-more title="SPA Loading Template" to="/docs/4.x/api/configuration/nuxt-config#spaloadingtemplate">



</read-more>
</note>

<video-accordion title="Watch a video from Alexander Lichter about Building a plain SPA with Nuxt" video-id="7Lr0QTP1Ro8">



</video-accordion>

### Deploying a Static Client-Rendered App

If you deploy your app to [static hosting](/docs/4.x/getting-started/deployment#static-hosting) with the `nuxt generate` or `nuxt build --prerender` commands, then by default, Nuxt will render every page as a separate static HTML file.

<warning>

If you prerender your app with the `nuxt generate` or `nuxt build --prerender` commands, then you will not be able to use any server endpoints as no server will be included in your output folder. If you need server functionality, use `nuxt build` instead.

</warning>

If you are using purely client-side rendering, then this might be unnecessary. You might only need a single `index.html` file, plus `200.html` and `404.html` fallbacks, which you can tell your static web host to serve up for all requests.

In order to achieve this we can change how the routes are prerendered. Just add this to [your hooks](/docs/4.x/api/advanced/hooks#nuxt-hooks-build-time) in your `nuxt.config.ts`:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  hooks: {
    'prerender:routes' ({ routes }) {
      routes.clear() // Do not generate any routes (except the defaults)
    },
  },
})
```

This will produce three files:

- `index.html`
- `200.html`
- `404.html`

The `200.html` and `404.html` might be useful for the hosting provider you are using.

#### Skipping Client Fallback Generation

When prerendering a client-rendered app, Nuxt will generate `index.html`, `200.html` and `404.html` files by default. However, if you need to prevent any (or all) of these files from being generated in your build, you can use the `'prerender:generate'` hook from [Nitro](/docs/4.x/getting-started/prerendering#prerendergenerate-nitro-hook).

```ts [nuxt.config.ts]twoslash
// @errors: 2353 7006
export default defineNuxtConfig({
  ssr: false,
  nitro: {
    hooks: {
      'prerender:generate' (route) {
        const routesToSkip = ['/index.html', '/200.html', '/404.html']
        if (routesToSkip.includes(route.route)) {
          route.skip = true
        }
      },
    },
  },
})
```

## Hybrid Rendering

Hybrid rendering allows different caching rules per route using **Route Rules** and decides how the server should respond to a new request on a given URL.

Previously every route/page of a Nuxt application and server must use the same rendering mode, universal or client-side. In various cases, some pages could be generated at build time, while others should be client-side rendered. For example, think of a content website with an admin section. Every content page should be primarily static and generated once, but the admin section requires registration and behaves more like a dynamic application.

Nuxt includes route rules and hybrid rendering support. Using route rules you can define rules for a group of nuxt routes, change rendering mode or assign a cache strategy based on route!

Nuxt server will automatically register corresponding middleware and wrap routes with cache handlers using [Nitro caching layer](https://nitro.build/guide/cache).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  routeRules: {
    // Homepage pre-rendered at build time
    '/': { prerender: true },
    // Products page generated on demand, revalidates in background, cached until API response changes
    '/products': { swr: true },
    // Product pages generated on demand, revalidates in background, cached for 1 hour (3600 seconds)
    '/products/**': { swr: 3600 },
    // Blog posts page generated on demand, revalidates in background, cached on CDN for 1 hour (3600 seconds)
    '/blog': { isr: 3600 },
    // Blog post page generated on demand once until next deployment, cached on CDN
    '/blog/**': { isr: true },
    // Admin dashboard renders only on client-side
    '/admin/**': { ssr: false },
    // Add cors headers on API routes
    '/api/**': { cors: true },
    // Redirects legacy urls
    '/old-page': { redirect: '/new-page' },
  },
})
```

### Route Rules

The different properties you can use are the following:

- `redirect: string` - Define server-side redirects.
- `ssr: boolean` - Disables server-side rendering of the HTML for sections of your app and make them render only in the browser with `ssr: false`
- `cors: boolean` - Automatically adds cors headers with `cors: true` - you can customize the output by overriding with `headers`
- `headers: object` - Add specific headers to sections of your site - for example, your assets
- `swr: number | boolean` - Add cache headers to the server response and cache it on the server or reverse proxy for a configurable TTL (time to live). The `node-server` preset of Nitro is able to cache the full response. When the TTL expired, the cached response will be sent while the page will be regenerated in the background. If true is used, a `stale-while-revalidate` header is added without a MaxAge.
- `isr: number | boolean` - The behavior is the same as `swr` except that we are able to add the response to the CDN cache on platforms that support this (currently Netlify or Vercel). If `true` is used, the content persists until the next deploy inside the CDN.
- `prerender: boolean` - Prerenders routes at build time and includes them in your build as static assets
- `noScripts: boolean` - Disables rendering of Nuxt scripts and JS resource hints for sections of your site.
- `appMiddleware: string | string[] | Record<string, boolean>` - Allows you to define middleware that should or should not run for page paths within the Vue app part of your application (that is, not your Nitro routes)

<note>

Routes using `isr` or `swr` also generate `_payload.json` files alongside HTML. Client-side navigation loads these cached payloads instead of re-fetching data. Configure dynamic routes like `pages/[...slug].vue` with glob patterns: `'/**': { isr: true }`.

</note>

Whenever possible, route rules will be automatically applied to the deployment platform's native rules for optimal performances (Netlify and Vercel are currently supported).

<important>

Note that Hybrid Rendering is not available when using [`nuxt generate`](/docs/4.x/api/commands/generate).

</important>

**Examples:**

<card-group>
<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Nuxt Vercel ISR" to="https://github.com/danielroe/nuxt-vercel-isr">

Example of a Nuxt application with hybrid rendering deployed on Vercel.

</card>
</card-group>

## Edge-Side Rendering

Edge-Side Rendering (ESR) is a powerful feature introduced in Nuxt that allows the rendering of your Nuxt application closer to your users via edge servers of a Content Delivery Network (CDN). By leveraging ESR, you can ensure improved performance and reduced latency, thereby providing an enhanced user experience.

With ESR, the rendering process is pushed to the 'edge' of the network - the CDN's edge servers. Note that ESR is more a deployment target than an actual rendering mode.

When a request for a page is made, instead of going all the way to the original server, it's intercepted by the nearest edge server. This server generates the HTML for the page and sends it back to the user. This process minimizes the physical distance the data has to travel, **reducing latency and loading the page faster**.

Edge-side rendering is possible thanks to [Nitro](https://nitro.build/), the [server engine](/docs/4.x/guide/concepts/server-engine) that powers Nuxt. It offers cross-platform support for Node.js, Deno, Cloudflare Workers, and more.

The current platforms where you can leverage ESR are:

- [Cloudflare Pages](https://pages.cloudflare.com) with zero configuration using the git integration and the `nuxt build` command
- [Vercel Cloud](https://vercel.com/home) using the `nuxt build` command and `NITRO_PRESET=vercel-edge` environment variable
- [Netlify Edge Functions](https://www.netlify.com/platform/#netlify-edge-functions) using the `nuxt build` command and `NITRO_PRESET=netlify-edge` environment variable

Note that **Hybrid Rendering** can be used when using Edge-Side Rendering with route rules.

---

# Source: https://nuxt.com/raw/docs/3.x/community/reporting-bugs.md

# Source: https://nuxt.com/raw/docs/4.x/community/reporting-bugs.md

# Reporting Bugs

> One of the most valuable roles in open source is taking the time to report bugs helpfully.

Try as we might, we will never completely eliminate bugs.

Even if you can't fix the underlying code, reporting a bug well can enable someone else with a bit more familiarity with the codebase to spot a pattern or make a quick fix.

Here are a few key steps.

## Is It Really a Bug?

Consider if you're looking to get help with something, or whether you think there's a bug with Nuxt itself. If it's the former, we'd love to help you - but the best way to do that is through [asking for help](/docs/4.x/community/getting-help) rather than reporting a bug.

## Search the Issues

Search through the [open issues](https://github.com/nuxt/nuxt/issues) and [discussions](https://github.com/nuxt/nuxt/discussions) first. If you find anything that seems like the same bug, it's much better to comment on an existing thread than create a duplicate.

## Create a Minimal Reproduction

It's important to be able to reproduce the bug reliably - in a minimal way and apart from the rest of your project. This narrows down what could be causing the issue and makes it possible for someone not only to find the cause, but also to test a potential solution.

Start with the Nuxt sandbox and add the **minimum** amount of code necessary to reproduce the bug you're experiencing.

<note>

If your issue concerns Vue or Vite, please try to reproduce it first with the Vue SSR starter.

</note>

**Nuxt**:

<card-group>
<card icon="i-simple-icons-stackblitz" target="_blank" title="Nuxt on StackBlitz" to="https://nuxt.new/s/v4">



</card>

<card icon="i-simple-icons-codesandbox" target="_blank" title="Nuxt on CodeSandbox" to="https://nuxt.new/c/v4">



</card>
</card-group>

**Vue**:

<card-group>
<card icon="i-simple-icons-stackblitz" target="_blank" title="Vue SSR on StackBlitz" to="https://stackblitz.com/github/nuxt-contrib/vue3-ssr-starter/tree/main?terminal=dev">



</card>

<card icon="i-simple-icons-codesandbox" target="_blank" title="Vue SSR on CodeSandbox" to="https://codesandbox.io/p/sandbox/github/nuxt-contrib/vue3-ssr-starter/main">



</card>

<card icon="i-simple-icons-github" target="_blank" title="Vue SSR Template on GitHub" to="https://github.com/nuxt-contrib/vue3-ssr-starter/generate">



</card>
</card-group>

Once you've reproduced the issue, remove as much code from your reproduction as you can (while still recreating the bug). The time spent making the reproduction as minimal as possible will make a huge difference to whoever sets out to fix the issue.

## Figure Out What the Cause Might Be

With a Nuxt project, there are lots of moving pieces - from [Nuxt modules](/modules) to [other JavaScript libraries](https://www.npmjs.com). Try to report the bug at the most relevant and specific place. That will likely be the Nuxt module causing an issue, or the upstream library that Nuxt is depending on.

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/resolving.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/resolving.md

# Resolving

> Nuxt Kit provides a set of utilities to help you resolve paths. These functions allow you to resolve paths relative to the current module, with unknown name or extension.

Sometimes you need to resolve a paths: relative to the current module, with unknown name or extension. For example, you may want to add a plugin that is located in the same directory as the module. To handle this cases, nuxt provides a set of utilities to resolve paths. `resolvePath` and `resolveAlias` are used to resolve paths relative to the current module. `findPath` is used to find first existing file in given paths. `createResolver` is used to create resolver relative to base path.

## `resolvePath`

Resolves full path to a file or directory respecting Nuxt alias and extensions options. If path could not be resolved, normalized input path will be returned.

### Usage

```ts
import { defineNuxtModule, resolvePath } from '@nuxt/kit'

export default defineNuxtModule({
  async setup () {
    const entrypoint = await resolvePath('@unhead/vue')
    console.log(`Unhead entrypoint is ${entrypoint}`)
  },
})
```

### Type

```ts
function resolvePath (path: string, options?: ResolvePathOptions): Promise<string>
```

### Parameters

**path**: A path to resolve.

**options**: Options to pass to the resolver. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        cwd
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Base for resolving paths from. Default is Nuxt rootDir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        alias
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Record
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      An object of aliases. Default is Nuxt configured aliases.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        extensions
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      The file extensions to try. Default is Nuxt configured extensions.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        virtual
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Whether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fallbackToOriginal
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Whether to fallback to the original path if the resolved path does not exist instead of returning the normalized input path.
    </td>
  </tr>
</tbody>
</table>

### Examples

```ts
import { defineNuxtModule, resolvePath } from '@nuxt/kit'
import { join } from 'pathe'

const headlessComponents: ComponentGroup[] = [
  {
    relativePath: 'combobox/combobox.js',
    chunkName: 'headlessui/combobox',
    exports: [
      'Combobox',
      'ComboboxLabel',
      'ComboboxButton',
      'ComboboxInput',
      'ComboboxOptions',
      'ComboboxOption',
    ],
  },
]

export default defineNuxtModule({
  meta: {
    name: 'nuxt-headlessui',
    configKey: 'headlessui',
  },
  defaults: {
    prefix: 'Headless',
  },
  async setup (options) {
    const entrypoint = await resolvePath('@headlessui/vue')
    const root = join(entrypoint, '../components')

    for (const group of headlessComponents) {
      for (const e of group.exports) {
        addComponent(
          {
            name: e,
            export: e,
            filePath: join(root, group.relativePath),
            chunkName: group.chunkName,
            mode: 'all',
          },
        )
      }
    }
  },
})
```

## `resolveAlias`

Resolves path aliases respecting Nuxt alias options.

### Type

```ts
function resolveAlias (path: string, alias?: Record<string, string>): string
```

### Parameters

**path**: A path to resolve.

**alias**: An object of aliases. If not provided, it will be read from `nuxt.options.alias`.

## `findPath`

Try to resolve first existing file in given paths.

### Usage

```ts
import { defineNuxtModule, findPath } from '@nuxt/kit'
import { join } from 'pathe'

export default defineNuxtModule({
  async setup (_, nuxt) {
    // Resolve main (app.vue)
    const mainComponent = await findPath([
      join(nuxt.options.srcDir, 'App'),
      join(nuxt.options.srcDir, 'app'),
    ])
  },
})
```

### Type

```ts
function findPath (paths: string | string[], options?: ResolvePathOptions, pathType: 'file' | 'dir'): Promise<string | null>
```

### Parameters

**paths**: A path or an array of paths to resolve.

**options**: Options to pass to the resolver. This object can have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        cwd
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Base for resolving paths from. Default is Nuxt rootDir.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        alias
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sZSNi">
          Record
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      An object of aliases. Default is Nuxt configured aliases.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        extensions
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      The file extensions to try. Default is Nuxt configured extensions.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        virtual
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Whether to resolve files that exist in the Nuxt VFS (for example, as a Nuxt template).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fallbackToOriginal
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Whether to fallback to the original path if the resolved path does not exist instead of returning the normalized input path.
    </td>
  </tr>
</tbody>
</table>

## `createResolver`

Creates resolver relative to base path.

<tip icon="i-lucide-video" target="_blank" to="https://vueschool.io/lessons/resolving-paths-and-injecting-assets-to-the-app?friend=nuxt">

Watch Vue School video about createResolver.

</tip>

### Usage

```ts
import { createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (_, nuxt) {
    const { resolve, resolvePath } = createResolver(import.meta.url)
  },
})
```

### Type

```ts
function createResolver (basePath: string | URL): Resolver
```

### Parameters

**basePath**: A base path to resolve from. It can be a string or a URL.

### Return Value

The `createResolver` function returns an object with the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        resolve
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          path
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          string
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          string
        </span>
      </code>
    </td>
    
    <td>
      A function that resolves a path relative to the base path.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resolvePath
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          path
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          string
        </span>
        
        <span class="sDfIl">
          ,
        </span>
        
        <span class="s1nJG">
          options
        </span>
        
        <span class="sDfIl">
          ?:
        </span>
        
        <span class="s52Pk">
          ResolvePathOptions
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="s52Pk">
          Promise
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      A function that resolves a path relative to the base path and respects Nuxt alias and extensions options.
    </td>
  </tr>
</tbody>
</table>

### Examples

```ts
import { createResolver, defineNuxtModule, isNuxt2 } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    nuxt.hook('modules:done', () => {
      if (isNuxt2()) {
        addPlugin(resolver.resolve('./runtime/plugin.vue2'))
      } else {
        addPlugin(resolver.resolve('./runtime/plugin.vue3'))
      }
    })
  },
})
```

---

# Source: https://nuxt.com/raw/blog/roadmap-v4.md

# Roadmap to v4

> We have some exciting news about the roadmap to Nuxt 4, including a new timeline and what to expect in the next few weeks.

We originally planned Nuxt 4 for June 2024, but things don't always go according to plan. I think it's appropriate to take a different approach:

👉 **Nuxt 4 entered Release Candidate (RC) stage on July 8, 2025, with a stable release coming soon. Nuxt 5 will come later once Nitro v3 is ready.**

## Why Two Releases?

Honestly, in hindsight I think we should have shipped Nuxt v4 last year. It would have aligned better with our once-a-year plan for careful major releases.

On the other hand, it has allowed time for testing across countless projects, by opting in to Nuxt 4 breaking changes with a single flag. I think that we should go ahead and ship these changes as Nuxt v4 for two reasons:

1. **People are already using it**. I frequently hear of teams who are using `compatibilityVersion: 4` in production. This option was *intended* only for testing, but it has proven solid enough for production use. We want to make it official, and give these teams the protection of a stable release.
2. **It will improve the migration**. Having a two-stage migration from v3 -> v4, and then v4 -> v5 will make for a smoother migration. We don't yet have a final list of breaking changes for Nitro v3, and this means we can spend enough time to ensure that the Nitro upgrade is smooth, while not delaying adoption of the Nuxt changes we've planned for the last year.

What's more, going forward we're going to do our best to decouple Nuxt releases from our key dependencies, like Vite or Nitro.

## What's Included?

Nuxt 4 includes all the features you've been testing with `compatibilityVersion: 4`:

- **🗂️ New Directory Structure** - code goes in `app/` for cleaner organization and better IDE performance
- **🔄 Improved Data Fetching** - smarter `useAsyncData` and `useFetch` with better caching and cleanup
- **🏷️ Consistent Component Names** - Vue DevTools and `<KeepAlive>` now see the same names as Nuxt's auto-imports
- **📄 Enhanced Head Management** - dropping deprecated features from Unhead v2 with better performance and tag optimization

... as well as many other improvements documented in the [upgrade guide](/docs/getting-started/upgrade). There are also a handful of further changes we will shipping, including:

- preparations for adopting the Vite Environment API (with a single dev server)
- improvements to type 'environment' handling (for server, client, and shared code)

## What About Nitro?

**We're not delaying Nitro v3 adoption**. We aim for Nuxt 5 to arrive with Nitro v3 at the same time we originally planned, even if that's only a few months after the release of Nuxt v4.

Despite the delays over the past year, we've seen phenomenal progress on Nitro. As a whole team, we're very excited to unveil what we have planned in Nitro v3 and h3 v2.

While Nuxt 4 won't initially include these upgrades, releasing Nuxt v4 and Nitro v3 in parallel will mean we can test both Nuxt and Nitro more thoroughly across the ecosystem by the time Nuxt 5 arrives.

## What About Nuxt 3?

We'll provide ongoing maintenance and support for Nuxt 3 after the first stable release of Nuxt 4 — and continue supporting both Nuxt 3 and Nuxt 4 after Nuxt 5 has been released. We've intentionally chosen a slightly shorter timetable of *six months* support for each of these releases because we believe that it will be a straightforward upgrade.

(My main aim for the Nuxt 4 upgrade is to ensure that it is as smooth as possible.)

Nevertheless, I'll be closely monitoring to see how successfully and quickly the ecosystem migrates. If there are issues I will absolutely extend that six month ongoing maintenance window. We don't want to leave anyone behind.

For a while, this will mean active backports of features and bugfixes across three versions. But I think it's worth it. And we have — after all — been doing this for the last year in preparation for Nuxt 4.

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Nuxt 3
      </strong>
    </td>
    
    <td>
      Continues receiving updates until the end of 2025
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Nuxt 4
      </strong>
    </td>
    
    <td>
      Supported until mid-2026 (estimated)
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Nuxt 5
      </strong>
    </td>
    
    <td>
      Long-term support following our usual pattern
    </td>
  </tr>
</tbody>
</table>

## What's Next

Nuxt v4 is now in **Release Candidate (RC)** stage! We'd love early adopters to test it. Please do report issues to Nuxt or any modules that you may be using.

<note>

We are currently in the **release candidate stage**: no more breaking changes are planned — only bug fixes before the stable release.

Release stages for Nuxt 4:

- **Alpha**: experimental features and breaking changes
- **RC (now)**: stable feature set, final testing before release

</note>

Here's what you can expect over the next few weeks:

- We plan to open **upstream PRs for community modules** in the [nuxt/modules](https://github.com/nuxt/modules) registry, and create a migration guide for module authors.
- We'll create a full **upgrade guide** for Nuxt 3 users, including a list of breaking changes and how to migrate. (The current [upgrade guide](/docs/getting-started/upgrade) explains how to enable compatibility mode, but there are some differences with Nuxt 4.)
- We'll **only release bugfixes for v3** this month, deferring backporting new features until after the release of v4.
- We'll **update the docs on nuxt.com** to allow switching between `3.x`, `4.x` and (soon) `5.x` documentation.
- With the **release candidate now live**, we're focused exclusively on bug fixes. No new features or breaking changes are expected.
- Once v4 is released, we'll separate the `main` branch to `4.x` to adopt edge releases of `h3` and `nitro` and begin development of Nuxt 5.

<note>

You can follow the progress of the remaining work by checking [these remaining tasks](https://github.com/nuxt/nuxt/issues/27027) and [the Nuxt 4 milestone](https://github.com/nuxt/nuxt/milestone/8) on GitHub.

</note>

I'm really excited with this timeline — and thank you for your patience and trust over the last year!

---

# Source: https://nuxt.com/raw/docs/3.x/community/roadmap.md

# Source: https://nuxt.com/raw/docs/4.x/community/roadmap.md

# Roadmap

> Nuxt is constantly evolving, with new features and modules being added all the time.

<read-more to="/blog">

See our blog for the latest framework and ecosystem announcements.

</read-more>

## Status Reports

<read-more to="https://github.com/nuxt/nuxt/issues/13653" icon="i-simple-icons-github" target="_blank">

Documentation Progress

</read-more>

<read-more to="https://github.com/nuxt/nuxt/discussions/16119" icon="i-simple-icons-github" target="_blank">

Rendering Optimizations: Today and Tomorrow

</read-more>

<read-more to="https://github.com/nuxt/image/discussions/563" icon="i-simple-icons-github" target="_blank">

Nuxt Image: Performance and Status

</read-more>

## Roadmap

In roadmap below are some features we are planning or working on at the moment.

<tip>

Check [Discussions](https://github.com/nuxt/nuxt/discussions) and [RFCs](https://github.com/nuxt/nuxt/discussions/categories/rfcs) for more upcoming features and ideas.

</tip>

<table>
<thead>
  <tr>
    <th>
      Milestone
    </th>
    
    <th>
      Expected date
    </th>
    
    <th>
      Notes
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      SEO & PWA
    </td>
    
    <td>
      2025
    </td>
    
    <td>
      <a href="https://github.com/nuxt/nuxt/discussions/18395" rel="nofollow">
        nuxt/nuxt#18395
      </a>
    </td>
    
    <td>
      Migrating from <a href="https://github.com/nuxt-community/pwa-module" rel="nofollow">
        nuxt-community/pwa-module
      </a>
      
       for built-in SEO utils and service worker support
    </td>
  </tr>
  
  <tr>
    <td>
      Assets
    </td>
    
    <td>
      2025
    </td>
    
    <td>
      <a href="https://github.com/nuxt/nuxt/discussions/22012" rel="nofollow">
        nuxt/nuxt#22012
      </a>
    </td>
    
    <td>
      Allow developers and modules to handle loading third-party assets.
    </td>
  </tr>
  
  <tr>
    <td>
      Translations
    </td>
    
    <td>
      -
    </td>
    
    <td>
      <a href="https://github.com/nuxt/nuxt.com/issues/1711" rel="nofollow">
        nuxt/nuxt.com#1711
      </a>
    </td>
    
    <td>
      A collaborative project for a stable translation process for Nuxt docs. Currently pending for ideas and documentation tooling support.
    </td>
  </tr>
</tbody>
</table>

## Core Modules Roadmap

In addition to the Nuxt framework, there are modules that are vital for the ecosystem. Their status will be updated below.

<table>
<thead>
  <tr>
    <th>
      Module
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Nuxt Support
    </th>
    
    <th>
      Repository
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://scripts.nuxt.com" rel="nofollow">
        Scripts
      </a>
    </td>
    
    <td>
      Public Beta
    </td>
    
    <td>
      3.x, 4.x
    </td>
    
    <td>
      <a href="https://github.com/nuxt/scripts" rel="nofollow">
        nuxt/scripts
      </a>
    </td>
    
    <td>
      Easy 3rd party script management.
    </td>
  </tr>
  
  <tr>
    <td>
      Auth Utils
    </td>
    
    <td>
      Planned
    </td>
    
    <td>
      4.x, 5.x
    </td>
    
    <td>
      <code>
        nuxt/auth-utils
      </code>
      
       to be announced
    </td>
    
    <td>
      The temporary repository <a href="https://github.com/atinux/nuxt-auth-utils" rel="nofollow">
        atinux/nuxt-auth-utils
      </a>
      
       is available while awaiting its official integration into Nuxt via RFC.
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://github.com/nuxt/a11y" rel="nofollow">
        a11y
      </a>
    </td>
    
    <td>
      Public Alpha
    </td>
    
    <td>
      3.x, 4.x
    </td>
    
    <td>
      <a href="https://github.com/nuxt/a11y" rel="nofollow">
        nuxt/a11y
      </a>
      
      .
    </td>
    
    <td>
      Real-time accessibility feedback and automated testing in your browser during development (see <a href="https://github.com/nuxt/nuxt/issues/23255" rel="nofollow">
        nuxt/nuxt#23255
      </a>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://github.com/nuxt/hints" rel="nofollow">
        Hints
      </a>
    </td>
    
    <td>
      Public Alpha
    </td>
    
    <td>
      4.x, 5.x
    </td>
    
    <td>
      <a href="https://github.com/nuxt/hints" rel="nofollow">
        nuxt/hints
      </a>
    </td>
    
    <td>
      Guidance and suggestions for enhancing development practices.
    </td>
  </tr>
</tbody>
</table>

## Release Cycle

Since January 2023, we've adopted a consistent release cycle for Nuxt, following [semver](https://semver.org). We aim for major framework releases every year, with an expectation of patch releases every week or so and minor releases every month or so. They should never contain breaking changes except within options clearly marked as `experimental`.

We are planning a slight variation from this plan for Nuxt 4 and Nuxt 5. Nuxt 4 will be a stability-focused release containing all `compatibilityVersion: 4` features, and will be followed shortly by Nuxt 5 which will include an upgrade to Nitro v3 and additional changes.

This approach separates breaking changes into manageable phases, allowing for better ecosystem testing and smoother migrations.

### Ongoing Support for Nuxt

We commit to support each major version of Nuxt for a minimum of six months after the release of the next major version, and to providing an upgrade path for current users at that point.

### Current Packages

The current active version of [Nuxt](https://nuxt.com) is **v4** which is available as `nuxt` on npm with the `latest` tag.

Nuxt 3 will continue to receive maintenance updates (bug fixes and security patches) until the end of July 2026.

Each active version has its own nightly releases which are generated automatically. For more about enabling the Nuxt nightly release channel, see [the nightly release channel docs](/docs/4.x/guide/going-further/nightly-release-channel).

<table>
<thead>
  <tr>
    <th>
      Release
    </th>
    
    <th>
      
    </th>
    
    <th>
      Initial release
    </th>
    
    <th>
      End Of Life
    </th>
    
    <th>
      Docs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        5.x
      </strong>
      
       (scheduled)
    </td>
    
    <td>
      
    </td>
    
    <td>
      Q1 2026 (estimated)
    </td>
    
    <td>
      TBA
    </td>
    
    <td>
      
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        4.x
      </strong>
      
       (stable)
    </td>
    
    <td>
      <a href="https://www.npmjs.com/package/nuxt?activeTab=versions">
        <img alt="Nuxt latest version" src="https://img.shields.io/npm/v/nuxt.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" className="not-prose,h-5,w-auto" :zoom="false" />
      </a>
    </td>
    
    <td>
      2025-07-16
    </td>
    
    <td>
      6 months after 5.x release
    </td>
    
    <td>
      <a href="/docs/4.x/getting-started/introduction">
        nuxt.com
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        3.x
      </strong>
      
       (maintenance)
    </td>
    
    <td>
      <a href="https://www.npmjs.com/package/nuxt?activeTab=versions">
        <img alt="Nuxt 3.x version" src="https://img.shields.io/npm/v/nuxt/3x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" className="not-prose,h-5,w-auto" :zoom="false" />
      </a>
    </td>
    
    <td>
      2022-11-16
    </td>
    
    <td>
      2026-07-31
    </td>
    
    <td>
      <a href="/docs/3.x/getting-started/introduction">
        nuxt.com
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        2.x
      </strong>
      
       (unsupported)
    </td>
    
    <td>
      <a href="https://www.npmjs.com/package/nuxt?activeTab=versions">
        <img alt="Nuxt 2.x version" src="https://img.shields.io/npm/v/nuxt/2x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" className="not-prose,h-5,w-auto" :zoom="false" />
      </a>
    </td>
    
    <td>
      2018-09-21
    </td>
    
    <td>
      2024-06-30
    </td>
    
    <td>
      <a href="https://v2.nuxt.com/docs/get-started/installation/" rel="nofollow">
        v2.nuxt.com
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        1.x
      </strong>
      
       (unsupported)
    </td>
    
    <td>
      <a href="https://www.npmjs.com/package/nuxt?activeTab=versions">
        <img alt="Nuxt 1.x version" src="https://img.shields.io/npm/v/nuxt/1x.svg?logo=nuxt&label=&style=flat&colorA=18181B&colorB=28CF8D" className="not-prose,h-5,w-auto" :zoom="false" />
      </a>
    </td>
    
    <td>
      2018-01-08
    </td>
    
    <td>
      2019-09-21
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

### Support Status

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Unsupported
    </td>
    
    <td>
      This version is not maintained any more and will not receive security patches
    </td>
  </tr>
  
  <tr>
    <td>
      Maintenance
    </td>
    
    <td>
      This version will only receive security patches
    </td>
  </tr>
  
  <tr>
    <td>
      Stable
    </td>
    
    <td>
      This version is being developed for and will receive security patches
    </td>
  </tr>
  
  <tr>
    <td>
      Development
    </td>
    
    <td>
      This version could be unstable
    </td>
  </tr>
  
  <tr>
    <td>
      Scheduled
    </td>
    
    <td>
      This version does not exist yet but is planned
    </td>
  </tr>
</tbody>
</table>

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/routing.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/routing.md

# Routing

> Nuxt file-system routing creates a route for every file in the pages/ directory.

One core feature of Nuxt is the file system router. Every Vue file inside the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory creates a corresponding URL (or route) that displays the contents of the file. By using dynamic imports for each page, Nuxt leverages code-splitting to ship the minimum amount of JavaScript for the requested route.

## Pages

Nuxt routing is based on [vue-router](https://router.vuejs.org) and generates the routes from every component created in the [`app/pages/` directory](/docs/4.x/directory-structure/app/pages), based on their filename.

This file system routing uses naming conventions to create dynamic and nested routes:

<code-group>

```bash [Directory Structure]
-| pages/
---| about.vue
---| index.vue
---| posts/
-----| [id].vue
```

```json [Generated Router File]
{
  "routes": [
    {
      "path": "/about",
      "component": "pages/about.vue"
    },
    {
      "path": "/",
      "component": "pages/index.vue"
    },
    {
      "path": "/posts/:id",
      "component": "pages/posts/[id].vue"
    }
  ]
}
```

</code-group>

<read-more to="/docs/4.x/directory-structure/app/pages">



</read-more>

## Navigation

The [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) component links pages between them. It renders an `<a>` tag with the `href` attribute set to the route of the page. Once the application is hydrated, page transitions are performed in JavaScript by updating the browser URL. This prevents full-page refreshes and allows for animated transitions.

When a [`<NuxtLink>`](/docs/4.x/api/components/nuxt-link) enters the viewport on the client side, Nuxt will automatically prefetch components and payload (generated pages) of the linked pages ahead of time, resulting in faster navigation.

```vue [app/pages/index.vue]
<template>
  <header>
    <nav>
      <ul>
        <li><NuxtLink to="/about">About</NuxtLink></li>
        <li><NuxtLink to="/posts/1">Post 1</NuxtLink></li>
        <li><NuxtLink to="/posts/2">Post 2</NuxtLink></li>
      </ul>
    </nav>
  </header>
</template>
```

<read-more to="/docs/4.x/api/components/nuxt-link">



</read-more>

## Route Parameters

The [`useRoute()`](/docs/4.x/api/composables/use-route) composable can be used in a `<script setup>` block or a `setup()` method of a Vue component to access the current route details.

```vue [pages/posts/[id].vue]twoslash
<script setup lang="ts">
const route = useRoute()

// When accessing /posts/1, route.params.id will be 1
console.log(route.params.id)
</script>
```

<read-more to="/docs/4.x/api/composables/use-route">



</read-more>

## Route Middleware

Nuxt provides a customizable route middleware framework you can use throughout your application, ideal for extracting code that you want to run before navigating to a particular route.

<note>

Route middleware runs within the Vue part of your Nuxt app. Despite the similar name, they are completely different from server middleware, which are run in the Nitro server part of your app.

</note>

<important>

Route middleware does **not** run for server routes (e.g. `/api/*`) or other server requests. To apply middleware to these requests, use [server middleware](/docs/4.x/directory-structure/server#server-middleware) instead.

</important>

There are three kinds of route middleware:

1. Anonymous (or inline) route middleware, which are defined directly in the pages where they are used.
2. Named route middleware, which are placed in the [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) directory and will be automatically loaded via asynchronous import when used on a page. (**Note**: The route middleware name is normalized to kebab-case, so `someMiddleware` becomes `some-middleware`.)
3. Global route middleware, which are placed in the [`app/middleware/`](/docs/4.x/directory-structure/app/middleware) directory (with a `.global` suffix) and will be automatically run on every route change.

Example of an `auth` middleware protecting the `/dashboard` page:

<code-group>

```ts [middleware/auth.ts]twoslash
function isAuthenticated (): boolean { return false }
// ---cut---
export default defineNuxtRouteMiddleware((to, from) => {
  // isAuthenticated() is an example method verifying if a user is authenticated
  if (isAuthenticated() === false) {
    return navigateTo('/login')
  }
})
```

```vue [pages/dashboard.vue]twoslash
<script setup lang="ts">
definePageMeta({
  middleware: 'auth',
})
</script>

<template>
  <h1>Welcome to your dashboard</h1>
</template>
```

</code-group>

<read-more to="/docs/4.x/directory-structure/app/middleware">



</read-more>

## Route Validation

Nuxt offers route validation via the `validate` property in [`definePageMeta()`](/docs/4.x/api/utils/define-page-meta) in each page you wish to validate.

The `validate` property accepts the `route` as an argument. You can return a boolean value to determine whether or not this is a valid route to be rendered with this page. If you return `false`, this will cause a 404 error. You can also directly return an object with `status`/`statusText` to customize the error returned.

If you have a more complex use case, then you can use anonymous route middleware instead.

```vue [pages/posts/[id].vue]twoslash
<script setup lang="ts">
definePageMeta({
  validate (route) {
    // Check if the id is made up of digits
    return typeof route.params.id === 'string' && /^\d+$/.test(route.params.id)
  },
})
</script>
```

<read-more to="/docs/4.x/api/utils/define-page-meta">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/runtime-config.md

# Source: https://nuxt.com/raw/docs/3.x/bridge/runtime-config.md

# Source: https://nuxt.com/raw/docs/3.x/api/kit/runtime-config.md

# Source: https://nuxt.com/raw/docs/3.x/guide/going-further/runtime-config.md

# Source: https://nuxt.com/raw/docs/4.x/migration/runtime-config.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/runtime-config.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/runtime-config.md

# Source: https://nuxt.com/raw/docs/4.x/guide/going-further/runtime-config.md

# Runtime Config

> Nuxt provides a runtime config API to expose configuration and secrets within your application.

## Exposing

To expose config and environment variables to the rest of your app, you will need to define runtime configuration in your [`nuxt.config`](/docs/4.x/directory-structure/nuxt-config) file, using the [`runtimeConfig`](/docs/4.x/api/nuxt-config#runtimeconfig) option.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    // The private keys which are only available within server-side
    apiSecret: '123',
    // Keys within public, will be also exposed to the client-side
    public: {
      apiBase: '/api',
    },
  },
})
```

When adding `apiBase` to the `runtimeConfig.public`, Nuxt adds it to each page payload. We can universally access `apiBase` in both server and browser.

```ts
const runtimeConfig = useRuntimeConfig()

console.log(runtimeConfig.apiSecret)
console.log(runtimeConfig.public.apiBase)
```

<tip>

Public runtime config is accessible in Vue templates with `$config.public`.

</tip>

### Serialization

Your runtime config will be serialized before being passed to Nitro. This means that anything that cannot be serialized and then deserialized (such as functions, Sets, Maps, and so on), should not be set in your `nuxt.config`.

Instead of passing non-serializable objects or functions into your application from your `nuxt.config`, you can place this code in a Nuxt or Nitro plugin or middleware.

### Environment Variables

The most common way to provide configuration is by using environment variables.

<note>

The Nuxt CLI has built-in support for reading your `.env` file in development, build and generate. But when you run your built server, **your .env file will not be read**.

<read-more to="/docs/4.x/directory-structure/env">



</read-more>
</note>

Runtime config values are **automatically replaced by matching environment variables at runtime**.

There are two key requirements:

1. Your desired variables must be defined in your `nuxt.config`. This ensures that arbitrary environment variables are not exposed to your application code.
2. Only a specially-named environment variable can override a runtime config property. That is, an uppercase environment variable starting with `NUXT_` which uses `_` to separate keys and case changes.

<warning>

Setting the default of `runtimeConfig` values to *differently named environment variables* (for example setting `myVar` to `process.env.OTHER_VARIABLE`) will only work during build-time and will break on runtime.
It is advised to use environment variables that match the structure of your `runtimeConfig` object.

</warning>

<tip icon="i-lucide-video" target="_blank" to="https://youtu.be/_FYV5WfiWvs">

Watch a video from Alexander Lichter showcasing the top mistake developers make using runtimeConfig.

</tip>

#### Example

```ini [.env]
NUXT_API_SECRET=api_secret_token
NUXT_PUBLIC_API_BASE=https://nuxtjs.org
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    apiSecret: '', // can be overridden by NUXT_API_SECRET environment variable
    public: {
      apiBase: '', // can be overridden by NUXT_PUBLIC_API_BASE environment variable
    },
  },
})
```

## Reading

### Vue App

Within the Vue part of your Nuxt app, you will need to call [`useRuntimeConfig()`](/docs/4.x/api/composables/use-runtime-config) to access the runtime config.

<important>

The behavior is different between the client-side and server-side:

- On client-side, only keys in `runtimeConfig.public` and `runtimeConfig.app` (which is used by Nuxt internally) are available, and the object is both writable and reactive.
- On server-side, the entire runtime config is available, but it is read-only to avoid context sharing.

</important>

```vue [app/pages/index.vue]
<script setup lang="ts">
const config = useRuntimeConfig()

console.log('Runtime config:', config)
if (import.meta.server) {
  console.log('API secret:', config.apiSecret)
}
</script>

<template>
  <div>
    <div>Check developer console!</div>
  </div>
</template>
```

<caution>

**Security note:** Be careful not to expose runtime config keys to the client-side by either rendering them or passing them to `useState`.

</caution>

### Plugins

If you want to use the runtime config within any (custom) plugin, you can use [`useRuntimeConfig()`](/docs/4.x/api/composables/use-runtime-config) inside of your `defineNuxtPlugin` function.

```ts [app/plugins/config.ts]
export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  console.log('API base URL:', config.public.apiBase)
})
```

### Server Routes

You can access runtime config within the server routes as well using `useRuntimeConfig`.

```ts [server/api/test.ts]
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`,
    },
  })
  return result
})
```

<note>

Giving the `event` as argument to `useRuntimeConfig` is optional, but it is recommended to pass it to get the runtime config overwritten by [environment variables](/docs/4.x/guide/going-further/runtime-config#environment-variables) at runtime for server routes.

</note>

## Typing Runtime Config

Nuxt tries to automatically generate a typescript interface from provided runtime config using [unjs/untyped](https://github.com/unjs/untyped).

But it is also possible to type your runtime config manually:

```ts [index.d.ts]
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
  }
  interface PublicRuntimeConfig {
    apiBase: string
  }
}
// It is always important to ensure you import/export something when augmenting a type
export {}
```

<note>

`nuxt/schema` is provided as a convenience for end-users to access the version of the schema used by Nuxt in their project. Module authors should instead augment `@nuxt/schema`.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/seo-meta.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/seo-meta.md

# SEO and Meta

> Improve your Nuxt app's SEO with powerful head config, composables and components.

Nuxt head tag management is powered by [Unhead](https://unhead.unjs.io). It provides sensible defaults, several powerful composables
and numerous configuration options to manage your app's head and SEO meta tags.

## Nuxt Config

Providing an [`app.head`](/docs/4.x/api/nuxt-config#head) property in your [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) allows you to statically customize the head for your entire app.

<important>

This method does not allow you to provide reactive data. We recommend using `useHead()` in `app.vue`.

</important>

It's good practice to set tags here that won't change such as your site title default, language and favicon.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    head: {
      title: 'Nuxt', // default fallback title
      htmlAttrs: {
        lang: 'en',
      },
      link: [
        { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      ],
    },
  },
})
```

You can also provide any of the keys listed below in [Types](/docs/4.x/getting-started/seo-meta#types).

### Defaults Tags

Some tags are provided by Nuxt by default to ensure your website works well out of the box.

- `viewport`: `width=device-width, initial-scale=1`
- `charset`: `utf-8`

While most sites won't need to override these defaults, you can update them using the keyed shortcuts.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    head: {
      // update Nuxt defaults
      charset: 'utf-16',
      viewport: 'width=device-width, initial-scale=1, maximum-scale=1',
    },
  },
})
```

## `useHead`

The [`useHead`](/docs/4.x/api/composables/use-head) composable function supports reactive input, allowing you to manage your head tags programmatically.

```vue [app/app.vue]twoslash
<script setup lang="ts">
useHead({
  title: 'My App',
  meta: [
    { name: 'description', content: 'My amazing site.' },
  ],
  bodyAttrs: {
    class: 'test',
  },
  script: [{ innerHTML: 'console.log(\'Hello world\')' }],
})
</script>
```

We recommend taking a look at the [`useHead`](/docs/4.x/api/composables/use-head) and [`useHeadSafe`](/docs/4.x/api/composables/use-head-safe) composables.

## `useSeoMeta`

The [`useSeoMeta`](/docs/4.x/api/composables/use-seo-meta) composable lets you define your site's SEO meta tags as an object with full type safety.

This helps you avoid typos and common mistakes, such as using `name` instead of `property`.

```vue [app/app.vue]twoslash
<script setup lang="ts">
useSeoMeta({
  title: 'My Amazing Site',
  ogTitle: 'My Amazing Site',
  description: 'This is my amazing site, let me tell you all about it.',
  ogDescription: 'This is my amazing site, let me tell you all about it.',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image',
})
</script>
```

<read-more to="/docs/4.x/api/composables/use-seo-meta">



</read-more>

## Components

While using [`useHead`](/docs/4.x/api/composables/use-head) is recommended in all cases, you may have a personal preference for defining your head tags in your template using components.

Nuxt provides the following components for this purpose: `<Title>`, `<Base>`, `<NoScript>`, `<Style>`, `<Meta>`, `<Link>`, `<Body>`, `<Html>` and `<Head>`. Note
the capitalization of these components ensuring we don't use invalid native HTML tags.

`<Head>` and `<Body>` can accept nested meta tags (for aesthetic reasons) but this does not affect *where* the nested meta tags are rendered in the final HTML.

```vue [app/app.vue]
<script setup lang="ts">
const title = ref('Hello World')
</script>

<template>
  <div>
    <Head>
      <Title>{{ title }}</Title>
      <Meta
        name="description"
        :content="title"
      />
      <Style>
        body { background-color: green; }
      </Style>
    </Head>

    <h1>{{ title }}</h1>
  </div>
</template>
```

It's suggested to wrap your components in either a `<Head>` or `<Html>` components as tags will be deduped more intuitively.

<warning>

If you need to duplicate tags across client-server boundaries, apply a `key` attribute on the `<Head>` component.

</warning>

## Types

Below are the non-reactive types used for [`useHead`](/docs/4.x/api/composables/use-head), [`app.head`](/docs/4.x/api/nuxt-config#head) and components.

```ts
interface MetaObject {
  title?: string
  titleTemplate?: string | ((title?: string) => string)
  templateParams?: Record<string, string | Record<string, string>>
  base?: Base
  link?: Link[]
  meta?: Meta[]
  style?: Style[]
  script?: Script[]
  noscript?: Noscript[]
  htmlAttrs?: HtmlAttributes
  bodyAttrs?: BodyAttributes
}
```

See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.

## Features

### Reactivity

Reactivity is supported on all properties, by providing a computed value, a getter, or a reactive object.

<code-group>

```vue [useHead]twoslash
<script setup lang="ts">
const description = ref('My amazing site.')

useHead({
  meta: [
    { name: 'description', content: description },
  ],
})
</script>
```

```vue [useSeoMeta]twoslash
<script setup lang="ts">
const description = ref('My amazing site.')

useSeoMeta({
  description,
})
</script>
```

```vue [app/Components]
<script setup lang="ts">
const description = ref('My amazing site.')
</script>

<template>
  <div>
    <Meta
      name="description"
      :content="description"
    />
  </div>
</template>
```

</code-group>

### Title Template

You can use the `titleTemplate` option to provide a dynamic template for customizing the title of your site. For example, you could add the name of your site to the title of every page.

The `titleTemplate` can either be a string, where `%s` is replaced with the title, or a function.

If you want to use a function (for full control), then this cannot be set in your `nuxt.config`. It is recommended instead to set it within your `app.vue` file where it will apply to all pages on your site:

<code-group>

```vue [useHead]twoslash
<script setup lang="ts">
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} - Site Title` : 'Site Title'
  },
})
</script>
```

</code-group>

Now, if you set the title to `My Page` with [`useHead`](/docs/4.x/api/composables/use-head) on another page of your site, the title would appear as 'My Page - Site Title' in the browser tab. You could also pass `null` to default to 'Site Title'.

### Template Params

You can use `templateParams` to provide additional placeholders in your `titleTemplate` besides the default `%s`. This allows for more dynamic title generation.

<code-group>

```vue [useHead]twoslash
<script setup lang="ts">
useHead({
  titleTemplate: (titleChunk) => {
    return titleChunk ? `${titleChunk} %separator %siteName` : '%siteName'
  },
  templateParams: {
    siteName: 'Site Title',
    separator: '-',
  },
})
</script>
```

</code-group>

### Body Tags

You can use the `tagPosition: 'bodyClose'` option on applicable tags to append them to the end of the `<body>` tag.

For example:

```vuetwoslash
<script setup lang="ts">
useHead({
  script: [
    {
      src: 'https://third-party-script.com',
      // valid options are: 'head' | 'bodyClose' | 'bodyOpen'
      tagPosition: 'bodyClose',
    },
  ],
})
</script>
```

## Examples

### With `definePageMeta`

Within your [`app/pages/` directory](/docs/4.x/directory-structure/app/pages), you can use `definePageMeta` along with [`useHead`](/docs/4.x/api/composables/use-head) to set metadata based on the current route.

For example, you can first set the current page title (this is extracted at build time via a macro, so it can't be set dynamically):

```vue [pages/some-page.vue]twoslash
<script setup lang="ts">
definePageMeta({
  title: 'Some Page',
})
</script>
```

And then in your layout file, you might use the route's metadata you have previously set:

```vue [layouts/default.vue]twoslash
<script setup lang="ts">
const route = useRoute()

useHead({
  meta: [{ property: 'og:title', content: `App Name - ${route.meta.title}` }],
})
</script>
```

<link-example to="/docs/4.x/examples/features/meta-tags">



</link-example>

<read-more to="/docs/4.x/directory-structure/app/pages/#page-metadata">



</read-more>

### Dynamic Title

In the example below, `titleTemplate` is set either as a string with the `%s` placeholder or as a `function`, which allows greater flexibility in setting the page title dynamically for each route of your Nuxt app:

```vue [app/app.vue]twoslash
<script setup lang="ts">
useHead({
  // as a string,
  // where `%s` is replaced with the title
  titleTemplate: '%s - Site Title',
})
</script>
```

```vue [app/app.vue]twoslash
<script setup lang="ts">
useHead({
  // or as a function
  titleTemplate: (productCategory) => {
    return productCategory
      ? `${productCategory} - Site Title`
      : 'Site Title'
  },
})
</script>
```

`nuxt.config` is also used as an alternative way of setting the page title. However, `nuxt.config` does not allow the page title to be dynamic. Therefore, it is recommended to use `titleTemplate` in the `app.vue` file to add a dynamic title, which is then applied to all routes of your Nuxt app.

### External CSS

The example below shows how you might enable Google Fonts using either the `link` property of the [`useHead`](/docs/4.x/api/composables/use-head) composable or using the `<Link>` component:

<code-group>

```vue [useHead]twoslash
<script setup lang="ts">
useHead({
  link: [
    {
      rel: 'preconnect',
      href: 'https://fonts.googleapis.com',
    },
    {
      rel: 'stylesheet',
      href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap',
      crossorigin: '',
    },
  ],
})
</script>
```

```vue [app/Components]
<template>
  <div>
    <Link
      rel="preconnect"
      href="https://fonts.googleapis.com"
    />
    <Link
      rel="stylesheet"
      href="https://fonts.googleapis.com/css2?family=Roboto&display=swap"
      crossorigin=""
    />
  </div>
</template>
```

</code-group>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/server-engine.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/server-engine.md

# Server Engine

> Nuxt is powered by a new server engine: Nitro.

While building Nuxt, we created a new server engine: [Nitro](https://nitro.build/).

It is shipped with many features:

- Cross-platform support for Node.js, browsers, service workers and more.
- Serverless support out-of-the-box.
- API routes support.
- Automatic code-splitting and async-loaded chunks.
- Hybrid mode for static + serverless sites.
- Development server with hot module reloading.

## API Layer

Server [API endpoints](/docs/4.x/directory-structure/server#server-routes) and [Middleware](/docs/4.x/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/h3js/h3).

Key features include:

- Handlers can directly return objects/arrays for an automatically-handled JSON response
- Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported)
- Helper functions for body parsing, cookie handling, redirects, headers and more

Check out [the h3 docs](https://github.com/h3js/h3) for more information.

<read-more to="/docs/4.x/directory-structure/server#server-routes">

Learn more about the API layer in the `server/` directory.

</read-more>

## Direct API Calls

Nitro allows 'direct' calling of routes via the globally-available [`$fetch`](/docs/4.x/api/utils/dollarfetch) helper. This will make an API call to the server if run on the browser, but will directly call the relevant function if run on the server, **saving an additional API call**.

[`$fetch`](/docs/4.x/api/utils/dollarfetch) API is using [ofetch](https://github.com/unjs/ofetch), with key features including:

- Automatic parsing of JSON responses (with access to raw response if needed)
- Request body and params are automatically handled, with correct `Content-Type` headers

For more information on `$fetch` features, check out [ofetch](https://github.com/unjs/ofetch).

## Typed API Routes

When using API routes (or middleware), Nitro will generate typings for these routes as long as you are returning a value instead of using `res.end()` to send a response.

You can access these types when using [`$fetch()`](/docs/4.x/api/utils/dollarfetch) or [`useFetch()`](/docs/4.x/api/composables/use-fetch).

## Standalone Server

Nitro produces a standalone server dist that is independent of `node_modules`.

The server in Nuxt 2 is not standalone and requires part of Nuxt core to be involved by running `nuxt start` (with the [`nuxt-start`](https://www.npmjs.com/package/nuxt-start) or [`nuxt`](https://www.npmjs.com/package/nuxt) distributions) or custom programmatic usage, which is fragile and prone to breakage and not suitable for serverless and service worker environments.

Nuxt generates this dist when running `nuxt build` into a [`.output`](/docs/4.x/directory-structure/output) directory.

The output contains runtime code to run your Nuxt server in any environment (including experimental browser service workers!) and serve your static files, making it a true hybrid framework for the JAMstack. In addition, Nuxt implements a native storage layer, supporting multi-source drivers and local assets.

<read-more to="https://github.com/nitrojs/nitro" icon="i-simple-icons-github" target="_blank">

Read more about Nitro engine on GitHub.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/migration/server.md

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/server.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/server.md

# Source: https://nuxt.com/raw/docs/4.x/migration/server.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/server.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/server.md

# Server

> Build full-stack applications with Nuxt's server framework. You can fetch data from your database or another server, create APIs, or even generate static server-side content like a sitemap or a RSS feed - all from a single codebase.

<read-more to="/docs/4.x/directory-structure/server">



</read-more>

## Powered by Nitro

![Server engine](/assets/docs/getting-started/server.svg)

Nuxt's server is [Nitro](https://github.com/nitrojs/nitro). It was originally created for Nuxt but is now part of [UnJS](https://unjs.io) and open for other frameworks - and can even be used on its own.

Using Nitro gives Nuxt superpowers:

- Full control of the server-side part of your app
- Universal deployment on any provider (many zero-config)
- Hybrid rendering

Nitro is internally using [h3](https://github.com/h3js/h3), a minimal H(TTP) framework built for high performance and portability.

<video-accordion title="Watch a video from Alexander Lichter to understand the responsibilities of Nuxt and Nitro in your application" video-id="DkvgJa-X31k">



</video-accordion>

## Server Endpoints & Middleware

You can easily manage the server-only part of your Nuxt app, from API endpoints to middleware.

Both endpoints and middleware can be defined like this:

```ts [server/api/test.ts]twoslash
export default defineEventHandler(async (event) => {
  // ... Do whatever you want here
})
```

And you can directly return `text`, `json`, `html` or even a `stream`.

Out-of-the-box, it supports **hot module replacement** and **auto-import** like the other parts of your Nuxt application.

<read-more to="/docs/4.x/directory-structure/server">



</read-more>

## Universal Deployment

Nitro offers the ability to deploy your Nuxt app anywhere, from a bare metal server to the edge network, with a start time of just a few milliseconds. That's fast!

<read-more to="/blog/nuxt-on-the-edge">



</read-more>

There are more than 15 presets to build your Nuxt app for different cloud providers and servers, including:

- [Cloudflare Workers](https://workers.cloudflare.com)
- [Netlify Functions](https://www.netlify.com/platform/core/functions/)
- [Vercel Cloud](https://vercel.com/home)

Or for other runtimes:

<card-group>
<card icon="i-logos-deno" target="_blank" title="Deno" to="https://deno.com">



</card>

<card icon="i-logos-bun" target="_blank" title="Bun" to="https://bun.com">



</card>
</card-group>

<read-more to="/docs/4.x/getting-started/deployment">



</read-more>

## Hybrid Rendering

Nitro has a powerful feature called `routeRules` which allows you to define a set of rules to customize how each route of your Nuxt app is rendered (and more).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  routeRules: {
    // Generated at build time for SEO purpose
    '/': { prerender: true },
    // Cached for 1 hour
    '/api/*': { cache: { maxAge: 60 * 60 } },
    // Redirection to avoid 404
    '/old-page': {
      redirect: { to: '/new-page', statusCode: 302 },
    },
    // ...
  },
})
```

<read-more to="/docs/4.x/guide/concepts/rendering#hybrid-rendering">

Learn about all available route rules are available to customize the rendering mode of your routes.

</read-more>

In addition, there are some route rules (for example, `ssr`, `appMiddleware`, and `noScripts`) that are Nuxt specific to change the behavior when rendering your pages to HTML.

Some route rules (`appMiddleware`, `redirect` and `prerender`) also affect client-side behavior.

Nitro is used to build the app for server side rendering, as well as pre-rendering.

<read-more to="/docs/4.x/guide/concepts/rendering">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/guide/recipes/sessions-and-authentication.md

# Source: https://nuxt.com/raw/docs/4.x/guide/recipes/sessions-and-authentication.md

# Sessions and Authentication

> Authentication is an extremely common requirement in web apps. This recipe will show you how to implement basic user registration and authentication in your Nuxt app.

## Introduction

In this recipe we'll be setting up authentication in a full-stack Nuxt app using [Nuxt Auth Utils](https://github.com/Atinux/nuxt-auth-utils) which provides convenient utilities for managing client-side and server-side session data.

The module uses secured & sealed cookies to store session data, so you don't need to setup a database to store session data.

## Install nuxt-auth-utils

Install the `nuxt-auth-utils` module using the `nuxt` CLI.

```bash [Terminal]
npx nuxt module add auth-utils
```

<callout>

This command will install `nuxt-auth-utils` as dependency and push it in the `modules` section of our `nuxt.config.ts`

</callout>

## Cookie Encryption Key

As `nuxt-auth-utils` uses sealed cookies to store session data, session cookies are encrypted using a secret key from the `NUXT_SESSION_PASSWORD` environment variable.

<note>

If not set, this environment variable will be added to your `.env` automatically when running in development mode.

</note>

```ini [.env]
NUXT_SESSION_PASSWORD=a-random-password-with-at-least-32-characters
```

<important>

You'll need to add this environment variable to your production environment before deploying.

</important>

## Login API Route

For this recipe, we'll create a simple API route to sign-in a user based on static data.

Let's create a `/api/login` API route that will accept a POST request with the email and password in the request body.

```ts [server/api/login.post.ts]
import { z } from 'zod'

const bodySchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
})

export default defineEventHandler(async (event) => {
  const { email, password } = await readValidatedBody(event, bodySchema.parse)

  if (email === 'admin@admin.com' && password === 'iamtheadmin') {
    // set the user session in the cookie
    // this server util is auto-imported by the auth-utils module
    await setUserSession(event, {
      user: {
        name: 'John Doe',
      },
    })
    return {}
  }
  throw createError({
    status: 401,
    message: 'Bad credentials',
  })
})
```

<callout>

Make sure to install the `zod` dependency in your project (`npm i zod`).

</callout>

<tip to="https://github.com/atinux/nuxt-auth-utils#server-utils">

Read more about the `setUserSession` server helper exposed by `nuxt-auth-utils`.

</tip>

## Login Page

The module exposes a Vue composable to know if a user is authenticated in our application:

```vue
<script setup>
const { loggedIn, session, user, clear, fetch } = useUserSession()
</script>
```

Let's create a login page with a form to submit the login data to our `/api/login` route.

```vue [app/pages/login.vue]
<script setup lang="ts">
const { loggedIn, user, fetch: refreshSession } = useUserSession()
const credentials = reactive({
  email: '',
  password: '',
})
async function login () {
  try {
    await $fetch('/api/login', {
      method: 'POST',
      body: credentials,
    })

    // Refresh the session on client-side and redirect to the home page
    await refreshSession()
    await navigateTo('/')
  } catch {
    alert('Bad credentials')
  }
}
</script>

<template>
  <form @submit.prevent="login">
    <input
      v-model="credentials.email"
      type="email"
      placeholder="Email"
    >
    <input
      v-model="credentials.password"
      type="password"
      placeholder="Password"
    >
    <button type="submit">
      Login
    </button>
  </form>
</template>
```

## Protect API Routes

Protecting server routes is key to making sure your data is safe. Client-side middleware is helpful for the user, but without server-side protection your data can still be accessed. It is critical to protect any routes with sensitive data, we should return a 401 error if the user is not logged in on those.

The `auth-utils` module provides the `requireUserSession` utility function to help make sure that users are logged in and have an active session.

Let's create an example of a `/api/user/stats` route that only authenticated users can access.

```ts [server/api/user/stats.get.ts]
export default defineEventHandler(async (event) => {
  // make sure the user is logged in
  // This will throw a 401 error if the request doesn't come from a valid user session
  const { user } = await requireUserSession(event)

  // TODO: Fetch some stats based on the user

  return {}
})
```

## Protect App Routes

Our data is safe with the server-side route in place, but without doing anything else, unauthenticated users would probably get some odd data when trying to access the `/users` page. We should create a [client-side middleware](https://nuxt.com/docs/4.x/directory-structure/app/middleware) to protect the route on the client side and redirect users to the login page.

`nuxt-auth-utils` provides a convenient `useUserSession` composable which we'll use to check if the user is logged in, and redirect them if they are not.

We'll create a middleware in the `/middleware` directory. Unlike on the server, client-side middleware is not automatically applied to all endpoints, and we'll need to specify where we want it applied.

```typescript [app/middleware/authenticated.ts]
export default defineNuxtRouteMiddleware(() => {
  const { loggedIn } = useUserSession()

  // redirect the user to the login screen if they're not authenticated
  if (!loggedIn.value) {
    return navigateTo('/login')
  }
})
```

## Home Page

Now that we have our app middleware to protect our routes, we can use it on our home page that display our authenticated user information. If the user is not authenticated, they will be redirected to the login page.

We'll use [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) to apply the middleware to the route that we want to protect.

```vue [app/pages/index.vue]
<script setup lang="ts">
definePageMeta({
  middleware: ['authenticated'],
})

const { user, clear: clearSession } = useUserSession()

async function logout () {
  await clearSession()
  await navigateTo('/login')
}
</script>

<template>
  <div>
    <h1>Welcome {{ user.name }}</h1>
    <button @click="logout">
      Logout
    </button>
  </div>
</template>
```

We also added a logout button to clear the session and redirect the user to the login page.

## Conclusion

We've successfully set up a very basic user authentication and session management in our Nuxt app. We've also protected sensitive routes on the server and client side to ensure that only authenticated users can access them.

As next steps, you can:

- Add authentication using the [20+ supported OAuth providers](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#supported-oauth-providers)
- Add a database to store users, see [Nitro SQL Database](https://nitro.build/guide/database) or [NuxtHub SQL Database](https://hub.nuxt.com/docs/features/database)
- Let user signup with email & password using [password hashing](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#password-hashing)
- Add support for [WebAuthn / Passkeys](https://github.com/atinux/nuxt-auth-utils?tab=readme-ov-file#webauthn-passkey)

Checkout the open source [atidone repository](https://github.com/atinux/atidone) for a full example of a Nuxt app with OAuth authentication, database and CRUD operations.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/set-page-layout.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/set-page-layout.md

# setPageLayout

> setPageLayout allows you to dynamically change the layout of a page.

<important>

`setPageLayout` allows you to dynamically change the layout of a page. It relies on access to the Nuxt context and therefore can only be called within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).

</important>

```ts [app/middleware/custom-layout.ts]
export default defineNuxtRouteMiddleware((to) => {
  // Set the layout on the route you are navigating _to_
  setPageLayout('other')
})
```

## Passing Props to Layouts

You can pass props to the layout by providing an object as the second argument:

```ts [app/middleware/admin-layout.ts]
export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    title: 'Dashboard',
  })
})
```

The layout can then receive these props:

```vue [app/layouts/admin.vue]
<script setup lang="ts">
const props = defineProps<{
  sidebar?: boolean
  title?: string
}>()
</script>

<template>
  <div>
    <aside v-if="sidebar">
      Sidebar
    </aside>
    <main>
      <h1>{{ title }}</h1>
      <slot />
    </main>
  </div>
</template>
```

<note>

If you choose to set the layout dynamically on the server side, you *must* do so before the layout is rendered by Vue (that is, within a plugin or route middleware) to avoid a hydration mismatch.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/set-response-status.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/set-response-status.md

# setResponseStatus

> setResponseStatus sets the status (and optionally the statusText) of the response.

Nuxt provides composables and utilities for first-class server-side-rendering support.

`setResponseStatus` sets the status (and optionally the statusText) of the response.

<important>

`setResponseStatus` can only be called in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).

</important>

```ts
const event = useRequestEvent()

// event will be undefined in the browser
if (event) {
  // Set the status code to 404 for a custom 404 page
  setResponseStatus(event, 404)

  // Set the status message as well
  setResponseStatus(event, 404, 'Page Not Found')
}
```

<note>

In the browser, `setResponseStatus` will have no effect.

</note>

<read-more to="/docs/4.x/getting-started/error-handling">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/shared.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/shared.md

# shared

> Use the shared/ directory to share functionality between the Vue app and the Nitro server.

The `shared/` directory allows you to share code that can be used in both the Vue app and the Nitro server.

<note>

The `shared/` directory is available in Nuxt v3.14+.

</note>

<important>

Code in the `shared/` directory cannot import any Vue or Nitro code.

</important>

<video-accordion title="Watch a video from Vue School on sharing utils and types between app and server" video-id="nnAR-MO3q5M">



</video-accordion>

## Usage

**Method 1:** Named export

```ts [shared/utils/capitalize.ts]twoslash
export const capitalize = (input: string) => {
  return input[0] ? input[0].toUpperCase() + input.slice(1) : ''
}
```

**Method 2:** Default export

```ts [shared/utils/capitalize.ts]twoslash
export default function (input: string) {
  return input[0] ? input[0].toUpperCase() + input.slice(1) : ''
}
```

You can now use [auto-imported](/docs/4.x/directory-structure/shared) utilities in your Nuxt app and `server/` directory.

```vue [app/app.vue]
<script setup lang="ts">
const hello = capitalize('hello')
</script>

<template>
  <div>
    {{ hello }}
  </div>
</template>
```

```ts [server/api/hello.get.ts]
export default defineEventHandler((event) => {
  return {
    hello: capitalize('hello'),
  }
})
```

## How Files Are Scanned

Only files in the `shared/utils/` and `shared/types/` directories will be auto-imported. Files nested within subdirectories of these directories will not be auto-imported unless you add these directories to `imports.dirs` and `nitro.imports.dirs`.

<tip>

The way `shared/utils` and `shared/types` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/4.x/directory-structure/app/composables) and [`app/utils/`](/docs/4.x/directory-structure/app/utils) directories.

</tip>

<read-more to="/docs/4.x/directory-structure/app/composables#how-files-are-scanned">



</read-more>

```bash [Directory Structure]
-| shared/
---| capitalize.ts        # Not auto-imported
---| formatters
-----| lower.ts           # Not auto-imported
---| utils/
-----| lower.ts           # Auto-imported
-----| formatters
-------| upper.ts         # Not auto-imported
---| types/
-----| bar.ts             # Auto-imported
```

Any other files you create in the `shared/` folder must be manually imported using the `#shared` alias (automatically configured by Nuxt):

```ts
// For files directly in the shared directory
import capitalize from '#shared/capitalize'

// For files in nested directories
import lower from '#shared/formatters/lower'

// For files nested in a folder within utils
import upper from '#shared/utils/formatters/upper'
```

This alias ensures consistent imports across your application, regardless of the importing file's location.

<read-more to="/docs/4.x/guide/concepts/auto-imports">



</read-more>

---

# Source: https://nuxt.com/raw/blog/shiki-v1.md

# The Evolution of Shiki v1.0

> Shiki v1.0 came with many improvements and features - see how Nuxt drives the evolution of Shiki!

[Shiki](https://github.com/shikijs/shiki) is a syntax highlighter that uses [TextMate grammars and themes](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide#textmate-grammars), the same engine that powers VS Code. It provides one of the most accurate and beautiful syntax highlighting for your code snippets. It was created by [Pine Wu](https://github.com/octref) back in 2018, when he was part of the VS Code team. It started as an experiment to use [Oniguruma](https://github.com/microsoft/vscode-oniguruma) to do syntax highlighting.

Different from existing syntax highlighters like [Prism](https://prismjs.com/) and [Highlight.js](https://highlightjs.org/) that designed to run in the browser, Shiki took a different approach by **highlighting ahead of time**. It ships the highlighted HTML to the client, producing accurate and beautiful syntax highlighting with **zero JavaScript**. It soon took off and became a very popular choice, especially for static site generators and documentation sites.

<collapsible name="Shiki Example">

For example, with the code snippet below:

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
  ],
})
```

Shiki will generate the following HTML:

```html
<pre class="shiki material-theme-palenight" style="background-color:#292D3E;color:#babed8" tabindex="0">
  <code>
    <span class="line"><span style="color:#89DDFF;font-style:italic">export</span><span style="color:#89DDFF;font-style:italic"> default</span><span style="color:#82AAFF"> defineNuxtConfig</span><span style="color:#BABED8">(</span><span style="color:#89DDFF">{</span></span>
    <span class="line"><span style="color:#F07178">  modules</span><span style="color:#89DDFF">:</span><span style="color:#BABED8"> [</span></span>
    <span class="line"><span style="color:#89DDFF">    '</span><span style="color:#C3E88D">@nuxt/content</span><span style="color:#89DDFF">'</span><span style="color:#89DDFF">,</span></span>
    <span class="line"><span style="color:#BABED8">  ]</span><span style="color:#89DDFF">,</span></span>
    <span class="line"><span style="color:#89DDFF">}</span><span style="color:#BABED8">)</span></span>
  </code>
</pre>
```

It might look a bit overwhelming if you read it, but **this piece of HTML works everywhere without any JavaScript or CSS**. TextMate grammars has a very rich representation of the types of every token (TextMate scopes). Since Shiki flattens all the tokens into styled spans, it achieves accurate results that most traditional CSS-based highlighters have difficulties achieving.

</collapsible>

While Shiki is awesome, it's still a library that is designed to run on Node.js. This means it is limited to highlighting static code only and would have trouble with dynamic code, because Shiki doesn't work in the browser. In addition, Shiki relies on the WASM binary of Oniguruma, as well as a bunch of heavy grammar and theme files in JSON. It uses Node.js filesystem and path resolution to load these files, which is not accessible in the browser.

To improve that situation, I [started this RFC](https://github.com/shikijs/shiki/issues/91) that later landed with [this PR](https://github.com/shikijs/shiki/pull/109) and shipped in Shiki v0.9. While it abstracted the file loading layer to use fetch or filesystem based on the environment, it's still quite complicated to use as you need to serve the grammars and theme files somewhere in your bundle or CDN manually, then call the `setCDN` method to tell Shiki where to load these files.

The solution is not perfect but at least it made it possible to run Shiki in the browser to highlight dynamic content. We have been using that approach since then - until the story of this article began.

## The Start

Nuxt is putting a lot effort in pushing the [web to the edge](/blog/nuxt-on-the-edge), making the web more accessible with lower latency and better performance. Like CDN servers, edge hosting services such as [CloudFlare Workers](https://workers.cloudflare.com/) are deployed all over the world. Users get the content from the nearest edge server without the round trips to the origin server which could be thousands of miles away. With the awesome benefits it provides, it also comes with some trade-offs. For example, edge servers use a restricted runtime environment. CloudFlare Workers also does not support file system access and usually don't preserve the state between requests. While Shiki's main overhead is loading the grammars and themes upfront, that wouldn't work well in the edge environment.

It all started with a chat between [Sébastien](https://x.com/Atinux) and me. We were trying to make [Nuxt Content](https://github.com/nuxt/content) which uses Shiki to highlight the code blocks, to work on the edge.

![Chat History Between Sébastien and Anthony](/assets/blog/shiki-start-chat.png)

I started the experiments by patching [`shiki-es`](https://github.com/pi0/shiki-es) (a ESM build of Shiki by [Pooya Parsa](https://github.com/pi0)) locally, to convert the grammars and themes files into [ECMAScript Module (ESM)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) so that it could be understood and bundled by the build tools. This was done to create the code bundle for CloudFlare Workers to consume without using the filesystem nor making network requests.

```ts [Before - Read JSON assets from filesystem]
import fs from 'fs/promises'

const cssGrammar = JSON.parse(await fs.readFile('../langs/css.json', 'utf-8'))
```

```ts [After - Using ESM import]
const cssGrammar = await import('../langs/css.mjs').then(m => m.default)
```

We need to wrap the JSON files into ESM as inline literal so that we can use [`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) to dynamically import them. The difference is that `import()` is a standard JavaScript feature that works everywhere, while `fs.readFile` is a Node.js specific API that only works in Node.js. Having `import()` statically would also make bundlers like [Rollup](https://rollupjs.org/) and [webpack](https://webpack.js.org/) able to construct the module relationship graph and [emit the bundled code as chunks](https://rollupjs.org/tutorial/#code-splitting).

Then, I realized that it actually takes more than that to make it work on edge runtimes. Since bundlers expect imports to be resolvable at build time (meaning that in order to support all the languages and themes), we need to list all the import statements in every single grammar and theme file in the codebase. This would end up with a huge bundle size with a bunch of grammars and themes that you might not actually use. This problem is particularly important in the edge environment, where the bundle size is critical for performance.

So, we needed to figure out a better middle ground to make it work better.

## The Fork - Shikiji

Knowing this might fundamentally change the way Shiki works, and since we don't want to risk breaking the existing Shiki users with our experiments, I started a fork of Shiki called [Shikiji](https://github.com/antfu/shikiji). I rewrote the code from scratch while keeping the previous API design decisions in mind. The goal is to make Shiki runtime-agnostic, performant and efficient, like the philosophy we have at [UnJS](https://github.com/unjs).

To make that happen, we need to make Shikiji completely ESM-friendly, pure and [tree-shakable](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking). This goes all the way up to the dependencies of Shiki such as [`vscode-oniguruma`](https://github.com/microsoft/vscode-oniguruma) and [`vscode-textmate`](https://github.com/microsoft/vscode-textmate), which are provided in [Common JS (CJS)](https://requirejs.org/docs/commonjs.html) format.  `vscode-oniguruma` also contains a WASM binding generated by [`emscripten`](https://github.com/emscripten-core/emscripten) that contains [dangling promises](https://github.com/typescript-eslint/typescript-eslint/blob/main/packages/eslint-plugin/docs/rules/no-floating-promises.md) that will make CloudFlare Workers fail to finish the request. We ended up by embedding the WASM binary into a [base64 string](https://en.wikipedia.org/wiki/Base64) and shipping it as an ES module, manually rewriting the WASM binding to avoid dangling promises, and [vendored `vscode-textmate`](https://github.com/shikijs/shiki/blob/main/CONTRIBUTING.md#clone) to compile from its source code and produce the efficient ESM output.

The end result was very promising. We managed to get Shikiji working on any runtime environment, with even the possibility to [import it from CDN and run in the browser](https://shiki.style/guide/install#cdn-usage) with a single line of code.

We also took the chance to improve the API and the internal architecture of Shiki. We switched from simple string concatenation to use [`hast`](https://github.com/syntax-tree/hast), creating an Abstract Syntax Tree (AST) for generating the HTML output. This opens up the possibility of exposing a [Transformers API](https://shiki.style/guide/transformers) to allow users to modify the intermediate HAST and do many cool integrations that would be very hard to achieve previously.

Dark/Light mode support [was a frequently requested feature](https://github.com/shikijs/shiki/issues/33). Because of the static approach Shiki takes, it won't be possible to change the theme on the fly at rendering. The solution in the past was to generate the highlighted HTML twice, and toggle their visibility based on the user's preference - it wasn't efficient as it duplicate the payload, or used [CSS variables theme](https://github.com/shikijs/shiki/pull/212) which lost the granular highlighting Shiki is great for. With the new architecture that Shikiji has, I took a step back and rethought the problem, and [came up with the idea](https://github.com/shikijs/shiki/issues/33#issuecomment-1676362336) of breaking down the common tokens and merge multiple themes as inlined CSS variables, which provide  efficient output while aligning with the Shiki's philosophy. You can learn more about it in [Shiki's documentation](https://shiki.style/guide/dual-themes).

To make the migration easier, we also created the [`shikiji-compat` compatibility layer](https://shikiji.netlify.app/guide/compat), which uses Shikiji's new foundation and provides backward compatibility API.

To get Shikiji to work on Cloudflare Workers, we had one last challenge as they don't support [initiating WASM instance](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/instantiate_static)s from inlined binary data. Instead it requires importing the static `.wasm` assets for security reasons. This means that our "All-in-ESM" approach does not work well on CloudFlare. This would require extra work for users to provide different WASM sources, which makes the experience more difficult than we intended. At this moment, [Pooya Parsa](https://github.com/pi0) stepped in and made the universal layer [`unjs/unwasm`](https://github.com/unjs/unwasm), which supports the upcoming [WebAssembly/ES Module Integration](https://github.com/WebAssembly/esm-integration/tree/main/proposals/esm-integration) proposal. It has been integrated into [Nitro to have automated WASM targets](https://github.com/unjs/nitro/pull/2037). We hope that `unwasm` will help developers to have a better experience when working with WASM.

Overall, the Shikiji rewrite works well. [Nuxt Content](https://github.com/nuxt/content), [VitePress](https://vitepress.dev/) and [Astro](https://astro.build/) have been migrated to it. The feedback we have received has also been very positive.

## Merging Back

I am a team member of Shiki and have helped to do releases from time to time. While [Pine](https://github.com/octref) is the lead of Shiki, he was busy on other stuff and Shiki's iterations slowed down. During the experiments in Shikiji, I [proposed a few improvements](https://github.com/shikijs/shiki/issues/510) that could help Shiki acquire a modern structure. While generally everyone agreed with that direction, there would have been quite a lot of work to do and no one started to work on that.

While we were happy to use Shikiji to solve the problems we had, we certainly didn't want to see the community split by two different versions of Shiki. After a call with Pine, we made the consensus to merge the two projects into one:

<read-more color="purple" icon="i-octicon-git-merge-24" to="https://github.com/shikijs/shiki/pull/557">

feat!: merge Shikiji back into Shiki for v1.0 <span className="opacity-50">

#557

</span>
</read-more>

We are really happy to see that our work in Shikiji has been merged back to Shiki, that not only works for ourselves, but also benefits the entire community. With this merge, it **solves around 95% of the open issues** we have had in Shiki for years:

![Shikiji Merged Back to Shiki](/assets/blog/shiki-merge-pr.png)

Shiki now also got [a brand new documentation site](https://shiki.style/) where you can also play it right in your browser (thanks to the agnostic approach!). Many frameworks now has built-in integration with Shiki, maybe you are already using it somewhere!

## Twoslash

[Twoslash](https://github.com/twoslashes/twoslash) is an integration tool to retrieve type information from [TypeScript Language Services](https://github.com/microsoft/TypeScript/wiki/Using-the-Language-Service-API) and generated to your code snippet. It essentially make your static code snippet to have hover type information similar to your VS Code editor. It's made by [Orta Therox](https://github.com/orta) for the [TypeScript documentation site](https://github.com/microsoft/TypeScript-Website), there you can find [the original source code here](https://github.com/microsoft/TypeScript-Website/tree/v2/packages/ts-twoslasher). Orta also created the [Twoslash integration for Shiki v0.x versions](https://github.com/shikijs/twoslash). Back then, Shiki [did not have proper plugin system](https://github.com/shikijs/shiki/issues/380), that makes the `shiki-twoslash` had to be built as a wrapper over Shiki, make it a bit hard to set up as the existing Shiki integrations won't directly work with Twoslash.

We also took the chance to revise the Twoslash integrations when we were rewriting Shikiji, also a way to [dog-fooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) and verify the extensibility. With the new HAST internal, we are able to [integrate Twoslash as a transformer plugin](https://shiki.style/packages/twoslash), making it works everywhere that Shiki works and also in a composable way to be used with other transformers.

With this, we started to think that we could probably get Twoslash to work on [nuxt.com](/), the website you are looking at. nuxt.com uses [Nuxt Content](https://github.com/nuxt/content) under the hood, and different from other documentation tools like VitePress, one of the benefits Nuxt Content provides is that it's able to handle dynamic content and runs on the edge. Since Twoslash is relying on TypeScript as well as the giant types modules graph from your dependencies, that would be not ideal to ship all those things to the edge or browser. Sounds tricky, but challenge accepted!

We first come up of fetching the types on-demand from CDN, using the [Auto-Type-Acquisition](https://github.com/microsoft/TypeScript-Website/tree/v2/packages/ata) technique that you will see on the [TypeScript playground](https://www.typescriptlang.org/play). We made the [`twoslash-cdn`](https://github.com/antfu/twoslash-cdn) that allows Twoslash to run in any runtime. However, still, it sounds like not the most optimal solution, as it would still require to make many network requests that might defeat the purpose of running on the edge.

After a few iterations on the underlying tools (e.g. on [`@nuxtjs/mdc`](https://github.com/nuxt-modules/mdc/pull/129), the markdown compiler used by Nuxt Content), we managed to take the hybrid approach and made [`nuxt-content-twoslash`](https://github.com/antfu/nuxt-content-twoslash) that runs Twoslash on build time and caches the results for edge rendering. This way we could avoid shipping any extra dependencies to the final bundle, but still have the rich interactive code snippets on the website:

```vuetwoslash
<script setup>
// Try hover on identifiers below to see the types
const count = useState('counter', () => 0)
const double = computed(() => count.value * 2)
</script>

<template>
  <button>Count is: {{ count }}</button>
  <div>Double is: {{ double }}</div>
</template>
```

During that, we also took the chance to refactor [Twoslash](https://github.com/twoslashes/twoslash) with Orta to have a more efficient and modern structure. It also allows us have [`twoslash-vue`](https://github.com/twoslashes/twoslash/tree/main/packages/twoslash-vue) that provides the [Vue SFC](https://vuejs.org/guide/scaling-up/sfc.html) support as you are playing above. It's powered by [Volar.js](https://github.com/volarjs/volar.js) and [`vuejs/language-tools`](https://github.com/vuejs/language-tools). With Volar growing to be framework agnostic and frameworks to work together, we are looking forward to see such integrations to expand to more syntaxes like Astro and Svelte components files in the future.

## Integrations

If you want to give Shiki a try in your own website, here you can find some integrations that we have made:

- [Nuxt](https://shiki.style/packages/nuxt)
  - If using [Nuxt Content](https://content.nuxt.com/), Shiki is [build-in](https://content.nuxt.com/get-started/configuration#highlight). For Twoslash, you can add [`nuxt-content-twoslash`](https://github.com/antfu/nuxt-content-twoslash) on top.
  - If not, you can use [`nuxt-shiki`](https://github.com/pi0/nuxt-shiki) to use Shiki as Vue component or composibles.
- [VitePress](https://shiki.style/packages/vitepress)
  - Shiki is [built-in](https://vitepress.dev/guide/markdown#syntax-highlighting-in-code-blocks). For Twoslash, you can use [`vitepress-twoslash`](https://shiki.style/packages/vitepress#twoslash).
- Low-level integrations - Shiki provides official integrations for markdown compilers:

  - [`markdown-it`](https://shiki.style/packages/markdown-it) - Plugin for [`markdown-it`](https://github.com/markdown-it/markdown-it)
  - [`rehype`](https://shiki.style/packages/rehype) - Plugin for [`rehype`](https://github.com/rehypejs/rehype)

Check out more integrations on [Shiki's Documentation](https://shiki.style/)

## Conclusions

**Our mission at Nuxt is not only to make a better framework for developers, but also to make the entire frontend and web ecosystem a better place.** We are keeping pushing the boundaries and endorse the modern web standards and best practices. We hope you enjoy the new [Shiki](https://github.com/shikijs/shiki), [unwasm](https://github.com/unjs/unwasm), [Twoslash](https://github.com/twoslashes/twoslash) and many other tools we made in the process of making Nuxt and the web better.

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/show-error.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/show-error.md

# showError

> Nuxt provides a quick and simple way to show a full screen error page if needed.

Within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context) you can use `showError` to show an error.

**Parameters:**

- `error`: `string | Error | Partial<{ cause, data, message, name, stack, status, statusText }>`

```ts
showError('😱 Oh no, an error has been thrown.')
showError({
  status: 404,
  statusText: 'Page Not Found',
})
```

The error is set in the state using [`useError()`](/docs/4.x/api/composables/use-error) to create a reactive and SSR-friendly shared error state across components.

<tip>

`showError` calls the `app:error` hook.

</tip>

<read-more to="/docs/4.x/getting-started/error-handling">



</read-more>

---

# Source: https://nuxt.com/raw/deploy/sst.md

# SST

> Deploy your Nuxt Application to AWS with SST.

Nuxt supports deploying on [SST](https://sst.dev/) with minimal configuration.

## Quick start

1. Create a Nuxt project.
2. Init SST in your project.
```bash
npx sst@latest init
```
3. It should detect that your are using Nuxt and ask you to update your `nuxt.config.ts` file.
```ts
nitro: {
  preset: 'aws-lambda'
}
```
4. Once you are ready to deploy, run.
```bash
npx sst deploy --stage production
```

You can [read the full Nuxt on SST tutorial here](https://sst.dev/docs/start/aws/nuxt).

## More options

You can also deploy Nuxt to a container using SST. Head over to the [SST docs to learn more](https://sst.dev/docs/start/aws/nuxt).

---

# Source: https://nuxt.com/raw/docs/3.x/examples/features/state-management.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/state-management.md

# Source: https://nuxt.com/raw/docs/4.x/examples/features/state-management.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/state-management.md

# State Management

> Nuxt provides powerful state management libraries and the useState composable to create a reactive and SSR-friendly shared state.

Nuxt provides the [`useState`](/docs/4.x/api/composables/use-state) composable to create a reactive and SSR-friendly shared state across components.

[`useState`](/docs/4.x/api/composables/use-state) is an SSR-friendly [`ref`](https://vuejs.org/api/reactivity-core#ref) replacement. Its value will be preserved after server-side rendering (during client-side hydration) and shared across all components using a unique key.

<video-accordion title="Watch a video from Alexander Lichter about why and when to use useState" video-id="mv0WcBABcIk">



</video-accordion>

<important>

Because the data inside [`useState`](/docs/4.x/api/composables/use-state) will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.

</important>

<read-more to="/docs/4.x/api/composables/use-state">

Read more about `useState` composable.

</read-more>

## Best Practices

<warning>

Never define `const state = ref()` outside of `<script setup>` or `setup()` function.<br />


For example, doing `export myState = ref({})` would result in state shared across requests on the server and can lead to memory leaks.

</warning>

<tip icon="i-lucide-circle-check">

Instead use `const useX = () => useState('x')`

</tip>

## Examples

### Basic Usage

In this example, we use a component-local counter state. Any other component that uses `useState('counter')` shares the same reactive state.

```vue [app/app.vue]twoslash
<script setup lang="ts">
const counter = useState('counter', () => Math.round(Math.random() * 1000))
</script>

<template>
  <div>
    Counter: {{ counter }}
    <button @click="counter++">
      +
    </button>
    <button @click="counter--">
      -
    </button>
  </div>
</template>
```

<link-example to="/docs/4.x/examples/features/state-management">



</link-example>

<note>

To globally invalidate cached state, see [`clearNuxtState`](/docs/4.x/api/utils/clear-nuxt-state) util.

</note>

### Initializing State

Most of the time, you will want to initialize your state with data that resolves asynchronously. You can use the [`app.vue`](/docs/4.x/directory-structure/app/app) component with the [`callOnce`](/docs/4.x/api/utils/call-once) util to do so.

```vue [app/app.vue]twoslash
<script setup lang="ts">
const websiteConfig = useState('config')

await callOnce(async () => {
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>
```

<tip>

This is similar to the [`nuxtServerInit` action](https://v2.nuxt.com/docs/directory-structure/store/#the-nuxtserverinit-action) in Nuxt 2, which allows filling the initial state of your store server-side before rendering the page.

</tip>

<read-more to="/docs/4.x/api/utils/call-once">



</read-more>

### Usage with Pinia

In this example, we leverage the [Pinia module](/modules/pinia) to create a global store and use it across the app.

<important>

Make sure to install the Pinia module with `npx nuxt module add pinia` or follow the [module's installation steps](https://pinia.vuejs.org/ssr/nuxt.html#Installation).

</important>

<code-group>

```ts [app/stores/website.ts]
export const useWebsiteStore = defineStore('websiteStore', {
  state: () => ({
    name: '',
    description: '',
  }),
  actions: {
    async fetch () {
      const infos = await $fetch('https://api.nuxt.com/modules/pinia')

      this.name = infos.name
      this.description = infos.description
    },
  },
})
```

```vue [app/app.vue]
<script setup lang="ts">
const website = useWebsiteStore()

await callOnce(website.fetch)
</script>

<template>
  <main>
    <h1>{{ website.name }}</h1>
    <p>{{ website.description }}</p>
  </main>
</template>
```

</code-group>

## Advanced Usage

<code-group>

```ts [app/composables/locale.ts]
import type { Ref } from 'vue'

export const useLocale = () => {
  return useState<string>('locale', () => useDefaultLocale().value)
}

export const useDefaultLocale = (fallback = 'en-US') => {
  const locale = ref(fallback)
  if (import.meta.server) {
    const reqLocale = useRequestHeaders()['accept-language']?.split(',')[0]
    if (reqLocale) {
      locale.value = reqLocale
    }
  } else if (import.meta.client) {
    const navLang = navigator.language
    if (navLang) {
      locale.value = navLang
    }
  }
  return locale
}

export const useLocales = () => {
  const locale = useLocale()
  const locales = ref([
    'en-US',
    'en-GB',
    // ...,
    'ja-JP-u-ca-japanese',
  ])
  if (!locales.value.includes(locale.value)) {
    locales.value.unshift(locale.value)
  }
  return locales
}

export const useLocaleDate = (date: Ref<Date> | Date, locale = useLocale()) => {
  return computed(() => new Intl.DateTimeFormat(locale.value, { dateStyle: 'full' }).format(unref(date)))
}
```

```vue [app/app.vue]
<script setup lang="ts">
const locales = useLocales()
const locale = useLocale()
const date = useLocaleDate(new Date('2016-10-26'))
</script>

<template>
  <div>
    <h1>Nuxt birthday</h1>
    <p>{{ date }}</p>
    <label for="locale-chooser">Preview a different locale</label>
    <select
      id="locale-chooser"
      v-model="locale"
    >
      <option
        v-for="loc of locales"
        :key="loc"
        :value="loc"
      >
        {{ loc }}
      </option>
    </select>
  </div>
</template>
```

</code-group>

<link-example to="/docs/4.x/examples/advanced/locale">



</link-example>

## Shared State

By using [auto-imported composables](/docs/4.x/directory-structure/app/composables) we can define global type-safe states and import them across the app.

```ts [composables/states.ts]twoslash
export const useColor = () => useState<string>('color', () => 'pink')
```

```vue [app/app.vue]
<script setup lang="ts">
// ---cut-start---
const useColor = () => useState<string>('color', () => 'pink')
// ---cut-end---
const color = useColor() // Same as useState('color')
</script>

<template>
  <p>Current color: {{ color }}</p>
</template>
```

<video-accordion title="Watch a video from Daniel Roe on how to deal with global state and SSR in Nuxt" video-id="dZSNW07sO-A">



</video-accordion>

## Using third-party libraries

Nuxt **used to rely** on the Vuex library to provide global state management. If you are migrating from Nuxt 2, please head to [the migration guide](/docs/4.x/migration/configuration#vuex).

Nuxt is not opinionated about state management, so feel free to choose the right solution for your needs. There are multiple integrations with the most popular state management libraries, including:

- [Pinia](/modules/pinia) - the official Vue recommendation
- [Harlem](/modules/harlem) - immutable global state management
- [XState](/modules/xstate) - state machine approach with tools for visualizing and testing your state logic

---

# Source: https://nuxt.com/raw/deploy/stormkit.md

# Stormkit

> Deploy your Nuxt Application to Stormkit infrastructure.

<tip>

**Zero Configuration ✨**

<br />

Integration with [Stormkit](https://www.stormkit.io/) is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

## Setup

Follow the steps to [create a new app](https://app.stormkit.io/apps/new) on Stormkit.

## Deployment

By default, Stormkit will deploy your apps automatically when you push changes to your main branch. But to trigger a manual deploy (for example, you might do this for the very first deployment), you may click `Deploy now`.

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/stormkit">

Head over **Nitro documentation** to learn more about the stormkit deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/styling.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/styling.md

# Styling

> Learn how to style your Nuxt application.

Nuxt is highly flexible when it comes to styling. Write your own styles, or reference local and external stylesheets.
You can use CSS preprocessors, CSS frameworks, UI libraries and Nuxt modules to style your application.

## Local Stylesheets

If you're writing local stylesheets, the natural place to put them is the [`app/assets/` directory](/docs/4.x/directory-structure/app/assets).

### Importing Within Components

You can import stylesheets in your pages, layouts and components directly.
You can use a JavaScript import, or a CSS [`@import` statement](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@import).

```vue [app/pages/index.vue]
<script>
// Use a static import for server-side compatibility
import '~/assets/css/first.css'

// Caution: Dynamic imports are not server-side compatible
import('~/assets/css/first.css')
</script>

<style>
@import url("~/assets/css/second.css");
</style>
```

<tip>

The stylesheets will be inlined in the HTML rendered by Nuxt.

</tip>

### The CSS Property

You can also use the `css` property in the Nuxt configuration.
The natural place for your stylesheets is the [`app/assets/` directory](/docs/4.x/directory-structure/app/assets). You can then reference its path and Nuxt will include it to all the pages of your application.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
})
```

<tip>

The stylesheets will be inlined in the HTML rendered by Nuxt, injected globally and present in all pages.

</tip>

### Working With Fonts

Place your local fonts files in your `public/` directory, for example in `public/fonts`. You can then reference them in your stylesheets using `url()`.

```css [assets/css/main.css]
@font-face {
  font-family: 'FarAwayGalaxy';
  src: url('/fonts/FarAwayGalaxy.woff') format('woff');
  font-weight: normal;
  font-style: normal;
  font-display: swap;
}
```

Then reference your fonts by name in your stylesheets, pages or components:

```vue
<style>
h1 {
  font-family: 'FarAwayGalaxy', sans-serif;
}
</style>
```

### Stylesheets Distributed Through NPM

You can also reference stylesheets that are distributed through npm. Let's use the popular `animate.css` library as an example.

<code-group sync="pm">

```bash [npm]
npm install animate.css
```

```bash [yarn]
yarn add animate.css
```

```bash [pnpm]
pnpm install animate.css
```

```bash [bun]
bun install animate.css
```

```bash [deno]
deno install npm:animate.css
```

</code-group>

Then you can reference it directly in your pages, layouts and components:

```vue [app/app.vue]
<script>
import 'animate.css'
</script>

<style>
@import url("animate.css");
</style>
```

The package can also be referenced as a string in the css property of your Nuxt configuration.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  css: ['animate.css'],
})
```

## External Stylesheets

You can include external stylesheets in your application by adding a link element in the head section of your nuxt.config file. You can achieve this result using different methods. Note that local stylesheets can also be included this way.

You can manipulate the head with the [`app.head`](/docs/4.x/api/nuxt-config#head) property of your Nuxt configuration:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    head: {
      link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }],
    },
  },
})
```

### Dynamically Adding Stylesheets

You can use the useHead composable to dynamically set a value in your head in your code.

<read-more to="/docs/4.x/api/composables/use-head">



</read-more>

```tstwoslash
useHead({
  link: [{ rel: 'stylesheet', href: 'https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css' }],
})
```

Nuxt uses `unhead` under the hood, and you can refer to [its full documentation](https://unhead.unjs.io).

### Modifying The Rendered Head With A Nitro Plugin

If you need more advanced control, you can intercept the rendered html with a hook and modify the head programmatically.

Create a plugin in `~/server/plugins/my-plugin.ts` like this:

```ts [server/plugins/my-plugin.ts]
export default defineNitroPlugin((nitro) => {
  nitro.hooks.hook('render:html', (html) => {
    html.head.push('<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">')
  })
})
```

External stylesheets are render-blocking resources: they must be loaded and processed before the browser renders the page. Web pages that contain unnecessarily large styles take longer to render. You can read more about it on [web.dev](https://web.dev/articles/defer-non-critical-css).

## Using Preprocessors

To use a preprocessor like SCSS, Sass, Less or Stylus, install it first.

<code-group>

```bash [Sass & SCSS]
npm install -D sass
```

```bash [Less]
npm install -D less
```

```bash [Stylus]
npm install -D stylus
```

</code-group>

The natural place to write your stylesheets is the `app/assets` directory.
You can then import your source files in your `app.vue` (or layouts files) using your preprocessor's syntax.

```vue [app/pages/app.vue]
<style lang="scss">
@use "~/assets/scss/main.scss";
</style>
```

Alternatively, you can use the `css` property of your Nuxt configuration.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  css: ['~/assets/scss/main.scss'],
})
```

<tip>

In both cases, the compiled stylesheets will be inlined in the HTML rendered by Nuxt.

</tip>

If you need to inject code in pre-processed files, like a [Sass partial](https://sass-lang.com/documentation/at-rules/use/#partials) with color variables, you can do so with the Vite [preprocessors options](https://vite.dev/config/shared-options#css-preprocessoroptions).

Create some partials in your `app/assets` directory:

<code-group sync="preprocessor">

```scss [assets/_colors.scss]
$primary: #49240F;
$secondary: #E4A79D;
```

```sass [assets/_colors.sass]
$primary: #49240F
$secondary: #E4A79D
```

</code-group>

Then in your `nuxt.config` :

<code-group>

```ts [SCSS]twoslash
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: {
          additionalData: '@use "~/assets/_colors.scss" as *;',
        },
      },
    },
  },
})
```

```ts [SASS]twoslash
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorOptions: {
        sass: {
          additionalData: '@use "~/assets/_colors.sass" as *\n',
        },
      },
    },
  },
})
```

</code-group>

Nuxt uses Vite by default. If you wish to use webpack instead, refer to each preprocessor loader [documentation](https://webpack.js.org/loaders/sass-loader/).

### Preprocessor Workers (Experimental)

Vite has made available an [experimental option](https://vite.dev/config/shared-options#css-preprocessormaxworkers) which can speed up using preprocessors.

You can enable this in your `nuxt.config`:

```ts
export default defineNuxtConfig({
  vite: {
    css: {
      preprocessorMaxWorkers: true, // number of CPUs minus 1
    },
  },
})
```

<note>

This is an experimental option and you should refer to the Vite documentation and [provide feedback](https://github.com/vitejs/vite/discussions/15835).

</note>

## Single File Components (SFC) Styling

One of the best things about Vue and SFC is how great it is at naturally dealing with styling. You can directly write CSS or preprocessor code in the style block of your components file, therefore you will have fantastic developer experience without having to use something like CSS-in-JS. However if you wish to use CSS-in-JS, you can find 3rd party libraries and modules that support it, such as [pinceau](https://github.com/Tahul/pinceau).

You can refer to the [Vue docs](https://vuejs.org/api/sfc-css-features) for a comprehensive reference about styling components in SFC.

### Class And Style Bindings

You can leverage Vue SFC features to style your components with class and style attributes.

<code-group>

```vue [Ref and Reactive]
<script setup lang="ts">
const isActive = ref(true)
const hasError = ref(false)
const classObject = reactive({
  'active': true,
  'text-danger': false,
})
</script>

<template>
  <div
    class="static"
    :class="{ 'active': isActive, 'text-danger': hasError }"
  />
  <div :class="classObject" />
</template>
```

```vue [Computed]
<script setup lang="ts">
const isActive = ref(true)
const error = ref(null)

const classObject = computed(() => ({
  'active': isActive.value && !error.value,
  'text-danger': error.value && error.value.type === 'fatal',
}))
</script>

<template>
  <div :class="classObject" />
</template>
```

```vue [Array]
<script setup lang="ts">
const isActive = ref(true)
const errorClass = ref('text-danger')
</script>

<template>
  <div :class="[{ active: isActive }, errorClass]" />
</template>
```

```vue [Style]
<script setup lang="ts">
const activeColor = ref('red')
const fontSize = ref(30)
const styleObject = reactive({ color: 'red', fontSize: '13px' })
</script>

<template>
  <div :style="{ color: activeColor, fontSize: fontSize + 'px' }" />
  <div :style="[baseStyles, overridingStyles]" />
  <div :style="styleObject" />
</template>
```

</code-group>

Refer to the [Vue docs](https://vuejs.org/guide/essentials/class-and-style) for more information.

### Dynamic Styles With `v-bind`

You can reference JavaScript variable and expression within your style blocks with the v-bind function.
The binding will be dynamic, meaning that if the variable value changes, the style will be updated.

```vue
<script setup lang="ts">
const color = ref('red')
</script>

<template>
  <div class="text">
    hello
  </div>
</template>

<style>
.text {
  color: v-bind(color);
}
</style>
```

### Scoped Styles

The scoped attribute allows you to style components in isolation. The styles declared with this attribute will only apply to this component.

```vue
<template>
  <div class="example">
    hi
  </div>
</template>

<style scoped>
.example {
  color: red;
}
</style>
```

### CSS Modules

You can use [CSS Modules](https://github.com/css-modules/css-modules) with the module attribute. Access it with the injected `$style` variable.

```vue
<template>
  <p :class="$style.red">
    This should be red
  </p>
</template>

<style module>
.red {
  color: red;
}
</style>
```

### Preprocessors Support

SFC style blocks support preprocessor syntax. Vite comes with built-in support for .scss, .sass, .less, .styl and .stylus files without configuration. You just need to install them first, and they will be available directly in SFC with the lang attribute.

<code-group>

```vue [SCSS]
<style lang="scss">
  /* Write scss here */
</style>
```

```vue [Sass]
<style lang="sass">
  /* Write sass here */
</style>
```

```vue [LESS]
<style lang="less">
  /* Write less here */
</style>
```

```vue [Stylus]
<style lang="stylus">
  /* Write stylus here */
</style>
```

</code-group>

You can refer to the [Vite CSS docs](https://vite.dev/guide/features#css) and the [@vitejs/plugin-vue docs](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue).
For webpack users, refer to the [vue loader docs](https://vue-loader.vuejs.org).

## Using PostCSS

Nuxt comes with postcss built-in. You can configure it in your `nuxt.config` file.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  postcss: {
    plugins: {
      'postcss-nested': {},
      'postcss-custom-media': {},
    },
  },
})
```

For proper syntax highlighting in SFC, you can use the postcss lang attribute.

```vue
<style lang="postcss">
  /* Write postcss here */
</style>
```

By default, Nuxt comes with the following plugins already pre-configured:

- [postcss-import](https://github.com/postcss/postcss-import): Improves the `@import` rule
- [postcss-url](https://github.com/postcss/postcss-url): Transforms `url()` statements
- [autoprefixer](https://github.com/postcss/autoprefixer): Automatically adds vendor prefixes
- [cssnano](https://cssnano.github.io/cssnano/): Minification and purge

## Leveraging Layouts For Multiple Styles

If you need to style different parts of your application completely differently, you can use layouts.
Use different styles for different layouts.

```vue
<template>
  <div class="default-layout">
    <h1>Default Layout</h1>
    <slot />
  </div>
</template>

<style>
.default-layout {
  color: red;
}
</style>
```

<read-more to="/docs/4.x/directory-structure/app/layouts">



</read-more>

## Third Party Libraries And Modules

Nuxt isn't opinionated when it comes to styling and provides you with a wide variety of options. You can use any styling tool that you want, such as popular libraries like [UnoCSS](https://unocss.dev) or [Tailwind CSS](https://tailwindcss.com).

The community and the Nuxt team have developed plenty of Nuxt modules to make the integration easier.
You can discover them on the [modules section](/modules) of the website.
Here are a few modules to help you get started:

- [UnoCSS](/modules/unocss): Instant on-demand atomic CSS engine
- [Tailwind CSS](/modules/tailwindcss): Utility-first CSS framework
- [Fontaine](https://github.com/nuxt-modules/fontaine): Font metric fallback
- [Pinceau](https://github.com/Tahul/pinceau): Adaptable styling framework
- [Nuxt UI](https://ui.nuxt.com): A UI Library for Modern Web Apps
- [Panda CSS](https://panda-css.com/docs/installation/nuxt): CSS-in-JS engine that generates atomic CSS at build time

Nuxt modules provide you with a good developer experience out of the box, but remember that if your favorite tool doesn't have a module, it doesn't mean that you can't use it with Nuxt! You can configure it yourself for your own project. Depending on the tool, you might need to use a [Nuxt plugin](/docs/4.x/directory-structure/app/plugins) and/or [make your own module](/docs/4.x/guide/modules). Share them with the [community](/modules) if you do!

### Easily Load Webfonts

You can use [the Nuxt Google Fonts module](https://github.com/nuxt-modules/google-fonts) to load Google Fonts.

If you are using [UnoCSS](https://unocss.dev/integrations/nuxt), note that it comes with a [web fonts presets](https://unocss.dev/presets/web-fonts) to conveniently load fonts from common providers, including Google Fonts and more.

## Advanced

### Transitions

Nuxt comes with the same `<Transition>` element that Vue has, and also has support for the experimental [View Transitions API](/docs/4.x/getting-started/transitions#view-transitions-api-experimental).

<read-more to="/docs/4.x/getting-started/transitions">



</read-more>

### Font Advanced Optimization

We would recommend using [Fontaine](https://github.com/nuxt-modules/fontaine) to reduce your [CLS](https://web.dev/articles/cls). If you need something more advanced, consider creating a Nuxt module to extend the build process or the Nuxt runtime.

<tip>

Always remember to take advantage of the various tools and techniques available in the Web ecosystem at large to make styling your application easier and more efficient. Whether you're using native CSS, a preprocessor, postcss, a UI library or a module, Nuxt has got you covered. Happy styling!

</tip>

### LCP Advanced Optimizations

You can do the following to speed-up the download of your global CSS files:

- Use a CDN so the files are physically closer to your users
- Compress your assets, ideally using Brotli
- Use HTTP2/HTTP3 for delivery
- Host your assets on the same domain (do not use a different subdomain)

Most of these things should be done for you automatically if you're using modern platforms like Cloudflare, Netlify or Vercel.
You can find an LCP optimization guide on [web.dev](https://web.dev/articles/optimize-lcp).

If all of your CSS is inlined by Nuxt, you can (experimentally) completely stop external CSS files from being referenced in your rendered HTML.
You can achieve that with a hook, that you can place in a module, or in your Nuxt configuration file.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  hooks: {
    'build:manifest': (manifest) => {
      // find the app entry, css list
      const css = Object.values(manifest).find(options => options.isEntry)?.css
      if (css) {
        // start from the end of the array and go to the beginning
        for (let i = css.length - 1; i >= 0; i--) {
          // if it starts with 'entry', remove it from the list
          if (css[i].startsWith('entry')) {
            css.splice(i, 1)
          }
        }
      }
    },
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/teleport.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/teleport.md

# Teleport

> This example shows how to use the <Teleport> with client-side and server-side rendering.

Vue 3 provides the [`<Teleport>` component](https://vuejs.org/guide/built-ins/teleport.html) which allows content to be rendered elsewhere in the DOM, outside of the Vue application.

This example shows how to use the `<Teleport>` with client-side and server-side rendering.

<read-more to="/docs/api/components/teleports">



</read-more>

<sandbox branch="main" dir="examples/advanced/teleport" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/api/components/teleports.md

# Source: https://nuxt.com/raw/docs/4.x/api/components/teleports.md

# <Teleport>

> The <Teleport> component teleports a component to a different location in the DOM.

<warning>

The `to` target of [`<Teleport>`](https://vuejs.org/guide/built-ins/teleport) expects a CSS selector string or an actual DOM node. Nuxt currently has SSR support for teleports to `#teleports` only, with client-side support for other targets using a `<ClientOnly>` wrapper.

</warning>

## Body Teleport

```vue
<template>
  <button @click="open = true">
    Open Modal
  </button>
  <Teleport to="#teleports">
    <div
      v-if="open"
      class="modal"
    >
      <p>Hello from the modal!</p>
      <button @click="open = false">
        Close
      </button>
    </div>
  </Teleport>
</template>
```

## Client-side Teleport

```vue
<template>
  <ClientOnly>
    <Teleport to="#some-selector">
      <!-- content -->
    </Teleport>
  </ClientOnly>
</template>
```

<link-example to="/docs/4.x/examples/advanced/teleport">



</link-example>

---

# Source: https://nuxt.com/raw/docs/3.x/api/kit/templates.md

# Source: https://nuxt.com/raw/docs/4.x/api/kit/templates.md

# Templates

> Nuxt Kit provides a set of utilities to help you work with templates. These functions allow you to generate extra files during development and build time.

Templates allow you to generate extra files during development and build time. These files will be available in virtual filesystem and can be used in plugins, layouts, components, etc. `addTemplate` and `addTypeTemplate` allow you to add templates to the Nuxt application. `updateTemplates` allows you to regenerate templates that match the filter.

## `addTemplate`

Renders given template during build into the virtual file system, and optionally to disk in the project `buildDir`

### Usage

```tstwoslash
import { addTemplate, defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    const globalMeta = defu(nuxt.options.app.head, {
      charset: options.charset,
      viewport: options.viewport,
    })

    addTemplate({
      filename: 'meta.config.mjs',
      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
    })
  },
})
```

### Type

```tstwoslash
// @errors: 2391
import type { NuxtTemplate, ResolvedNuxtTemplate } from '@nuxt/schema'
// ---cut---
function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate
```

### Parameters

**template**: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        src
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path to the template. If <code>
        src
      </code>
      
       is not provided, <code>
        getContents
      </code>
      
       must be provided instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filename
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Filename of the template. If <code>
        filename
      </code>
      
       is not provided, it will be generated from the <code>
        src
      </code>
      
       path. In this case, the <code>
        src
      </code>
      
       option is required.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dst
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path to the destination file. If <code>
        dst
      </code>
      
       is not provided, it will be generated from the <code>
        filename
      </code>
      
       path and nuxt <code>
        buildDir
      </code>
      
       option.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        Options
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Options to pass to the template.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        getContents
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          data
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Options
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="s52Pk">
          Promise
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      A function that will be called with the <code>
        options
      </code>
      
       object. It should return a string or a promise that resolves to a string. If <code>
        src
      </code>
      
       is provided, this function will be ignored.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        write
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the template will be written to the destination file. Otherwise, the template will be used only in virtual filesystem.
    </td>
  </tr>
</tbody>
</table>

### Examples

#### Creating a Virtual File for Runtime Plugin

In this example, we merge an object inside a module and consume the result in a runtime plugin.

```ts [module.ts]twoslash
import { addTemplate, defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    const globalMeta = defu(nuxt.options.app.head, {
      charset: options.charset,
      viewport: options.viewport,
    })

    addTemplate({
      filename: 'meta.config.mjs',
      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
    })
  },
})
```

In the module above, we generate a virtual file named `meta.config.mjs`. In the runtime plugin, we can import it using the `#build` alias:

```ts [runtime/plugin.ts]
import { createHead as createServerHead } from '@unhead/vue/server'
import { createHead as createClientHead } from '@unhead/vue/client'
import { defineNuxtPlugin } from '#imports'
// @ts-expect-error - virtual file
import metaConfig from '#build/meta.config.mjs'

export default defineNuxtPlugin((nuxtApp) => {
  const createHead = import.meta.server ? createServerHead : createClientHead
  const head = createHead()
  head.push(metaConfig.globalMeta)

  nuxtApp.vueApp.use(head)
})
```

## `addTypeTemplate`

Renders given template during build into the project buildDir, then registers it as types.

### Usage

```tstwoslash
import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addTypeTemplate({
      filename: 'types/markdown.d.ts',
      getContents: () => `declare module '*.md' {
  import type { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}`,
    })
  },
})
```

### Type

```ts
function addTypeTemplate (template: NuxtTypeTemplate | string, context?: { nitro?: boolean, nuxt?: boolean }): ResolvedNuxtTemplate
```

### Parameters

**template**: A template object or a string with the path to the template. If a string is provided, it will be converted to a template object with `src` set to the string value. If a template object is provided, it must have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        src
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path to the template. If <code>
        src
      </code>
      
       is not provided, <code>
        getContents
      </code>
      
       must be provided instead.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        filename
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Filename of the template. If <code>
        filename
      </code>
      
       is not provided, it will be generated from the <code>
        src
      </code>
      
       path. In this case, the <code>
        src
      </code>
      
       option is required.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dst
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Path to the destination file. If <code>
        dst
      </code>
      
       is not provided, it will be generated from the <code>
        filename
      </code>
      
       path and nuxt <code>
        buildDir
      </code>
      
       option.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        Options
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Options to pass to the template.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        getContents
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          data
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          Options
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="s52Pk">
          Promise
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      A function that will be called with the <code>
        options
      </code>
      
       object. It should return a string or a promise that resolves to a string. If <code>
        src
      </code>
      
       is provided, this function will be ignored.
    </td>
  </tr>
</tbody>
</table>

**context**: An optional context object can be passed to control where the type is added. If omitted, the type will only be added to the Nuxt context. This object supports the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        nuxt
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the type will be added to the Nuxt context.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nitro
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If set to <code>
        true
      </code>
      
      , the type will be added to the Nitro context.
    </td>
  </tr>
</tbody>
</table>

### Examples

#### Adding Type Templates to the Nitro Context

By default, －－ only adds the type declarations to the Nuxt context. To also add them to the Nitro context, set nitro to true.

```tstwoslash
import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addTypeTemplate({
      filename: 'types/auth.d.ts',
      getContents: () => `declare module '#auth-utils' {
  interface User {
    id: string;
    name: string;
  }

}`,
    }, {
      nitro: true,
    })
  },
})
```

This allows the `#auth-utils` module to be used within the Nitro context.

```ts [server/api/auth.ts]
import type { User } from '#auth-utils'

export default eventHandler(() => {
  const user: User = {
    id: '123',
    name: 'John Doe',
  }

  // do something with the user

  return user
})
```

## `addServerTemplate`

Adds a virtual file that can be used within the Nuxt Nitro server build.

### Usage

```tstwoslash
import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })
  },
})
```

### Type

```tstwoslash
// @errors: 2391
import type { NuxtServerTemplate } from '@nuxt/schema'
// ---cut---
function addServerTemplate (template: NuxtServerTemplate): NuxtServerTemplate
```

### Parameters

**template**: A template object. It must have the following properties:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        filename
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Filename of the template.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        getContents
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          ()
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          |
        </span>
        
        <span class="s52Pk">
          Promise
        </span>
        
        <span class="sDfIl">
          <
        </span>
        
        <span class="sZSNi">
          string
        </span>
        
        <span class="sDfIl">
          >
        </span>
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      A function that will be called with the <code>
        options
      </code>
      
       object. It should return a string or a promise that resolves to a string.
    </td>
  </tr>
</tbody>
</table>

### Examples

### Creating a Virtual File for Nitro

In this example, we create a virtual file that can be used within the Nuxt Nitro server build.

```tstwoslash
import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })
  },
})
```

And then in a runtime file

```ts [server/api/test.ts]
import { test } from '#my-module/test.js'

export default eventHandler(() => {
  return test
})
```

## `updateTemplates`

Regenerate templates that match the filter. If no filter is provided, all templates will be regenerated.

### Usage

```ts
import { defineNuxtModule, updateTemplates } from '@nuxt/kit'
import { resolve } from 'pathe'

export default defineNuxtModule({
  setup (options, nuxt) {
    const updateTemplatePaths = [
      resolve(nuxt.options.srcDir, 'pages'),
    ]
    // watch and rebuild routes template list when one of the pages changes
    nuxt.hook('builder:watch', async (event, relativePath) => {
      if (event === 'change') {
        return
      }

      const path = resolve(nuxt.options.srcDir, relativePath)
      if (updateTemplatePaths.some(dir => path.startsWith(dir))) {
        await updateTemplates({
          filter: template => template.filename === 'routes.mjs',
        })
      }
    })
  },
})
```

### Type

```ts
async function updateTemplates (options: UpdateTemplatesOptions): void
```

### Parameters

**options**: Options to pass to the template. This object can have the following property:

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        filter
      </code>
    </td>
    
    <td>
      <code className="language-ts shiki shiki-themes material-theme-lighter material-theme-lighter material-theme-palenight" language="ts" style="">
        <span class="sDfIl">
          (
        </span>
        
        <span class="s1nJG">
          template
        </span>
        
        <span class="sDfIl">
          :
        </span>
        
        <span class="s52Pk">
          ResolvedNuxtTemplate
        </span>
        
        <span class="sDfIl">
          )
        </span>
        
        <span class="smZ93">
          =>
        </span>
        
        <span class="sZSNi">
          boolean
        </span>
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      A function that will be called with the <code>
        template
      </code>
      
       object. It should return a boolean indicating whether the template should be regenerated. If <code>
        filter
      </code>
      
       is not provided, all templates will be regenerated.
    </td>
  </tr>
</tbody>
</table>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/test.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/test.md

# nuxt test

> The test command runs tests using @nuxt/test-utils.

```bash [Terminal]
npx nuxt test [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dev] [--watch]
```

The `test` command runs tests using [`@nuxt/test-utils`](/docs/4.x/getting-started/testing). This command sets `process.env.NODE_ENV` to `test` if not already set.

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dev
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Run in dev mode
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --watch
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Watch mode
    </td>
  </tr>
</tbody>
</table>

<note>

This command sets `process.env.NODE_ENV` to `test`.

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/testing.md

# Source: https://nuxt.com/raw/docs/3.x/guide/modules/testing.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/testing.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/testing.md

# Source: https://nuxt.com/raw/docs/4.x/guide/modules/testing.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/testing.md

# Testing

> How to test your Nuxt application.

<tip>

If you are a module author, you can find more specific information in the [Module Author's guide](/docs/4.x/guide/modules/testing).

</tip>

Nuxt offers first-class support for end-to-end and unit testing of your Nuxt application via `@nuxt/test-utils`, a library of test utilities and configuration that currently powers the [tests we use on Nuxt itself](https://github.com/nuxt/nuxt/tree/main/test) and tests throughout the module ecosystem.

<video-accordion title="Watch a video from Alexander Lichter about getting started with @nuxt/test-utils" video-id="yGzwk9xi9gU">



</video-accordion>

## Installation

In order to allow you to manage your other testing dependencies, `@nuxt/test-utils` ships with various optional peer dependencies. For example:

- you can choose between `happy-dom` and `jsdom` for a runtime Nuxt environment
- you can choose between `vitest`, `cucumber`, `jest` and `playwright` for end-to-end test runners
- `playwright-core` is only required if you wish to use the built-in browser testing utilities (and are not using `@playwright/test` as your test runner)

<code-group sync="pm">

```bash [npm]
npm i --save-dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core
```

```bash [yarn]
yarn add --dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core
```

```bash [pnpm]
pnpm add -D @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core
```

```bash [bun]
bun add --dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core
```

</code-group>

## Unit Testing

We currently ship an environment for unit testing code that needs a [Nuxt](https://nuxt.com) runtime environment. It currently *only has support for vitest* (although contribution to add other runtimes would be welcome).

### Setup

1. Add `@nuxt/test-utils/module` to your `nuxt.config` file (optional). It adds a Vitest integration to your Nuxt DevTools which supports running your unit tests in development.```tstwoslash
export default defineNuxtConfig({
  modules: [
    '@nuxt/test-utils/module',
  ],
})
```
2. Create a `vitest.config.ts` with the following content:```tstwoslash
import { defineConfig } from 'vitest/config'
import { defineVitestProject } from '@nuxt/test-utils/config'

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'unit',
          include: ['test/unit/*.{test,spec}.ts'],
          environment: 'node',
        },
      },
      {
        test: {
          name: 'e2e',
          include: ['test/e2e/*.{test,spec}.ts'],
          environment: 'node',
        },
      },
      await defineVitestProject({
        test: {
          name: 'nuxt',
          include: ['test/nuxt/*.{test,spec}.ts'],
          environment: 'nuxt',
        },
      }),
    ],
  },
})
```

<tip>

When importing `@nuxt/test-utils` in your vitest config, It is necessary to have `"type": "module"` specified in your `package.json` or rename your vitest config file appropriately.

> i.e., `vitest.config.m{ts,js}`.

</tip>

<tip>

It is possible to set environment variables for testing by using the `.env.test` file.

</tip>

### Using a Nuxt Runtime Environment

Using [Vitest projects](https://vitest.dev/guide/projects.html#test-projects), you have fine-grained control over which tests run in which environment:

- **Unit tests**: Place regular unit tests in `test/unit/` - these run in a Node environment for speed
- **Nuxt tests**: Place tests that rely on the Nuxt runtime environment in `test/nuxt/` - these will run within a Nuxt runtime environment

#### Alternative: Simple Setup

If you prefer a simpler setup and want all tests to run in the Nuxt environment, you can use the basic configuration:

```tstwoslash
import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    // you can optionally set Nuxt-specific environment options
    // environmentOptions: {
    //   nuxt: {
    //     rootDir: fileURLToPath(new URL('./playground', import.meta.url)),
    //     domEnvironment: 'happy-dom', // 'happy-dom' (default) or 'jsdom'
    //     overrides: {
    //       // other Nuxt config you want to pass
    //     }
    //   }
    // }
  },
})
```

If you're using the simple setup with `environment: 'nuxt'` by default, you can opt *out* of the [Nuxt environment](https://vitest.dev/guide/environment.html#test-environment) per test file as needed.

```tstwoslash
// @vitest-environment node
import { test } from 'vitest'

test('my test', () => {
  // ... test without Nuxt environment!
})
```

<warning>

This approach is not recommended as it creates a hybrid environment where Nuxt Vite plugins run but the Nuxt entry and `nuxtApp` are not initialized. This can lead to hard-to-debug errors.

</warning>

### Organizing Your Tests

With the project-based setup, you might organize your tests as follows:

```bash [Directory structure]
test/
├── e2e/
│   └── ssr.test.ts
├── nuxt/
│   ├── components.test.ts
│   └── composables.test.ts
├── unit/
│   └── utils.test.ts
```

You can of course opt for any test structure, but keeping the Nuxt runtime environment separated from Nuxt end-to-end tests is important for test stability.

#### TypeScript Support in Tests

By default, test files in `test/nuxt/` and `tests/nuxt/` directories are included in the [Nuxt app TypeScript context](/docs/4.x/guide/concepts/typescript#how-nuxt-uses-project-references). That means they will recognise Nuxt aliases (like `~/`, `@/`, `#imports`) and TypeScript will be aware of auto-imports that work in your Nuxt app.

<tip>

This matches the recommended structure where only tests that need the Nuxt runtime environment are placed in these directories. Unit tests in other directories like `test/unit/` can be added manually if needed.

</tip>

##### Adding other test directories

If you have tests in other directories that you will be running in the Nuxt Vitest environment, you can include them in the Nuxt app TypeScript context by adding them to your configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      include: [
        // this path is relative to the generated .nuxt/tsconfig.json
        '../test/other-nuxt-context/**/*',
      ],
    },
  },
})
```

<important>

Unit tests should not depend on Nuxt runtime features like auto-imports or composables. Only add TypeScript path alias support if your tests import from your source files (e.g., `~/utils/helpers`), not for Nuxt-specific features.

</important>

#### Running Tests

With the project setup, you can run different test suites:

```bash
# Run all tests
npx vitest

# Run only unit tests
npx vitest --project unit

# Run only Nuxt tests
npx vitest --project nuxt

# Run tests in watch mode
npx vitest --watch
```

<warning>

When you run your tests within the Nuxt environment, they will be running in a [`happy-dom`](https://github.com/capricorn86/happy-dom) or [`jsdom`](https://github.com/jsdom/jsdom) environment. Before your tests run, a global Nuxt app will be initialized (including, for example, running any plugins or code you've defined in your `app.vue`).

This means you should take particular care not to mutate the global state in your tests (or, if you need to, to reset it afterwards).

</warning>

### 🎭 Built-In Mocks

`@nuxt/test-utils` provides some built-in mocks for the DOM environment.

#### `intersectionObserver`

Default `true`, creates a dummy class without any functionality for the IntersectionObserver API

#### `indexedDB`

Default `false`, uses [`fake-indexeddb`](https://github.com/dumbmatter/fakeIndexedDB) to create a functional mock of the IndexedDB API

These can be configured in the `environmentOptions` section of your `vitest.config.ts` file:

```tstwoslash
import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  test: {
    environmentOptions: {
      nuxt: {
        mock: {
          intersectionObserver: true,
          indexedDb: true,
        },
      },
    },
  },
})
```

### 🛠️ Helpers

`@nuxt/test-utils` provides a number of helpers to make testing Nuxt apps easier.

#### `mountSuspended`

`mountSuspended` allows you to mount any Vue component within the Nuxt environment, allowing async setup and access to injections from your Nuxt plugins.

<note>

Under the hood, `mountSuspended` wraps `mount` from `@vue/test-utils`, so you can check out [the Vue Test Utils documentation](https://test-utils.vuejs.org/guide/) for more on the options you can pass, and how to use this utility.

</note>

For example:

```tstwoslash
// @noErrors
import { expect, it } from 'vitest'
import type { Component } from 'vue'

declare module '#components' {
  export const SomeComponent: Component
}
// ---cut---
// tests/components/SomeComponents.nuxt.spec.ts
import { mountSuspended } from '@nuxt/test-utils/runtime'
import { SomeComponent } from '#components'

it('can mount some component', async () => {
  const component = await mountSuspended(SomeComponent)
  expect(component.text()).toMatchInlineSnapshot(
    '"This is an auto-imported component"',
  )
})
```

```tstwoslash
// @noErrors
import { expect, it } from 'vitest'
// ---cut---
// tests/components/SomeComponents.nuxt.spec.ts
import { mountSuspended } from '@nuxt/test-utils/runtime'
import App from '~/app.vue'

// tests/App.nuxt.spec.ts
it('can also mount an app', async () => {
  const component = await mountSuspended(App, { route: '/test' })
  expect(component.html()).toMatchInlineSnapshot(`
      "<div>This is an auto-imported component</div>
      <div> I am a global component </div>
      <div>/</div>
      <a href="/test"> Test link </a>"
    `)
})
```

#### `renderSuspended`

`renderSuspended` allows you to render any Vue component within the Nuxt environment using `@testing-library/vue`, allowing async setup and access to injections from your Nuxt plugins.

This should be used together with utilities from Testing Library, e.g. `screen` and `fireEvent`. Install [@testing-library/vue](https://testing-library.com/docs/vue-testing-library/intro/) in your project to use these.

Additionally, Testing Library also relies on testing globals for cleanup. You should turn these on in your [Vitest config](https://vitest.dev/config/globals).

The passed in component will be rendered inside a `<div id="test-wrapper"></div>`.

Examples:

```tstwoslash
// @noErrors
import { expect, it } from 'vitest'
import type { Component } from 'vue'

declare module '#components' {
  export const SomeComponent: Component
}
// ---cut---
// tests/components/SomeComponents.nuxt.spec.ts
import { renderSuspended } from '@nuxt/test-utils/runtime'
import { SomeComponent } from '#components'
import { screen } from '@testing-library/vue'

it('can render some component', async () => {
  await renderSuspended(SomeComponent)
  expect(screen.getByText('This is an auto-imported component')).toBeDefined()
})
```

```tstwoslash
// @noErrors
import { expect, it } from 'vitest'
// ---cut---
// tests/App.nuxt.spec.ts
import { renderSuspended } from '@nuxt/test-utils/runtime'
import App from '~/app.vue'

it('can also render an app', async () => {
  const html = await renderSuspended(App, { route: '/test' })
  expect(html).toMatchInlineSnapshot(`
    "<div id="test-wrapper">
      <div>This is an auto-imported component</div>
      <div> I am a global component </div>
      <div>Index page</div><a href="/test"> Test link </a>
    </div>"
  `)
})
```

#### `mockNuxtImport`

`mockNuxtImport` allows you to mock Nuxt's auto import functionality. For example, to mock `useStorage`, you can do so like this:

```tstwoslash
import { mockNuxtImport } from '@nuxt/test-utils/runtime'

mockNuxtImport('useStorage', () => {
  return () => {
    return { value: 'mocked storage' }
  }
})

// your tests here
```

<note>

`mockNuxtImport` can only be used once per mocked import per test file. It is actually a macro that gets transformed to `vi.mock` and `vi.mock` is hoisted, as described [in the Vitest docs](https://vitest.dev/api/vi#vi-mock).

</note>

If you need to mock a Nuxt import and provide different implementations between tests, you can do it by creating and exposing your mocks using [`vi.hoisted`](https://vitest.dev/api/vi#vi-hoisted), and then use those mocks in `mockNuxtImport`. You then have access to the mocked imports, and can change the implementation between tests. Be careful to [restore mocks](https://vitest.dev/api/mock#mockrestore) before or after each test to undo mock state changes between runs.

```tstwoslash
import { vi } from 'vitest'
import { mockNuxtImport } from '@nuxt/test-utils/runtime'

const { useStorageMock } = vi.hoisted(() => {
  return {
    useStorageMock: vi.fn(() => {
      return { value: 'mocked storage' }
    }),
  }
})

mockNuxtImport('useStorage', () => {
  return useStorageMock
})

// Then, inside a test
useStorageMock.mockImplementation(() => {
  return { value: 'something else' }
})
```

#### `mockComponent`

`mockComponent` allows you to mock Nuxt's component.
The first argument can be the component name in PascalCase, or the relative path of the component.
The second argument is a factory function that returns the mocked component.

For example, to mock `MyComponent`, you can:

```tstwoslash
import { mockComponent } from '@nuxt/test-utils/runtime'

mockComponent('MyComponent', {
  props: {
    value: String,
  },
  setup (props) {
    // ...
  },
})

// relative path or alias also works
mockComponent('~/components/my-component.vue', () => {
  // or a factory function
  return defineComponent({
    setup (props) {
      // ...
    },
  })
})

// or you can use SFC for redirecting to a mock component
mockComponent('MyComponent', () => import('./MockComponent.vue'))

// your tests here
```

> **Note**: You can't reference local variables in the factory function since they are hoisted. If you need to access Vue APIs or other variables, you need to import them in your factory function.

```tstwoslash
import { mockComponent } from '@nuxt/test-utils/runtime'

mockComponent('MyComponent', async () => {
  const { ref, h } = await import('vue')

  return defineComponent({
    setup (props) {
      const counter = ref(0)
      return () => h('div', null, counter.value)
    },
  })
})
```

#### `registerEndpoint`

`registerEndpoint` allows you create Nitro endpoint that returns mocked data. It can come in handy if you want to test a component that makes requests to API to display some data.

The first argument is the endpoint name (e.g. `/test/`).
The second argument is a factory function that returns the mocked data.

For example, to mock `/test/` endpoint, you can do:

```tstwoslash
import { registerEndpoint } from '@nuxt/test-utils/runtime'

registerEndpoint('/test/', () => ({
  test: 'test-field',
}))
```

By default, your request will be made using the `GET` method. You may use another method by setting an object as the second argument instead of a function.

```tstwoslash
import { registerEndpoint } from '@nuxt/test-utils/runtime'

registerEndpoint('/test/', {
  method: 'POST',
  handler: () => ({ test: 'test-field' }),
})
```

> **Note**: If your requests in a component go to an external API, you can use `baseURL` and then make it empty using [Nuxt Environment Override Config](/docs/4.x/getting-started/configuration#environment-overrides) (`$test`) so all your requests will go to Nitro server.

#### Conflict with End-To-End Testing

`@nuxt/test-utils/runtime` and `@nuxt/test-utils/e2e` need to run in different testing environments and so can't be used in the same file.

If you would like to use both the end-to-end and unit testing functionality of `@nuxt/test-utils`, you can split your tests into separate files. You then either specify a test environment per-file with the special `// @vitest-environment nuxt` comment, or name your runtime unit test files with the `.nuxt.spec.ts` extension.

`app.nuxt.spec.ts`

```tstwoslash
import { mockNuxtImport } from '@nuxt/test-utils/runtime'

mockNuxtImport('useStorage', () => {
  return () => {
    return { value: 'mocked storage' }
  }
})
```

`app.e2e.spec.ts`

```tstwoslash
import { $fetch, setup } from '@nuxt/test-utils/e2e'

await setup({
  setupTimeout: 10000,
})

// ...
```

### Using `@vue/test-utils`

If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and you are only testing components which do not rely on Nuxt composables, auto-imports or context, you can follow these steps to set it up.

1. Install the needed dependencies<code-group sync="pm">

```bash [npm]
npm i --save-dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
```

```bash [yarn]
yarn add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
```

```bash [pnpm]
pnpm add -D vitest @vue/test-utils happy-dom @vitejs/plugin-vue
```

```bash [bun]
bun add --dev vitest @vue/test-utils happy-dom @vitejs/plugin-vue
```

</code-group>
2. Create a `vitest.config.ts` with the following content:```ts
import { defineConfig } from 'vitest/config'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  test: {
    environment: 'happy-dom',
  },
})
```
3. Add a new command for test in your `package.json````json
"scripts": {
  "build": "nuxt build",
  "dev": "nuxt dev",
  ...
  "test": "vitest"
},
```
4. Create a simple `<HelloWorld>` component `app/components/HelloWorld.vue` with the following content:```vue
<template>
  <p>Hello world</p>
</template>
```
5. Create a simple unit test for this newly created component `~/components/HelloWorld.spec.ts````tstwoslash
import { describe, expect, it } from 'vitest'
import { mount } from '@vue/test-utils'

import HelloWorld from './HelloWorld.vue'

describe('HelloWorld', () => {
  it('component renders Hello world properly', () => {
    const wrapper = mount(HelloWorld)
    expect(wrapper.text()).toContain('Hello world')
  })
})
```
6. Run vitest command<code-group sync="pm">

```bash [npm]
npm run test
```

```bash [yarn]
yarn test
```

```bash [pnpm]
pnpm run test
```

```bash [bun]
bun run test
```

</code-group>

Congratulations, you're all set to start unit testing with `@vue/test-utils` in Nuxt! Happy testing!

## End-To-End Testing

For end-to-end testing, we support [Vitest](https://github.com/vitest-dev/vitest), [Jest](https://jestjs.io), [Cucumber](https://cucumber.io/) and [Playwright](https://playwright.dev/) as test runners.

### Setup

In each `describe` block where you are taking advantage of the `@nuxt/test-utils/e2e` helper methods, you will need to set up the test context before beginning.

```ts [test/my-test.spec.ts]twoslash
import { describe, test } from 'vitest'
import { $fetch, setup } from '@nuxt/test-utils/e2e'

describe('My test', async () => {
  await setup({
    // test context options
  })

  test('my test', () => {
    // ...
  })
})
```

Behind the scenes, `setup` performs a number of tasks in `beforeAll`, `beforeEach`, `afterEach` and `afterAll` to set up the Nuxt test environment correctly.

Please use the options below for the `setup` method.

#### Nuxt Config

- `rootDir`: Path to a directory with a Nuxt app to be put under test.

  - Type: `string`
  - Default: `'.'`
- `configFile`: Name of the configuration file.

  - Type: `string`
  - Default: `'nuxt.config'`

#### Timings

- `setupTimeout`: The amount of time (in milliseconds) to allow for `setupTest` to complete its work (which could include building or generating files for a Nuxt application, depending on the options that are passed).
  - Type: `number`
  - Default: `120000` or `240000` on windows
- `teardownTimeout`: The amount of time (in milliseconds) to allow tearing down the test environment, such as closing the browser.
  - Type: `number`
  - Default: `30000`

#### Features

- `build`: Whether to run a separate build step.
  - Type: `boolean`
  - Default: `true` (`false` if `browser` or `server` is disabled, or if a `host` is provided)
- `server`: Whether to launch a server to respond to requests in the test suite.
  - Type: `boolean`
  - Default: `true` (`false` if a `host` is provided)
- `port`: If provided, set the launched test server port to the value.
  - Type: `number | undefined`
  - Default: `undefined`
- `host`: If provided, a URL to use as the test target instead of building and running a new server. Useful for running "real" end-to-end tests against a deployed version of your application, or against an already running local server (which may provide a significant reduction in test execution timings). See the [target host end-to-end example below](/docs/4.x/getting-started/testing#target-host-end-to-end-example).
  - Type: `string`
  - Default: `undefined`
- `browser`: Under the hood, Nuxt test utils uses [`playwright`](https://playwright.dev) to carry out browser testing. If this option is set, a browser will be launched and can be controlled in the subsequent test suite.
  - Type: `boolean`
  - Default: `false`
- `browserOptions`
  - Type: `object` with the following properties
  
    - `type`: The type of browser to launch - either `chromium`, `firefox` or `webkit`
    - `launch`: `object` of options that will be passed to playwright when launching the browser. See [full API reference](https://playwright.dev/docs/api/class-browsertype#browser-type-launch).
- `runner`: Specify the runner for the test suite. Currently, [Vitest](https://vitest.dev) is recommended.
  - Type: `'vitest' | 'jest' | 'cucumber'`
  - Default: `'vitest'`

##### Target `host` end-to-end example

A common use-case for end-to-end testing is running the tests against a deployed application running in the same environment typically used for Production.

For local development or automated deploy pipelines, testing against a separate local server can be more efficient and is typically faster than allowing the test framework to rebuild between tests.

To utilize a separate target host for end-to-end tests, simply provide the `host` property of the `setup` function with the desired URL.

```ts
import { createPage, setup } from '@nuxt/test-utils/e2e'
import { describe, expect, it } from 'vitest'

describe('login page', async () => {
  await setup({
    host: 'http://localhost:8787',
  })

  it('displays the email and password fields', async () => {
    const page = await createPage('/login')
    expect(await page.getByTestId('email').isVisible()).toBe(true)
    expect(await page.getByTestId('password').isVisible()).toBe(true)
  })
})
```

### APIs

#### `$fetch(url)`

Get the HTML of a server-rendered page.

```tstwoslash
import { $fetch } from '@nuxt/test-utils/e2e'

const html = await $fetch('/')
```

#### `fetch(url)`

Get the response of a server-rendered page.

```tstwoslash
import { fetch } from '@nuxt/test-utils/e2e'

const res = await fetch('/')
const { body, headers } = res
```

#### `url(path)`

Get the full URL for a given page (including the port the test server is running on.)

```tstwoslash
import { url } from '@nuxt/test-utils/e2e'

const pageUrl = url('/page')
// 'http://localhost:6840/page'
```

### Testing in a Browser

We provide built-in support using Playwright within `@nuxt/test-utils`, either programmatically or via the Playwright test runner.

#### `createPage(url)`

Within `vitest`, `jest` or `cucumber`, you can create a configured Playwright browser instance with `createPage`, and (optionally) point it at a path from the running server. You can find out more about the API methods available from [in the Playwright documentation](https://playwright.dev/docs/api/class-page).

```tstwoslash
import { createPage } from '@nuxt/test-utils/e2e'

const page = await createPage('/page')
// you can access all the Playwright APIs from the `page` variable
```

#### Testing with Playwright Test Runner

We also provide first-class support for testing Nuxt within [the Playwright test runner](https://playwright.dev/docs/intro).

<code-group sync="pm">

```bash [npm]
npm i --save-dev @playwright/test @nuxt/test-utils
```

```bash [yarn]
yarn add --dev @playwright/test @nuxt/test-utils
```

```bash [pnpm]
pnpm add -D @playwright/test @nuxt/test-utils
```

```bash [bun]
bun add --dev @playwright/test @nuxt/test-utils
```

```bash [deno]
deno add --dev npm:@playwright/test npm:@nuxt/test-utils
```

</code-group>

You can provide global Nuxt configuration, with the same configuration details as the `setup()` function mentioned earlier in this section.

```ts [playwright.config.ts]
import { fileURLToPath } from 'node:url'
import { defineConfig, devices } from '@playwright/test'
import type { ConfigOptions } from '@nuxt/test-utils/playwright'

export default defineConfig<ConfigOptions>({
  use: {
    nuxt: {
      rootDir: fileURLToPath(new URL('.', import.meta.url)),
    },
  },
  // ...
})
```

<read-more target="_blank" title="See full example config" to="https://github.com/nuxt/test-utils/blob/main/examples/app-playwright/playwright.config.ts">



</read-more>

Your test file should then use `expect` and `test` directly from `@nuxt/test-utils/playwright`:

```ts [tests/example.test.ts]
import { expect, test } from '@nuxt/test-utils/playwright'

test('test', async ({ page, goto }) => {
  await goto('/', { waitUntil: 'hydration' })
  await expect(page.getByRole('heading')).toHaveText('Welcome to Playwright!')
})
```

You can alternatively configure your Nuxt server directly within your test file:

```ts [tests/example.test.ts]
import { expect, test } from '@nuxt/test-utils/playwright'

test.use({
  nuxt: {
    rootDir: fileURLToPath(new URL('..', import.meta.url)),
  },
})

test('test', async ({ page, goto }) => {
  await goto('/', { waitUntil: 'hydration' })
  await expect(page.getByRole('heading')).toHaveText('Welcome to Playwright!')
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/transitions.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/transitions.md

# Transitions

> Apply transitions between pages and layouts with Vue or native browser View Transitions.

<note>

Nuxt leverages Vue's [`<Transition>`](https://vuejs.org/guide/built-ins/transition#the-transition-component) component to apply transitions between pages and layouts.

</note>

## Page Transitions

You can enable page transitions to apply an automatic transition for all your [pages](/docs/4.x/directory-structure/app/pages).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    pageTransition: { name: 'page', mode: 'out-in' },
  },
})
```

<note>

If you are changing layouts as well as page, the page transition you set here will not run. Instead, you should set a [layout transition](/docs/4.x/getting-started/transitions#layout-transitions).

</note>

To start adding transition between your pages, add the following CSS to your [`app.vue`](/docs/4.x/directory-structure/app/app):

<code-group>

```vue [app/app.vue]
<template>
  <NuxtPage />
</template>

<style>
.page-enter-active,
.page-leave-active {
  transition: all 0.4s;
}
.page-enter-from,
.page-leave-to {
  opacity: 0;
  filter: blur(1rem);
}
</style>
```

```vue [app/pages/index.vue]
<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about">About page</NuxtLink>
  </div>
</template>
```

```vue [app/pages/about.vue]
<template>
  <div>
    <h1>About page</h1>
    <NuxtLink to="/">Home page</NuxtLink>
  </div>
</template>
```

</code-group>

This produces the following result when navigating between pages:

<video controls="true" className="rounded" poster="https://res.cloudinary.com/nuxt/video/upload/v1665061349/nuxt3/nuxt3-page-transitions_umwvmh.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1665061349/nuxt3/nuxt3-page-transitions_umwvmh.mp4" type="video/mp4" />
</video>

To set a different transition for a page, set the `pageTransition` key in [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) of the page:

<code-group>

```vue [pages/about.vue]twoslash
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'rotate',
  },
})
</script>
```

```vue [app/app.vue]
<template>
  <NuxtPage />
</template>

<style>
/* ... */
.rotate-enter-active,
.rotate-leave-active {
  transition: all 0.4s;
}
.rotate-enter-from,
.rotate-leave-to {
  opacity: 0;
  transform: rotate3d(1, 1, 1, 15deg);
}
</style>
```

</code-group>

Moving to the about page will add the 3d rotation effect:

<video controls="true" className="rounded" poster="https://res.cloudinary.com/nuxt/video/upload/v1665063233/nuxt3/nuxt3-page-transitions-cutom.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1665063233/nuxt3/nuxt3-page-transitions-cutom.mp4" type="video/mp4" />
</video>

## Layout Transitions

You can enable layout transitions to apply an automatic transition for all your [layouts](/docs/4.x/directory-structure/app/layouts).

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    layoutTransition: { name: 'layout', mode: 'out-in' },
  },
})
```

To start adding transition between your pages and layouts, add the following CSS to your [`app.vue`](/docs/4.x/directory-structure/app/app):

<code-group>

```vue [app/app.vue]
<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

<style>
.layout-enter-active,
.layout-leave-active {
  transition: all 0.4s;
}
.layout-enter-from,
.layout-leave-to {
  filter: grayscale(1);
}
</style>
```

```vue [app/layouts/default.vue]
<template>
  <div>
    <pre>default layout</pre>
    <slot />
  </div>
</template>

<style scoped>
div {
  background-color: lightgreen;
}
</style>
```

```vue [app/layouts/orange.vue]
<template>
  <div>
    <pre>orange layout</pre>
    <slot />
  </div>
</template>

<style scoped>
div {
  background-color: #eebb90;
  padding: 20px;
  height: 100vh;
}
</style>
```

```vue [app/pages/index.vue]
<template>
  <div>
    <h1>Home page</h1>
    <NuxtLink to="/about">About page</NuxtLink>
  </div>
</template>
```

```vue [app/pages/about.vue]
<script setup lang="ts">
definePageMeta({
  layout: 'orange',
})
</script>

<template>
  <div>
    <h1>About page</h1>
    <NuxtLink to="/">Home page</NuxtLink>
  </div>
</template>
```

</code-group>

This produces the following result when navigating between pages:

<video controls="true" className="rounded" poster="https://res.cloudinary.com/nuxt/video/upload/v1665065289/nuxt3/nuxt3-layouts-transitions_c9hwlx.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1665065289/nuxt3/nuxt3-layouts-transitions_c9hwlx.mp4" type="video/mp4" />
</video>

Similar to `pageTransition`, you can apply a custom `layoutTransition` to the page component using `definePageMeta`:

```vue [pages/about.vue]twoslash
<script setup lang="ts">
definePageMeta({
  layout: 'orange',
  layoutTransition: {
    name: 'slide-in',
  },
})
</script>
```

## Global Settings

You can customize these default transition names globally using `nuxt.config`.

Both `pageTransition` and `layoutTransition` keys accept [`TransitionProps`](https://vuejs.org/api/built-in-components#transition) as JSON serializable values where you can pass the `name`, `mode` and other valid transition-props of the custom CSS transition.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    pageTransition: {
      name: 'fade',
      mode: 'out-in', // default
    },
    layoutTransition: {
      name: 'slide',
      mode: 'out-in', // default
    },
  },
})
```

<warning>

If you change the `name` property, you also have to rename the CSS classes accordingly.

</warning>

To override the global transition property, use the `definePageMeta` to define page or layout transitions for a single Nuxt page and override any page or layout transitions that are defined globally in `nuxt.config` file.

```vue [pages/some-page.vue]twoslash
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'bounce',
    mode: 'out-in', // default
  },
})
</script>
```

## Disable Transitions

`pageTransition` and `layoutTransition` can be disabled for a specific route:

```vue [pages/some-page.vue]twoslash
<script setup lang="ts">
definePageMeta({
  pageTransition: false,
  layoutTransition: false,
})
</script>
```

Or globally in the `nuxt.config`:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    pageTransition: false,
    layoutTransition: false,
  },
})
```

## JavaScript Hooks

For advanced use-cases, you can use JavaScript hooks to create highly dynamic and custom transitions for your Nuxt pages.

This way presents perfect use-cases for JavaScript animation libraries such as [GSAP](https://gsap.com).

```vue [pages/some-page.vue]twoslash
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'custom-flip',
    mode: 'out-in',
    onBeforeEnter: (el) => {
      console.log('Before enter...')
    },
    onEnter: (el, done) => {},
    onAfterEnter: (el) => {},
  },
})
</script>
```

<tip>

Learn more about additional [JavaScript hooks](https://vuejs.org/guide/built-ins/transition#javascript-hooks) available in the `Transition` component.

</tip>

## Dynamic Transitions

To apply dynamic transitions using conditional logic, you can leverage inline [middleware](/docs/4.x/directory-structure/app/middleware) to assign a different transition name to `to.meta.pageTransition`.

<code-group>

```vue [pages/[id].vue]twoslash
<script setup lang="ts">
definePageMeta({
  pageTransition: {
    name: 'slide-right',
    mode: 'out-in',
  },
  middleware (to, from) {
    if (to.meta.pageTransition && typeof to.meta.pageTransition !== 'boolean') {
      to.meta.pageTransition.name = +to.params.id! > +from.params.id! ? 'slide-left' : 'slide-right'
    }
  },
})
</script>

<template>
  <h1>#{{ $route.params.id }}</h1>
</template>

<style>
.slide-left-enter-active,
.slide-left-leave-active,
.slide-right-enter-active,
.slide-right-leave-active {
  transition: all 0.2s;
}
.slide-left-enter-from {
  opacity: 0;
  transform: translate(50px, 0);
}
.slide-left-leave-to {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-enter-from {
  opacity: 0;
  transform: translate(-50px, 0);
}
.slide-right-leave-to {
  opacity: 0;
  transform: translate(50px, 0);
}
</style>
```

```vue [app/layouts/default.vue]
<script setup lang="ts">
const route = useRoute()
const id = computed(() => Number(route.params.id || 1))
const prev = computed(() => '/' + (id.value - 1))
const next = computed(() => '/' + (id.value + 1))
</script>

<template>
  <div>
    <slot />
    <div v-if="$route.params.id">
      <NuxtLink :to="prev">⬅️</NuxtLink> |
      <NuxtLink :to="next">➡️</NuxtLink>
    </div>
  </div>
</template>
```

</code-group>

The page now applies the `slide-left` transition when going to the next id and `slide-right` for the previous:

<video controls="true" className="rounded" poster="https://res.cloudinary.com/nuxt/video/upload/v1665069410/nuxt3/nuxt-dynamic-page-transitions.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1665069410/nuxt3/nuxt-dynamic-page-transitions.mp4" type="video/mp4" />
</video>

## Transition with NuxtPage

When `<NuxtPage />` is used in `app.vue`, transitions can be configured with the `transition` prop to activate transitions globally.

```vue [app/app.vue]
<template>
  <div>
    <NuxtLayout>
      <NuxtPage
        :transition="{
          name: 'bounce',
          mode: 'out-in',
        }"
      />
    </NuxtLayout>
  </div>
</template>
```

<note>

Remember, this page transition cannot be overridden with `definePageMeta` on individual pages.

</note>

## View Transitions API (experimental)

Nuxt ships with an experimental implementation of the [**View Transitions API**](https://developer.chrome.com/docs/web-platform/view-transitions) (see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)). This is an exciting new way to implement native browser transitions which (among other things) have the ability to transition between unrelated elements on different pages.

You can check a demo [on StackBlitz](https://stackblitz.com/edit/nuxt-view-transitions).

The Nuxt integration can be enabled with the `experimental.viewTransition` option in your configuration file:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    viewTransition: true,
  },
})
```

The possible values are: `false`, `true`, or `'always'`.

If set to true, Nuxt will not apply transitions if the user's browser matches `prefers-reduced-motion: reduce` (recommended). If set to `always`, Nuxt will always apply the transition and it is up to you to respect the user's preference.

By default, view transitions are enabled for all [pages](/docs/4.x/directory-structure/app/pages), but you can set a different global default.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  app: {
    // Disable view transitions globally, and opt-in on a per page basis
    viewTransition: false,
  },
})
```

It is possible to override the default `viewTransition` value for a page by setting the `viewTransition` key in [`definePageMeta`](/docs/4.x/api/utils/define-page-meta) of the page:

```vue [pages/about.vue]twoslash
<script setup lang="ts">
definePageMeta({
  viewTransition: false,
})
</script>
```

<warning>

Overriding view transitions on a per-page basis will only have an effect if you have enabled the `experimental.viewTransition` option.

</warning>

If you are also using Vue transitions like `pageTransition` and `layoutTransition` (see above) to achieve the same result as the new View Transitions API, then you may wish to *disable* Vue transitions if the user's browser supports the newer, native web API. You can do this by creating `~/middleware/disable-vue-transitions.global.ts` with the following contents:

```ts
export default defineNuxtRouteMiddleware((to) => {
  if (import.meta.server || !document.startViewTransition) {
    return
  }

  // Disable built-in Vue transitions
  to.meta.pageTransition = false
  to.meta.layoutTransition = false
})
```

### Known Issues

- If you perform data fetching within your page setup functions, you may wish to reconsider using this feature for the moment. (By design, View Transitions completely freeze DOM updates whilst they are taking place.) We're looking at restricting the View Transition to the final moments before `<Suspense>` resolves, but in the interim you may want to consider carefully whether to adopt this feature if this describes you.

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/tsconfig.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/tsconfig.md

# tsconfig.json

> Learn how Nuxt manages TypeScript configuration across different parts of your project.

Nuxt [automatically generates](/docs/4.x/guide/concepts/typescript#auto-generated-types) multiple TypeScript configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, `.nuxt/tsconfig.node.json` and `.nuxt/tsconfig.shared.json`) that include recommended basic TypeScript configuration for your project, references to [auto-imports](/docs/4.x/guide/concepts/auto-imports), [API route types](/docs/4.x/guide/concepts/server-engine#typed-api-routes), path aliases, and more.

Your Nuxt project should include the following `tsconfig.json` file at the root of the project:

```json [tsconfig.json]
{
  "files": [],
  "references": [
    {
      "path": "./.nuxt/tsconfig.app.json"
    },
    {
      "path": "./.nuxt/tsconfig.server.json"
    },
    {
      "path": "./.nuxt/tsconfig.shared.json"
    },
    {
      "path": "./.nuxt/tsconfig.node.json"
    }
  ]
}
```

<warning>

We do not recommend modifying the contents of this file directly, as doing so could overwrite important settings that Nuxt or other modules rely on. Instead, extend it via `nuxt.config.ts`.

</warning>

<read-more to="/docs/4.x/guide/concepts/typescript#project-references">

Read more about the different type contexts of a Nuxt project here.

</read-more>

## Extending TypeScript Configuration

You can customize the TypeScript configuration of your Nuxt project for each context (`app`, `shared`, `node`, and `server`) in the `nuxt.config.ts` file.

```ts [nuxt.config.ts]twoslash
// @errors: 2353
export default defineNuxtConfig({
  typescript: {
    // customize tsconfig.app.json
    tsConfig: {
      // ...
    },
    // customize tsconfig.shared.json
    sharedTsConfig: {
      // ...
    },
    // customize tsconfig.node.json
    nodeTsConfig: {
      // ...
    },
  },
  nitro: {
    typescript: {
      // customize tsconfig.server.json
      tsConfig: {
        // ...
      },
    },
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/typecheck.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/typecheck.md

# nuxt typecheck

> The typecheck command runs vue-tsc to check types throughout your app.

```bash [Terminal]
npx nuxt typecheck [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--dotenv] [-e, --extends=<layer-name>]
```

The `typecheck` command runs [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) to check types throughout your app.

## Arguments

<table>
<thead>
  <tr>
    <th>
      Argument
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ROOTDIR="."
      </code>
    </td>
    
    <td>
      Specifies the working directory (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --cwd=<directory>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify the working directory, this takes precedence over ROOTDIR (default: <code>
        .
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --logLevel=<silent|info|verbose>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Specify build-time log level
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dotenv
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Path to <code>
        .env
      </code>
      
       file to load, relative to the root directory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -e, --extends=<layer-name>
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Extend from a Nuxt layer
    </td>
  </tr>
</tbody>
</table>

<note>

This command sets `process.env.NODE_ENV` to `production`. To override, define `NODE_ENV` in a [`.env`](/docs/4.x/directory-structure/env) file or as a command-line argument.

</note>

<read-more to="/docs/4.x/guide/concepts/typescript#type-checking">

Read more on how to enable type-checking at build or development time.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/bridge/typescript.md

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/typescript.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/typescript.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/typescript.md

# TypeScript

> Nuxt is fully typed and provides helpful shortcuts to ensure you have access to accurate type information when you are coding.

## Type-checking

By default, Nuxt doesn't check types when you run [`nuxt dev`](/docs/4.x/api/commands/dev) or [`nuxt build`](/docs/4.x/api/commands/build), for performance reasons.

To enable type-checking at build or development time, install `vue-tsc` and `typescript` as development dependency:

<code-group sync="pm">

```bash [npm]
npm install --save-dev vue-tsc typescript
```

```bash [yarn]
yarn add --dev vue-tsc typescript
```

```bash [pnpm]
pnpm add -D vue-tsc typescript
```

```bash [bun]
bun add -D vue-tsc typescript
```

```bash [deno]
deno add -D npm:vue-tsc npm:typescript
```

</code-group>

Then, run [`nuxt typecheck`](/docs/4.x/api/commands/typecheck) command to check your types:

```bash [Terminal]
npx nuxt typecheck
```

To enable type-checking at build or development time, you can also use the [`typescript.typeCheck`](/docs/4.x/api/nuxt-config#typecheck) option in your `nuxt.config` file:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  typescript: {
    typeCheck: true,
  },
})
```

## Auto-generated Types

Nuxt projects rely on auto-generated types to work properly. These types are stored in the [`.nuxt`](/docs/4.x/directory-structure/nuxt) directory and are generated when you run the dev server or build your application. You can also generate these files manually by running `nuxt prepare`.

The generated `tsconfig.json` files inside the [`.nuxt`](/docs/4.x/directory-structure/nuxt) directory include **recommended basic TypeScript configuration** for your project, references to [auto-imports](/docs/4.x/guide/concepts/auto-imports), [API route types](/docs/4.x/guide/concepts/server-engine#typed-api-routes), path aliases like `#imports`, `~/file`, or `#build/file`, and more.

<warning>

Nuxt relies on this configuration, and [Nuxt modules](/docs/4.x/guide/modules) can extend it as well. For this reason, it is not recommended to modify your `tsconfig.json` file directly, as doing so could overwrite important settings. Instead, extend it via `nuxt.config.ts`. [Learn more about extending the configuration here](/docs/4.x/directory-structure/tsconfig).

</warning>

<tip icon="i-lucide-video" target="_blank" to="https://youtu.be/umLI7SlPygY">

Watch a video from Daniel Roe explaining built-in Nuxt aliases.

</tip>

## Project References

Nuxt uses [TypeScript project references](https://www.typescriptlang.org/docs/handbook/project-references.html) to improve type-checking performance and provide better IDE support. This feature allows TypeScript to break up your codebase into smaller, more manageable pieces.

### How Nuxt Uses Project References

When you run `nuxt dev`, `nuxt build` or `nuxt prepare`, Nuxt will generate multiple `tsconfig.json` files for different parts of your application.

- **.nuxt/tsconfig.app.json** - Configuration for your application code within the `app/` directory
- **.nuxt/tsconfig.node.json** - Configuration for your `nuxt.config.ts` and files outside the other contexts
- **.nuxt/tsconfig.server.json** - Configuration for server-side code (when applicable)
- **.nuxt/tsconfig.shared.json** - For code shared between app and server contexts (like types and non-environment specific utilities)

Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.

<note>

For backward compatibility, Nuxt still generates `.nuxt/tsconfig.json`. However, we recommend using [TypeScript project references](/docs/4.x/directory-structure/tsconfig) with the new configuration files (`.nuxt/tsconfig.app.json`, `.nuxt/tsconfig.server.json`, etc.) for better type safety and performance. This legacy file will be removed in a future version of Nuxt.

</note>

### Benefits of Project References

- **Faster builds**: TypeScript can skip rebuilding unchanged projects
- **Better IDE performance**: Your IDE can provide faster IntelliSense and error checking
- **Isolated compilation**: Errors in one part of your application don't prevent compilation of other parts
- **Clearer dependency management**: Each project explicitly declares its dependencies

### Augmenting Types with Project References

Since the project is divided into **multiple type contexts**, it's important to **augment types within the correct context** to ensure they're properly recognized. TypeScript will not recognize augmentations placed outside these directories unless they are explicitly included in the appropriate context.

For example, if you want to augment types for the `app` context, the augmentation file should be placed in the `app/` directory.

Similarly:

- For the `server` context, place the augmentation file in the `server/` directory.
- For types that are **shared between the app and server**, place the file in the `shared/` directory.

<read-more to="/docs/4.x/guide/modules/recipes-advanced#extend-typescript-config">

Read more about augmenting specific type contexts from **files outside those contexts** in the Module Author Guide.

</read-more>

## Strict Checks

TypeScript comes with certain checks to give you more safety and analysis of your program.

[Strict checks](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html#getting-stricter-checks) are enabled by default in Nuxt when the [`typescript.typeCheck`](/docs/4.x/guide/concepts/typescript#type-checking) option is enabled to give you greater type safety.

If you are currently converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting `strict` to `false` in your `nuxt.config`:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  typescript: {
    strict: false,
  },
})
```

---

# Source: https://nuxt.com/raw/blog/understanding-how-fetch-works-in-nuxt-2-12.md

# Understanding how fetch works in Nuxt 2.12

> Explore different features of the fetch hook and learn a brand new way to bring data into Nuxt applications.

Nuxt introduces a new `fetch` with the latest release of version 2.12. Fetch provides a brand new way to bring data into Nuxt applications.

In this post, we will explore different features of the fetch hook and try to understand how it works.

## Fetch Hook and Nuxt Lifecycle

In terms of Nuxt lifecycle hooks, `fetch` sits within Vue lifecycle after `created` hook. As we already know that, all Vue lifecycle hooks are called with their `this` context. The same applies to `fetch` hook as well.

![New fetch in Nuxt lifecycle](/assets/blog/new-fetch-lifecycle-hooks.png)

Fetch hook is called after the component instance is created on the server-side. That makes `this` context available inside the `fetch`.

```js
export default {
  fetch() {
    console.log(this)
  }
}
```

Let’s see what this could mean for page components.

### Page Components

With the help of `this` context, fetch is able to mutate component’s data directly. It means we can set the component’s local data without having to dispatch Vuex store action or committing mutation from the page component.

As a result, Vuex becomes optional, but not impossible. We can still use `this.$store` as usual to access Vuex store if required.

## Availability of fetch hook

With `fetch`, we can prefetch the data asynchronously **in any Vue components**. It means, other than page components found in `/pages` directory, every other `.vue` components found in `/layouts` and `/components` directories can also benefit from the fetch hook.

Let's see what this could mean for layout and building-block components.

### Layout Components

Using new `fetch`, now we can make API calls directly from the layout components. This was impossible prior to the release of v2.12.

**Possible use cases**

- Fetch config data from the back-end in Nuxt layouts to generate footer and navbar dynamically
- Fetch user related data (i.e. user profile, shopping-cart item count) in the navbar
- Fetch site relevant data on `layouts/error.vue`

### Building-block (Child/Nested) Components

With `fetch` hook available in child components as well, we can off-load some of the data-fetching tasks from page-level components, and delegate them over to nested components. This was also impossible prior to the release of v2.12.

This reduces the responsibility of route-level components to a great extent.

**Possible use case -** We can still pass props to child components, but if the child components need to have their own data-fetching logic, now they can!

## Call order of multiple fetch hooks

Since each component can have its own data-fetching logic, you may ask what would be the order in which each of them are called?

Fetch hook is called on server-side once (on the first request to the Nuxt app) and then on client-side when navigating to further routes. But since we can define one fetch hook for each component, fetch hooks are called in sequence of their hierarchy.

### Disabling fetch on server-side

In addition, we can even disable fetch on the server-side if required.

```js
export default {
  fetchOnServer: false
}
```

And this way, the fetch hook will only be called on client-side. When `fetchOnServer` is set to false, `$fetchState.pending` becomes `true` when the component is rendered on server-side.

## Error Handling

New `fetch` handles error at component level. Let’s see how.

Because we’re fetching data asynchronously, the new fetch() provides a `$fetchState` object to check whether the request has finished and progressed successfully.

Below is what the `$fetchState` object looks like.

```text
$fetchState = {
  pending: true | false,
  error: null | {},
  timestamp: Integer
};
```

We have three keys,

1. **Pending -** lets you display a placeholder when fetch is being called on client-side
2. **Error -** lets you show an error message
3. **Timestamp -** shows timestamp of the last fetch which is useful for caching with `keep-alive`

These keys are then used directly in the template area of the component to show relevant placeholders during the process of fetching data from the API.

```html
<template>
  <div>
    <p v-if="$fetchState.pending">Fetching posts...</p>
    <p v-else-if="$fetchState.error">Error while fetching posts</p>
    <ul v-else>
      …
    </ul>
  </div>
</template>
```

When error occurs at **component-level**, we can set HTTP status code on server-side by checking `process.server` in fetch hook and follow it up with `throw new Error()` statement.

```js
async fetch() {
  const post = await fetch(`https://jsonplaceholder.typicode.com/posts/${this.$route.params.id}`)
                     .then((res) => res.json())

  if (post.id === this.$route.params.id) {
      this.post = post
    } else {
      // set status code on server and
      if (process.server) {
        this.$nuxt.context.res.statusCode = 404
      }
      // use throw new Error()
      throw new Error('Post not found')
    }
}
```

Setting the HTTP status code this way **is useful for correct SEO**.

## Fetch as a method

New fetch hook also acts as a method that can be invoked upon user interaction or invoked programmatically from the component methods.

```html
<!-- from template in template  -->
<button @click="$fetch">Refresh Data</button>
```

```js
// from component methods in script section
export default {
  methods: {
    refresh() {
      this.$fetch()
    }
  }
}
```

## Making Nuxt pages more performant

We can use `:keep-alive-props` prop and `activated` hook to make Nuxt page components more performant using a new fetch hook.

Nuxt allows **caching a certain number of pages** in the memory along with their fetched data. And also allows **adding a number of seconds** before we can re-fetch the data.

For any of the above methods to work, we have to use the `keep-alive` prop in generic `<nuxt />` and `<nuxt-child`> components.

```html [layouts/default.vue]
<template>
  <div>
    <nuxt keep-alive />
  </div>
</template>
```

In addition, we can pass `:keep-alive-props` to `<nuxt />` component to cache a number of pages along with their fetched data.

`:keep-alive-props` prop allow us to indicate the maximum number of pages that should be kept in the memory while we navigate elsewhere within the site.

```html [layouts/default.vue]
<nuxt keep-alive :keep-alive-props="{ max: 10 }" />
```

Above is one way to boost page performance which is more high-level and generic, while the next one drills down to optimize the fetch request calls by using the `timestamp` property of `$fetchState` and comparing it against the number of seconds delay before it re-fetches the data.

Vue’s `activated` hook is used here with Nuxt's `keep-alive` prop to re-fetch the data.

```js
export default {
  activated() {
    // Call fetch again if last fetch more than a minute ago
    if (this.$fetchState.timestamp <= Date.now() - 60000) {
      this.$fetch()
    }
  }
}
```

## asyncData vs Fetch

As far as page components are concerned, new `fetch` seems way too similar to `asyncData()` because they both deal with the local data. But there are some key differences worth taking note of as below.

As of Nuxt 2.12, `asyncData` method is still an active feature. Let’s examine some of the key differences between `asyncData` and new `fetch`.

### asyncData

1. `asyncData` is limited to only page-level components
2. `this` context is unavailable
3. Adds payload by **returning** the data

```js
export default {
  async asyncData(context) {
    const data = await context.$axios.$get(
      `https://jsonplaceholder.typicode.com/todos`
    )
    // `todos` does not have to be declared in data()
    return { todos: data.Item }
    // `todos` is merged with local data
  }
}
```

### New Fetch

1. `fetch` is available in all Vue components
2. `this` context is available
3. Simply **mutates** the local data

```js
export default {
  data() {
    return {
      todos: []
    }
  },
  async fetch() {
    const { data } = await axios.get(
      `https://jsonplaceholder.typicode.com/todos`
    )
    // `todos` has to be declared in data()
    this.todos = data
  }
}
```

## Fetch before Nuxt 2.12

If you have been working with Nuxt for a while, then you’ll know that the previous version of `fetch` was significantly different.

> **Is this a breaking change?**

> No, it isn't. Actually, the old fetch can still be used by passing the `context` as the first argument to avoid any breaking changes in your existing Nuxt applications.

Here’s the list of notable changes in `fetch` hook compared with **before** and **after** v2.12.

### 1. Call order of `fetch` hook

**Before -** `fetch` hook was called before initiating the component, hence `this` wasn’t available inside the fetch hook.

**After -** `fetch` is called after the component instance is created on the server-side when the route is accessed.

### 2. `this` vs `context`

**Before -** We had access to the Nuxt `context` on page-level components, given that the `context` is passed as a first parameter.

```js
export default {
  fetch(context) {
    // …
  }
}
```

**After -** We can access `this` context just like Vue client-side hooks without passing any parameters.

```js
export default {
  fetch() {
    console.log(this)
  }
}
```

### 3. Availability of `fetch` hook

**Before -** Only page (route-level) components were allowed to fetch data on the server-side.

**After -** Now, we can prefetch the data asynchronously in any Vue components.

### 4. Call order of `fetch` hook

**Before -** `fetch` could be called server-side once (on the first request to the Nuxt app) and client-side when navigating to further routes.

**After -** New `fetch` is the same as an old fetch, but…

…since we can have one `fetch` for each component, `fetch` hooks are called in sequence of their hierarchy.

### 5. Error Handling

**Before -** We used the `context.error` function that showed a custom error page when an error occurred during API calls.

**After -** New `fetch` uses the `$fetchState` object to handle errors in the template area during API calls.

Error handling is performed at component level.

> **Does this mean we cannot show users a custom error page like we did prior to Nuxt 2.12?**

Yes we can, but only with `asyncData()` when it's about page-level component data. When using `fetch`, we can utilize `this.$nuxt.error({ statusCode: 404, message: 'Data not found' })` to show a custom error page.

## Conclusion

New fetch hook brings a lot of improvements and provides more flexibility in fetching data and organizing route-level & building-block components in a whole new way!

It will certainly make you think a little differently when you plan and design your new Nuxt project that requires multiple API calls within the same route.

I hope this article has helped you get acquainted with the new `fetch` feature. I'd love to see what you build with it.

---

# Source: https://nuxt.com/raw/docs/3.x/examples/routing/universal-router.md

# Source: https://nuxt.com/raw/docs/4.x/examples/routing/universal-router.md

# Universal Router

> This example demonstrates Nuxt universal routing utilities without depending on `pages/` and `vue-router`.

<sandbox branch="main" dir="examples/routing/universal-router" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/api/utils/update-app-config.md

# Source: https://nuxt.com/raw/docs/4.x/api/utils/update-app-config.md

# updateAppConfig

> Update the App Config at runtime.

<note>

Updates the [`app.config`](/docs/4.x/directory-structure/app/app-config) using deep assignment. Existing (nested) properties will be preserved.

</note>

## Usage

```js
import { updateAppConfig, useAppConfig } from '#imports'

const appConfig = useAppConfig() // { foo: 'bar' }

const newAppConfig = { foo: 'baz' }
updateAppConfig(newAppConfig)

console.log(appConfig) // { foo: 'baz' }
```

<read-more to="/docs/4.x/directory-structure/app/app-config">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/commands/upgrade.md

# Source: https://nuxt.com/raw/docs/3.x/getting-started/upgrade.md

# Source: https://nuxt.com/raw/docs/4.x/api/commands/upgrade.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/upgrade.md

# Upgrade Guide

> Learn how to upgrade to the latest Nuxt version.

## Upgrading Nuxt

### Latest release

To upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases), use the `nuxt upgrade` command.

<code-group sync="pm">

```bash [npm]
npx nuxt upgrade
```

```bash [yarn]
yarn nuxt upgrade
```

```bash [pnpm]
pnpm nuxt upgrade
```

```bash [bun]
bun x nuxt upgrade
```

```bash [deno]
deno x nuxt upgrade
```

</code-group>

### Nightly Release Channel

To use the latest Nuxt build and test features before their release, read about the [nightly release channel](/docs/4.x/guide/going-further/nightly-release-channel) guide.

## Testing Nuxt 5

Nuxt 5 is **currently in development**. Until the release, it is possible to test many of Nuxt 5's breaking changes from Nuxt version 4.2+.

### Opting in to Nuxt 5

First, upgrade Nuxt to the [latest release](https://github.com/nuxt/nuxt/releases).

Then you can set your `future.compatibilityVersion` to match Nuxt 5 behavior:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5,
  },
})
```

When you set your `future.compatibilityVersion` to `5`, defaults throughout your Nuxt configuration will change to opt in to Nuxt v5 behavior, including:

- **Vite Environment API**: Automatically enables the new [Vite Environment API](/docs/4.x/getting-started/upgrade#migration-to-vite-environment-api) for improved build configuration
- Other Nuxt 5 improvements and changes as they become available

<note>

This section is subject to change until the final release, so please check back here regularly if you are testing Nuxt 5 using `future.compatibilityVersion: 5`.

</note>

Breaking or significant changes will be noted below along with migration steps for backward/forward compatibility.

### Migration to Vite Environment API

🚦 **Impact Level**: Medium

#### What Changed

Nuxt 5 migrates to Vite 6's new [Environment API](https://vite.dev/guide/api-environment), which formalizes the concept of environments and provides better control over configuration per environment.

Previously, Nuxt used separate client and server Vite configurations. Now, Nuxt uses a shared Vite configuration with environment-specific plugins that use the `applyToEnvironment()` method to target specific environments.

<tip>

You can test this feature early by setting `future.compatibilityVersion: 5` (see [Testing Nuxt 5](/docs/4.x/getting-started/upgrade#testing-nuxt-5)) or by enabling it explicitly with `experimental.viteEnvironmentApi: true`.

</tip>

**Key changes:**

1. **Deprecated environment-specific extendViteConfig()**: The `server` and `client` options in `extendViteConfig()` are deprecated and will show warnings when used.
2. **Changed plugin registration**: Vite plugins registered with `addVitePlugin()` and only targeting one environment (by passing `server: false` or `client: false`) will not have their `config` or `configResolved` hooks called.
3. **Shared configuration**: The `vite:extendConfig` and `vite:configResolved` hooks now work with a shared configuration rather than separate client/server configs.

#### Reasons for Change

The Vite Environment API provides:

- Better consistency between development and production builds
- More granular control over environment-specific configuration
- Improved performance and plugin architecture
- Support for custom environments beyond just client and server

#### Migration Steps

##### 1. Migrate to use Vite plugins

We would recommend you use a Vite plugin instead of `extendViteConfig`, `vite:configResolved` and `vite:extendConfig`.

```ts
// Before
extendViteConfig((config) => {
  config.optimizeDeps.include.push('my-package')
}, { server: false })

nuxt.hook('vite:extendConfig' /* or vite:configResolved */, (config, { isClient }) => {
  if (isClient) {
    config.optimizeDeps.include.push('my-package')
  }
})

// After
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    // you can set global vite configuration here
  },
  configResolved (config) {
    // you can access the fully resolved vite configuration here
  },
  configEnvironment (name, config) {
    // you can set environment-specific vite configuration here
    if (name === 'client') {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('my-package')
    }
  },
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
}))
```

##### 2. Migrate Vite plugins to use environments

Instead of using `addVitePlugin` with `server: false` or `client: false`, you can instead use the new `applyToEnvironment` hook within your plugin.

```ts
// Before
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    config.optimizeDeps.include.push('my-package')
  },
}), { client: false })

// After
addVitePlugin(() => ({
  name: 'my-plugin',
  config (config) {
    // you can set global vite configuration here
  },
  configResolved (config) {
    // you can access the fully resolved vite configuration here
  },
  configEnvironment (name, config) {
    // you can set environment-specific vite configuration here
    if (name === 'client') {
      config.optimizeDeps ||= {}
      config.optimizeDeps.include ||= []
      config.optimizeDeps.include.push('my-package')
    }
  },
  applyToEnvironment (environment) {
    return environment.name === 'client'
  },
}))
```

<read-more to="https://vite.dev/guide/api-environment" target="_blank">

Learn more about Vite's Environment API

</read-more>

## Migrating to Nuxt 4

Nuxt 4 includes significant improvements and changes. This guide will help you migrate your existing Nuxt 3 application to Nuxt 4.

First, upgrade to Nuxt 4:

<code-group sync="pm">

```bash [npm]
npm install nuxt@^4.0.0
```

```bash [yarn]
yarn add nuxt@^4.0.0
```

```bash [pnpm]
pnpm add nuxt@^4.0.0
```

```bash [bun]
bun add nuxt@^4.0.0
```

```bash [deno]
deno add npm:nuxt@^4.0.0
```

</code-group>

After upgrading, most Nuxt 4 behaviors are now the default. However, some features can still be configured if you need to maintain backward compatibility during your migration.

The following sections detail the key changes and migrations needed when upgrading to Nuxt 4.

Breaking or significant changes are documented below along with migration steps and available configuration options.

### Migrating Using Codemods

To facilitate the upgrade process, we have collaborated with the [Codemod](https://github.com/codemod/codemod) team to automate many migration steps with some open-source codemods.

<note>

If you encounter any issues, please report them to the Codemod team with `npx codemod feedback` 🙏

</note>

For a complete list of Nuxt 4 codemods, detailed information on each, their source, and various ways to run them, visit the [Codemod Registry](https://app.codemod.com/registry).

You can run all the codemods mentioned in this guide using the following `codemod` recipe:

<code-group>

```bash [npm]
# Using pinned version due to https://github.com/codemod/codemod/issues/1710
npx codemod@0.18.7 nuxt/4/migration-recipe
```

```bash [yarn]
# Using pinned version due to https://github.com/codemod/codemod/issues/1710
yarn dlx codemod@0.18.7 nuxt/4/migration-recipe
```

```bash [pnpm]
# Using pinned version due to https://github.com/codemod/codemod/issues/1710
pnpm dlx codemod@0.18.7 nuxt/4/migration-recipe
```

```bash [bun]
# Using pinned version due to https://github.com/codemod/codemod/issues/1710
bun x codemod@0.18.7 nuxt/4/migration-recipe
```

```bash [deno]
# Using pinned version due to https://github.com/codemod/codemod/issues/1710
deno x codemod@0.18.7 nuxt/4/migration-recipe
```

</code-group>

This command will execute all codemods in sequence, with the option to deselect any that you do not wish to run. Each codemod is also listed below alongside its respective change and can be executed independently.

### New Directory Structure

🚦 **Impact Level**: Significant

Nuxt now defaults to a new directory structure, with backwards compatibility (so if Nuxt detects you are using the old structure, such as with a top-level `app/pages/` directory, this new structure will not apply).

👉 [See full RFC](https://github.com/nuxt/nuxt/issues/26444)

#### What Changed

- the new Nuxt default `srcDir` is `app/` by default, and most things are resolved from there.
- `serverDir` now defaults to `<rootDir>/server` rather than `<srcDir>/server`
- `layers/`, `modules/` and `public/` are resolved relative to `<rootDir>` by default
- if using [Nuxt Content v2.13+](https://github.com/nuxt/content/pull/2649), `content/` is resolved relative to `<rootDir>`
- a new `dir.app` is added, which is the directory we look for `router.options.ts` and `spa-loading-template.html` - this defaults to `<srcDir>/`

<details>
<summary>

An example v4 folder structure.

</summary>

```sh
.output/
.nuxt/
app/
  assets/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  utils/
  app.config.ts
  app.vue
  router.options.ts
content/
layers/
modules/
node_modules/
public/
shared/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts
```

<note>

With this new structure, the `~` alias now points to the `app/` directory by default (your `srcDir`). This means `~/components` resolves to `app/components/`, `~/pages` to `app/pages/`, etc.

</note>
</details>

👉 For more details, see the [PR implementing this change](https://github.com/nuxt/nuxt/pull/27029).

#### Reasons for Change

1. **Performance** - placing all your code in the root of your repo causes issues with `.git/` and `node_modules/` folders being scanned/included by FS watchers which can significantly delay startup on non-Mac OSes.
2. **IDE type-safety** - `server/` and the rest of your app are running in two entirely different contexts with different global imports available, and making sure `server/` isn't *inside* the same folder as the rest of your app is a big first step to ensuring you get good auto-completes in your IDE.

<video-accordion platform="vimeo" title="Watch a video from Vue School on the new directory structure" video-id="1031028378">



</video-accordion>

#### Migration Steps

1. Create a new directory called `app/`.
2. Move your `assets/`, `components/`, `composables/`, `app/layouts/`, `app/middleware/`, `app/pages/`, `app/plugins/` and `utils/` folders under it, as well as `app.vue`, `error.vue`, `app.config.ts`. If you have an `app/router-options.ts` or `app/spa-loading-template.html`, these paths remain the same.
3. Make sure your `nuxt.config.ts`, `content/`, `layers/`, `modules/`, `public/` and `server/` folders remain outside the `app/` folder, in the root of your project.
4. Remember to update any third-party configuration files to work with the new directory structure, such as your `tailwindcss` or `eslint` configuration (if required - `@nuxtjs/tailwindcss` should automatically configure `tailwindcss` correctly).

<tip>

You can automate this migration by running `npx codemod@latest nuxt/4/file-structure`

</tip>

However, migration is *not required*. If you wish to keep your current folder structure, Nuxt should auto-detect it. (If it does not, please raise an issue.) The one exception is that if you *already* have a custom `srcDir`. In this case, you should be aware that your `modules/`, `public/` and `server/` folders will be resolved from your `rootDir` rather than from your custom `srcDir`. You can override this by configuring `dir.modules`, `dir.public` and `serverDir` if you need to.

You can also force a v3 folder structure with the following configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  // This reverts the new srcDir default from `app` back to your root directory
  srcDir: '.',
  // This specifies the directory prefix for `router.options.ts` and `spa-loading-template.html`
  dir: {
    app: 'app',
  },
})
```

### Singleton Data Fetching Layer

🚦 **Impact Level**: Moderate

#### What Changed

Nuxt's data fetching system (`useAsyncData` and `useFetch`) has been significantly reorganized for better performance and consistency:

1. **Shared refs for the same key**: All calls to `useAsyncData` or `useFetch` with the same key now share the same `data`, `error` and `status` refs. This means that it is important that all calls with an explicit key must not have conflicting `deep`, `transform`, `pick`, `getCachedData` or `default` options.
2. **More control over getCachedData**: The `getCachedData` function is now called every time data is fetched, even if this is caused by a watcher or calling `refreshNuxtData`. (Previously, new data was always fetched and this function was not called in these cases.) To allow more control over when to use cached data and when to refetch, the function now receives a context object with the cause of the request.
3. **Reactive key support**: You can now use computed refs, plain refs or getter functions as keys, which enables automatic data refetching (and stores data separately).
4. **Data cleanup**: When the last component using data fetched with `useAsyncData` is unmounted, Nuxt will remove that data to avoid ever-growing memory usage.

#### Reasons for Change

These changes have been made to improve memory usage and increase consistency with loading states across calls of `useAsyncData`.

#### Migration Steps

1. **Check for inconsistent options**: Review any components using the same key with different options or fetch functions.```ts
// This will now trigger a warning
const { data: users1 } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: users2 } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
```

<br />

It may be beneficial to extract any calls to `useAsyncData` that share an explicit key (and have custom options) into their own composable:```ts [app/composables/useUserData.ts]
export function useUserData (userId: string) {
  return useAsyncData(
    `user-${userId}`,
    () => fetchUser(userId),
    {
      deep: true,
      transform: user => ({ ...user, lastAccessed: new Date() }),
    },
  )
}
```
2. **Update getCachedData implementations**:```diff
useAsyncData('key', fetchFunction, {
-  getCachedData: (key, nuxtApp) => {
-    return cachedData[key]
-  }
+  getCachedData: (key, nuxtApp, ctx) => {
+    // ctx.cause - can be 'initial' | 'refresh:hook' | 'refresh:manual' | 'watch'
+    
+    // Example: Don't use cache on manual refresh
+    if (ctx.cause === 'refresh:manual') return undefined
+    
+    return cachedData[key]
+  }
})
```

Alternatively, for now, you can disable this behaviour with:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    granularCachedData: false,
    purgeCachedData: false,
  },
})
```

### Corrected Module Loading Order in Layers

🚦 **Impact Level**: Minimal

#### What Changed

The order in which modules are loaded when using [Nuxt layers](/docs/4.x/guide/going-further/layers) has been corrected. Previously, modules from the project root were loaded before modules from extended layers, which was the reverse of the expected behavior.

Now modules are loaded in the correct order:

1. **Layer modules first** (in extend order - deeper layers first)
2. **Project modules last** (highest priority)

This affects both:

- Modules defined in the `modules` array in `nuxt.config.ts`
- Auto-discovered modules from the `modules/` directory

#### Reasons for Change

This change ensures that:

- Extended layers have lower priority than the consuming project
- Module execution order matches the intuitive layer inheritance pattern
- Module configuration and hooks work as expected in multi-layer setups

#### Migration Steps

**Most projects will not need changes**, as this corrects the loading order to match expected behavior.

However, if your project was relying on the previous incorrect order, you may need to:

1. **Review module dependencies**: Check if any modules depend on specific loading order
2. **Adjust module configuration**: If modules were configured to work around the incorrect order
3. **Test thoroughly**: Ensure all functionality works as expected with the corrected order

Example of the new correct order:

```ts
// Layer: my-layer/nuxt.config.ts
export default defineNuxtConfig({
  modules: ['layer-module-1', 'layer-module-2'],
})

// Project: nuxt.config.ts
export default defineNuxtConfig({
  extends: ['./my-layer'],
  modules: ['project-module-1', 'project-module-2'],
})

// Loading order (corrected):
// 1. layer-module-1
// 2. layer-module-2
// 3. project-module-1 (can override layer modules)
// 4. project-module-2 (can override layer modules)
```

If you encounter issues with module order dependencies due to needing to register a hook, consider using the [`modules:done` hook](/docs/4.x/guide/modules/recipes-advanced) for modules that need to call a hook. This is run after all other modules have been loaded, which means it is safe to use.

👉 See [PR #31507](https://github.com/nuxt/nuxt/pull/31507) and [issue #25719](https://github.com/nuxt/nuxt/issues/25719) for more details.

### Deduplication of Route Metadata

🚦 **Impact Level**: Minimal

#### What Changed

It's possible to set some route metadata using `definePageMeta`, such as the `name`, `path`, and so on. Previously these were available both on the route and on route metadata (for example, `route.name` and `route.meta.name`).

Now, they are only accessible on the route object.

#### Reasons for Change

This is a result of enabling `experimental.scanPageMeta` by default, and is a performance optimization.

#### Migration Steps

The migration should be straightforward:

```diff
const route = useRoute()
  
- console.log(route.meta.name)
+ console.log(route.name)
```

### Normalized Component Names

🚦 **Impact Level**: Moderate

Vue will now generate component names that match the Nuxt pattern for component naming.

#### What Changed

By default, if you haven't set it manually, Vue will assign a component name that matches
the filename of the component.

```bash [Directory structure]
├─ components/
├─── SomeFolder/
├───── MyComponent.vue
```

In this case, the component name would be `MyComponent`, as far as Vue is concerned. If you wanted to use `<KeepAlive>` with it, or identify it in the Vue DevTools, you would need to use this name.

But in order to auto-import it, you would need to use `SomeFolderMyComponent`.

With this change, these two values will match, and Vue will generate a component name that matches the Nuxt pattern for component naming.

#### Migration Steps

Ensure that you use the updated name in any tests which use `findComponent` from `@vue/test-utils` and in any `<KeepAlive>` which depends on the name of your component.

Alternatively, for now, you can disable this behaviour with:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    normalizeComponentNames: false,
  },
})
```

### Unhead v2

🚦 **Impact Level**: Minimal

#### What Changed

[Unhead](https://unhead.unjs.io/), used to generate `<head>` tags, has been updated to version 2. While mostly compatible it includes several breaking changes
for lower-level APIs.

- Removed props: `vmid`, `hid`, `children`, `body`.
- Promise input no longer supported.
- Tags are now sorted using Capo.js by default.

#### Migration Steps

The above changes should have minimal impact on your app.

If you have issues you should verify:

- You're not using any of the removed props.

```diff
useHead({
  meta: [{ 
    name: 'description', 
    // meta tags don't need a vmid, or a key    
-   vmid: 'description' 
-   hid: 'description'
  }]
})
```

- If you're using [Template Params](https://unhead.unjs.io/docs/head/guides/plugins/template-params) or [Alias Tag Sorting](https://unhead.unjs.io/docs/head/guides/plugins/alias-sorting), you will need to explicitly opt in to these features now.

```ts
import { AliasSortingPlugin, TemplateParamsPlugin } from '@unhead/vue/plugins'

export default defineNuxtPlugin({
  setup () {
    const unhead = injectHead()
    unhead.use(TemplateParamsPlugin)
    unhead.use(AliasSortingPlugin)
  },
})
```

While not required it's recommended to update any imports from `@unhead/vue` to `#imports` or `nuxt/app`.

```diff
-import { useHead } from '@unhead/vue'
+import { useHead } from '#imports'
```

If you still have issues you may revert to the v1 behavior by enabling the `head.legacy` config.

```ts
export default defineNuxtConfig({
  unhead: {
    legacy: true,
  },
})
```

### New DOM Location for SPA Loading Screen

🚦 **Impact Level**: Minimal

#### What Changed

When rendering a client-only page (with `ssr: false`), we optionally render a loading screen (from `~/app/spa-loading-template.html` - note that this has also changed to `~/spa-loading-template.html` in Nuxt 4), within the Nuxt app root:

```html
<div id="__nuxt">
  <!-- spa loading template -->
</div>
```

Now, we default to rendering the template alongside the Nuxt app root:

```html
<div id="__nuxt"></div>
<!-- spa loading template -->
```

#### Reasons for Change

This allows the spa loading template to remain in the DOM until the Vue app suspense resolves, preventing a flash of white.

#### Migration Steps

If you were targeting the spa loading template with CSS or `document.queryElement` you will need to update your selectors. For this purpose you can use the new `app.spaLoaderTag` and `app.spaLoaderAttrs` configuration options.

Alternatively, you can revert to the previous behaviour with:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    spaLoadingTemplateLocation: 'within',
  },
})
```

### Parsed `error.data`

🚦 **Impact Level**: Minimal

It was possible to throw an error with a `data` property, but this was not parsed. Now, it is parsed and made available in the `error` object. Although a fix, this is technically a breaking change if you were relying on the previous behavior and parsing it manually.

#### Migration Steps

Update your custom `error.vue` to remove any additional parsing of `error.data`:

```diff
<script setup lang="ts">
  import type { NuxtError } from '#app'

  const props = defineProps({
    error: Object as () => NuxtError
  })

- const data = JSON.parse(error.data)
+ const data = error.data
  </script>
```

### More Granular Inline Styles

🚦 **Impact Level**: Moderate

Nuxt will now only inline styles for Vue components, not global CSS.

#### What Changed

Previously, Nuxt would inline all CSS, including global styles, and remove `<link>` elements to separate CSS files. Now, Nuxt will only do this for Vue components (which previously produced separate chunks of CSS). We think this is a better balance of reducing separate network requests (just as before, there will not be separate requests for individual `.css` files per-page or per-component on the initial load), as well as allowing caching of a single global CSS file and reducing the document download size of the initial request.

#### Migration Steps

This feature is fully configurable and you can revert to the previous behavior by setting `inlineStyles: true` to inline global CSS as well as per-component CSS.

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  features: {
    inlineStyles: true,
  },
})
```

### Scan Page Meta After Resolution

🚦 **Impact Level**: Minimal

#### What Changed

We now scan page metadata (defined in `definePageMeta`) *after* calling the `pages:extend` hook rather than before.

#### Reasons for Change

This was to allow scanning metadata for pages that users wanted to add in `pages:extend`. We still offer an opportunity to change or override page metadata in a new `pages:resolved` hook.

#### Migration Steps

If you want to override page metadata, do that in `pages:resolved` rather than in `pages:extend`.

```diff
export default defineNuxtConfig({
    hooks: {
-     'pages:extend'(pages) {
+     'pages:resolved'(pages) {
        const myPage = pages.find(page => page.path === '/')
        myPage.meta ||= {}
        myPage.meta.layout = 'overridden-layout'
      }
    }
  })
```

Alternatively, you can revert to the previous behaviour with:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: true,
  },
})
```

### Shared Prerender Data

🚦 **Impact Level**: Medium

#### What Changed

We enabled a previously experimental feature to share data from `useAsyncData` and `useFetch` calls, across different pages. See [original PR](https://github.com/nuxt/nuxt/pull/24894).

#### Reasons for Change

This feature automatically shares payload *data* between pages that are prerendered. This can result in a significant performance improvement when prerendering sites that use `useAsyncData` or `useFetch` and fetch the same data in different pages.

For example, if your site requires a `useFetch` call for every page (for example, to get navigation data for a menu, or site settings from a CMS), this data would only be fetched once when prerendering the first page that uses it, and then cached for use when prerendering other pages.

#### Migration Steps

Make sure that any unique key of your data is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch` should do this automatically for you.)

```ts [app/pages/test/[slug].vue]
// This would be unsafe in a dynamic page (e.g. `[slug].vue`) because the route slug makes a difference
// to the data fetched, but Nuxt can't know that because it's not reflected in the key.
const route = useRoute()
const { data } = await useAsyncData(async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
// Instead, you should use a key that uniquely identifies the data fetched.
const { data } = await useAsyncData(route.params.slug, async () => {
  return await $fetch(`/api/my-page/${route.params.slug}`)
})
```

Alternatively, you can disable this feature with:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    sharedPrerenderData: false,
  },
})
```

### Default `data` and `error` values in `useAsyncData` and `useFetch`

🚦 **Impact Level**: Minimal

#### What Changed

`data` and `error` objects returned from `useAsyncData` will now default to `undefined`.

#### Reasons for Change

Previously `data` was initialized to `null` but reset in `clearNuxtData` to `undefined`. `error` was initialized to `null`. This change is to bring greater consistency.

#### Migration Steps

If you were checking if `data.value` or `error.value` were `null`, you can update these checks to check for `undefined` instead.

<tip>

You can automate this step by running `npx codemod@latest nuxt/4/default-data-error-value`

</tip>

### Removal of deprecated `boolean` values for `dedupe` option when calling `refresh` in `useAsyncData` and `useFetch`

🚦 **Impact Level**: Minimal

#### What Changed

Previously it was possible to pass `dedupe: boolean` to `refresh`. These were aliases of `cancel` (`true`) and `defer` (`false`).

```ts [app/app.vue]twoslash
// @errors: 2322
const { refresh } = await useAsyncData(() => Promise.resolve({ message: 'Hello, Nuxt!' }))

async function refreshData () {
  await refresh({ dedupe: true })
}
```

#### Reasons for Change

These aliases were removed, for greater clarity.

The issue came up when adding `dedupe` as an option to `useAsyncData`, and we removed the boolean values as they ended up being *opposites*.

`refresh({ dedupe: false })` meant **do not cancel existing requests in favour of this new one**. But passing `dedupe: true` within the options of `useAsyncData` means **do not make any new requests if there is an existing pending request.** (See [PR](https://github.com/nuxt/nuxt/pull/24564#pullrequestreview-1764584361).)

#### Migration Steps

The migration should be straightforward:

```diff
const { refresh } = await useAsyncData(async () => ({ message: 'Hello, Nuxt 3!' }))
  
  async function refreshData () {
-   await refresh({ dedupe: true })
+   await refresh({ dedupe: 'cancel' })

-   await refresh({ dedupe: false })
+   await refresh({ dedupe: 'defer' })
  }
```

<tip>

You can automate this step by running `npx codemod@latest nuxt/4/deprecated-dedupe-value`

</tip>

### Respect defaults when clearing `data` in `useAsyncData` and `useFetch`

🚦 **Impact Level**: Minimal

#### What Changed

If you provide a custom `default` value for `useAsyncData`, this will now be used when calling `clear` or `clearNuxtData` and it will be reset to its default value rather than simply unset.

#### Reasons for Change

Often users set an appropriately empty value, such as an empty array, to avoid the need to check for `null`/`undefined` when iterating over it. This should be respected when resetting/clearing the data.

### Alignment of `pending` value in `useAsyncData` and `useFetch`

🚦 **Impact Level**: Medium

The `pending` object returned from `useAsyncData`, `useFetch`, `useLazyAsyncData` and `useLazyFetch` is now a computed property that is `true` only when `status` is also pending.

#### What Changed

Now, when `immediate: false` is passed, `pending` will be `false` until the first request is made. This is a change from the previous behavior, where `pending` was always `true` until the first request was made.

#### Reasons for Change

This aligns the meaning of `pending` with the `status` property, which is also `pending` when the request is in progress.

#### Migration Steps

If you rely on the `pending` property, ensure that your logic accounts for the new behavior where `pending` will only be `true` when the status is also pending.

```diff
<template>
-   <div v-if="!pending">
+   <div v-if="status === 'success'">
      <p>Data: {{ data }}</p>
    </div>
    <div v-else>
      <p>Loading...</p>
    </div>
  </template>
  <script setup lang="ts">
  const { data, pending, execute, status } = await useAsyncData(() => fetch('/api/data'), {
    immediate: false
  })
  onMounted(() => execute())
  </script>
```

Alternatively, you can temporarily revert to the previous behavior with:

```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    pendingWhenIdle: true,
  },
})
```

### Key Change Behavior in `useAsyncData` and `useFetch`

🚦 **Impact Level**: Medium

#### What Changed

When using reactive keys in `useAsyncData` or `useFetch`, Nuxt automatically refetches data when the key changes. When `immediate: false` is set, `useAsyncData` will only fetch data when the key changes if the data has already been fetched once.

Previously, `useFetch` had slightly different behavior. It would always fetch data when the key changed.

Now, `useFetch` and `useAsyncData` behave consistently - by only fetch data when the key changes if the data has already been fetched once.

#### Reasons for Change

This ensures consistent behavior between `useAsyncData` and `useFetch`, and prevents unexpected fetches. If you have set `immediate: false`, then you must call `refresh` or `execute` or data will never be fetched in `useFetch` or `useAsyncData`.

#### Migration Steps

This change should generally improve the expected behavior, but if you were expecting changing the key or options of a non-immediate `useFetch`, you now will need to trigger it manually the first time.

```diff
const id = ref('123')
  const { data, execute } = await useFetch('/api/test', {
    query: { id },
    immediate: false
  )
+ watch(id, () => execute(), { once: true })
```

To opt out of this behavior:

```ts
// Or globally in your Nuxt config
export default defineNuxtConfig({
  experimental: {
    alwaysRunFetchOnKeyChange: true,
  },
})
```

### Shallow Data Reactivity in `useAsyncData` and `useFetch`

🚦 **Impact Level**: Minimal

The `data` object returned from `useAsyncData`, `useFetch`, `useLazyAsyncData` and `useLazyFetch` is now a `shallowRef` rather than a `ref`.

#### What Changed

When new data is fetched, anything depending on `data` will still be reactive because the entire object is replaced. But if your code changes a property *within* that data structure, this will not trigger any reactivity in your app.

#### Reasons for Change

This brings a **significant** performance improvement for deeply nested objects and arrays because Vue does not need to watch every single property/array for modification. In most cases, `data` should also be immutable.

#### Migration Steps

In most cases, no migration steps are required, but if you rely on the reactivity of the data object then you have two options:

1. You can granularly opt in to deep reactivity on a per-composable basis:
```diff
- const { data } = useFetch('/api/test')
+ const { data } = useFetch('/api/test', { deep: true })
```
2. You can change the default behavior on a project-wide basis (not recommended):
```ts [nuxt.config.ts]twoslash
export default defineNuxtConfig({
  experimental: {
    defaults: {
      useAsyncData: {
        deep: true,
      },
    },
  },
})
```

<tip>

If you need to, you can automate this step by running `npx codemod@latest nuxt/4/shallow-function-reactivity`

</tip>

### Absolute Watch Paths in `builder:watch`

🚦 **Impact Level**: Minimal

#### What Changed

The Nuxt `builder:watch` hook now emits a path which is absolute rather than relative to your project `srcDir`.

#### Reasons for Change

This allows us to support watching paths which are outside your `srcDir`, and offers better support for layers and other more complex patterns.

#### Migration Steps

We have already proactively migrated the public Nuxt modules which we are aware use this hook. See [issue #25339](https://github.com/nuxt/nuxt/issues/25339).

However, if you are a module author using the `builder:watch` hook and wishing to remain backwards/forwards compatible, you can use the following code to ensure that your code works the same in both Nuxt v3 and Nuxt v4:

```diff
+ import { relative, resolve } from 'node:fs'
  // ...
  nuxt.hook('builder:watch', async (event, path) => {
+   path = relative(nuxt.options.srcDir, resolve(nuxt.options.srcDir, path))
    // ...
  })
```

<tip>

You can automate this step by running `npx codemod@latest nuxt/4/absolute-watch-path`

</tip>

### Removal of `window.__NUXT__` object

#### What Changed

We are removing the global `window.__NUXT__` object after the app finishes hydration.

#### Reasons for Change

This opens the way to multi-app patterns ([#21635](https://github.com/nuxt/nuxt/issues/21635)) and enables us to focus on a single way to access Nuxt app data - `useNuxtApp()`.

#### Migration Steps

The data is still available, but can be accessed with `useNuxtApp().payload`:

```diff
- console.log(window.__NUXT__)
+ console.log(useNuxtApp().payload)
```

### Directory index scanning

🚦 **Impact Level**: Medium

#### What Changed

Child folders in your `app/middleware/` folder are also scanned for `index` files and these are now also registered as middleware in your project.

#### Reasons for Change

Nuxt scans a number of folders automatically, including `app/middleware/` and `app/plugins/`.

Child folders in your `app/plugins/` folder are scanned for `index` files and we wanted to make this behavior consistent between scanned directories.

#### Migration Steps

Probably no migration is necessary but if you wish to revert to previous behavior you can add a hook to filter out these middleware:

```ts
export default defineNuxtConfig({
  hooks: {
    'app:resolve' (app) {
      app.middleware = app.middleware.filter(mw => !/\/index\.[^/]+$/.test(mw.path))
    },
  },
})
```

### Template Compilation Changes

🚦 **Impact Level**: Minimal

#### What Changed

Previously, Nuxt used `lodash/template` to compile templates located on the file system using the `.ejs` file format/syntax.

In addition, we provided some template utilities (`serialize`, `importName`, `importSources`) which could be used for code-generation within these templates, which are now being removed.

#### Reasons for Change

In Nuxt v3 we moved to a 'virtual' syntax with a `getContents()` function which is much more flexible and performant.

In addition, `lodash/template` has had a succession of security issues. These do not really apply to Nuxt projects because it is being used at build-time, not runtime, and by trusted code. However, they still appear in security audits. Moreover, `lodash` is a hefty dependency and is unused by most projects.

Finally, providing code serialization functions directly within Nuxt is not ideal. Instead, we maintain projects like [unjs/knitwork](https://github.com/unjs/knitwork) which can be dependencies of your project, and where security issues can be reported/resolved directly without requiring an upgrade of Nuxt itself.

#### Migration Steps

We have raised PRs to update modules using EJS syntax, but if you need to do this yourself, you have three backwards/forwards-compatible alternatives:

- Moving your string interpolation logic directly into `getContents()`.
- Using a custom function to handle the replacement, such as in [https://github.com/nuxt-modules/color-mode/pull/240](https://github.com/nuxt-modules/color-mode/pull/240).
- Use `es-toolkit/compat` (a drop-in replacement for lodash template), as a dependency of *your* project rather than Nuxt:

```diff
+ import { readFileSync } from 'node:fs'
+ import { template } from 'es-toolkit/compat'
  // ...
  addTemplate({
    fileName: 'appinsights-vue.js'
    options: { /* some options */ },
-   src: resolver.resolve('./runtime/plugin.ejs'),
+   getContents({ options }) {
+     const contents = readFileSync(resolver.resolve('./runtime/plugin.ejs'), 'utf-8')
+     return template(contents)({ options })
+   },
  })
```

Finally, if you are using the template utilities (`serialize`, `importName`, `importSources`), you can replace them as follows with utilities from `knitwork`:

```ts
import { genDynamicImport, genImport, genSafeVariableName } from 'knitwork'

const serialize = (data: any) => JSON.stringify(data, null, 2).replace(/"\{(.+)\}"(?=,?$)/gm, r => JSON.parse(r).replace(/^\{(.*)\}$/, '$1'))

const importSources = (sources: string | string[], { lazy = false } = {}) => {
  return toArray(sources).map((src) => {
    if (lazy) {
      return `const ${genSafeVariableName(src)} = ${genDynamicImport(src, { comment: `webpackChunkName: ${JSON.stringify(src)}` })}`
    }
    return genImport(src, genSafeVariableName(src))
  }).join('\n')
}

const importName = genSafeVariableName
```

<tip>

You can automate this step by running `npx codemod@latest nuxt/4/template-compilation-changes`

</tip>

### Default TypeScript Configuration Changes

🚦 **Impact Level**: Minimal

#### What Changed

`compilerOptions.noUncheckedIndexedAccess` is now `true` instead of `false`.

#### Reasons for Change

This change is a follow up to a prior [3.12 config update](https://github.com/nuxt/nuxt/pull/27485) where we improved our defaults, mostly adhering to [TotalTypeScript's recommendations](https://www.totaltypescript.com/tsconfig-cheat-sheet).

#### Migration Steps

There are two approaches:

1. Run a typecheck on your app and fix any new errors (recommended).
2. Override the new default in your `nuxt.config.ts`:```ts
export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        noUncheckedIndexedAccess: false,
      },
    },
  },
})
```

### TypeScript Configuration Splitting

🚦 **Impact Level**: Minimal

#### What Changed

Nuxt now generates separate TypeScript configurations for different contexts to provide better type-checking experiences:

1. **New TypeScript configuration files**: Nuxt now generates additional TypeScript configurations:
  - `.nuxt/tsconfig.app.json` - For your app code (Vue components, composables, etc.)
  - `.nuxt/tsconfig.server.json` - For your server-side code (Nitro/server directory)
  - `.nuxt/tsconfig.node.json` - For your build-time code (modules, `nuxt.config.ts`, etc.)
  - `.nuxt/tsconfig.shared.json` - For code shared between app and server contexts (like types and non-environment specific utilities)
  - `.nuxt/tsconfig.json` - Legacy configuration for backward compatibility
2. **Backward compatibility**: Existing projects that extend `.nuxt/tsconfig.json` will continue to work as before.
3. **Opt-in project references**: New projects or those wanting better type checking can adopt TypeScript's project references feature.
4. **Context-specific type checking**: Each context now has appropriate compiler options and includes/excludes for its specific environment.
5. **New typescript.nodeTsConfig option**: You can now customize the TypeScript configuration for Node.js build-time code.

#### Reasons for Change

This change provides several benefits:

1. **Better type safety**: Each context (app, server, build-time) gets appropriate type checking with context-specific globals and APIs.
2. **Improved IDE experience**: Better IntelliSense and error reporting for different parts of your codebase.
3. **Cleaner separation**: Server code won't incorrectly suggest client-side APIs and vice versa.
4. **Performance**: TypeScript can more efficiently check code with properly scoped configurations.

For example, auto-imports are not available in your `nuxt.config.ts` (but previously this was not flagged by TypeScript). And while IDEs recognized the separate context hinted by `tsconfig.json` in your `server/` directory, this was not reflected in type-checking (requiring a separate step).

#### Migration Steps

**No migration is required** - existing projects will continue to work as before.

However, to take advantage of improved type checking, you can opt in to the new project references approach:

1. **Update your root tsconfig.json** to use project references:<note>

If your `tsconfig.json` currently has an `"extends": "./.nuxt/tsconfig.json"` line, **remove it** before adding the references. Project references and extends are mutually exclusive.

</note>

```json
{
  // Remove "extends": "./.nuxt/tsconfig.json" if present
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ]
}
```
2. **Remove any manual server tsconfig.json** files (like `server/tsconfig.json`) that extended `.nuxt/tsconfig.server.json`.
3. **Update your type checking scripts** to use the build flag for project references:```diff
- "typecheck": "nuxt prepare && vue-tsc --noEmit"
+ "typecheck": "nuxt prepare && vue-tsc -b --noEmit"
```
4. **Move all type augmentations into their appropriate context**:
  - If you are augmenting types for the app context, move the files to the `app/` directory.
  - If you are augmenting types for the server context, move the files to the `server/` directory.
  - If you are augmenting types that are **shared between the app and server**, move the files to the `shared/` directory.<warning>

Augmenting types from outside the `app/`, `server/`, or `shared/` directories will not work with the new project references setup.

</warning>
5. **Configure TypeScript options** if needed:```ts
export default defineNuxtConfig({
  typescript: {
    // customize tsconfig.app.json
    tsConfig: {
      // ...
    },
    // customize tsconfig.shared.json
    sharedTsConfig: {
      // ...
    },
    // customize tsconfig.node.json
    nodeTsConfig: {
      // ...
    },
  },
  nitro: {
    typescript: {
      // customize tsconfig.server.json
      tsConfig: {
        // ...
      },
    },
  },
})
```
6. **Update any CI/build scripts** that run TypeScript checking to ensure they use the new project references approach.

The new configuration provides better type safety and IntelliSense for projects that opt in, while maintaining full backward compatibility for existing setups.

### Removal of Experimental Features

🚦 **Impact Level**: Minimal

#### What Changed

Four experimental features are no longer configurable in Nuxt 4:

- `experimental.treeshakeClientOnly` will be `true` (default since v3.0)
- `experimental.configSchema` will be `true` (default since v3.3)
- `experimental.polyfillVueUseHead` will be `false` (default since v3.4)
- `experimental.respectNoSSRHeader` will be `false` (default since v3.4)
- `vite.devBundler` is no longer configurable - it will use `vite-node` by default

#### Reasons for Change

These options have been set to their current values for some time and we do not have a reason to believe that they need to remain configurable.

#### Migration Steps

- `polyfillVueUseHead` is implementable in user-land with [this plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
- `respectNoSSRHeader`is implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)

### Removal of Top-Level `generate` Configuration

🚦 **Impact Level**: Minimal

#### What Changed

The top-level `generate` configuration option is no longer available in Nuxt 4. This includes all of its properties:

- `generate.exclude` - for excluding routes from prerendering
- `generate.routes` - for specifying routes to prerender

#### Reasons for Change

The top level `generate` configuration was a holdover from Nuxt 2. We've supported `nitro.prerender` for a while now, and it is the preferred way to configure prerendering in Nuxt 3+.

#### Migration Steps

Replace `generate` configuration with the corresponding `nitro.prerender` options:

```diff
export default defineNuxtConfig({
- generate: {
-   exclude: ['/admin', '/private'],
-   routes: ['/sitemap.xml', '/robots.txt']
- }
+ nitro: {
+   prerender: {
+     ignore: ['/admin', '/private'],
+     routes: ['/sitemap.xml', '/robots.txt']
+   }
+ }
})
```

<read-more to="https://nitro.build/config#prerender">

Read more about Nitro's prerender configuration options.

</read-more>

## Nuxt 2 vs. Nuxt 3+

In the table below, there is a quick comparison between 3 versions of Nuxt:

<table>
<thead>
  <tr>
    <th>
      Feature / Version
    </th>
    
    <th>
      Nuxt 2
    </th>
    
    <th>
      Nuxt Bridge
    </th>
    
    <th>
      Nuxt 3+
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Vue
    </td>
    
    <td>
      2
    </td>
    
    <td>
      2
    </td>
    
    <td>
      3
    </td>
  </tr>
  
  <tr>
    <td>
      Stability
    </td>
    
    <td>
      😊 Stable
    </td>
    
    <td>
      😊 Stable
    </td>
    
    <td>
      😊 Stable
    </td>
  </tr>
  
  <tr>
    <td>
      Performance
    </td>
    
    <td>
      🏎 Fast
    </td>
    
    <td>
      ✈️ Faster
    </td>
    
    <td>
      🚀 Fastest
    </td>
  </tr>
  
  <tr>
    <td>
      Nitro Engine
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      ESM support
    </td>
    
    <td>
      🌙 Partial
    </td>
    
    <td>
      👍 Better
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      TypeScript
    </td>
    
    <td>
      ☑️ Opt-in
    </td>
    
    <td>
      🚧 Partial
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      Composition API
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      🚧 Partial
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      Options API
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      Components Auto Import
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <script setup>
      </code>
      
       syntax
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      🚧 Partial
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      Auto Imports
    </td>
    
    <td>
      ❌
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      webpack
    </td>
    
    <td>
      4
    </td>
    
    <td>
      4
    </td>
    
    <td>
      5
    </td>
  </tr>
  
  <tr>
    <td>
      Vite
    </td>
    
    <td>
      ⚠️ Partial
    </td>
    
    <td>
      🚧 Partial
    </td>
    
    <td>
      ✅
    </td>
  </tr>
  
  <tr>
    <td>
      Nuxt CLI
    </td>
    
    <td>
      ❌ Old
    </td>
    
    <td>
      ✅ nuxt
    </td>
    
    <td>
      ✅ nuxt
    </td>
  </tr>
  
  <tr>
    <td>
      Static sites
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
    
    <td>
      ✅
    </td>
  </tr>
</tbody>
</table>

## Nuxt 2 to Nuxt 3+

The migration guide provides a step-by-step comparison of Nuxt 2 features to Nuxt 3+ features and guidance to adapt your current application.

<read-more to="/docs/4.x/migration/overview">

Check out the **guide to migrating from Nuxt 2 to Nuxt 3**.

</read-more>

## Nuxt 2 to Nuxt Bridge

If you prefer to progressively migrate your Nuxt 2 application to Nuxt 3, you can use Nuxt Bridge. Nuxt Bridge is a compatibility layer that allows you to use Nuxt 3+ features in Nuxt 2 with an opt-in mechanism.

<read-more to="/docs/4.x/bridge/overview">

**Migrate from Nuxt 2 to Nuxt Bridge**

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-app-config.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-app-config.md

# useAppConfig

> Access the reactive app config defined in the project.

## Usage

```ts
const appConfig = useAppConfig()

console.log(appConfig)
```

<read-more to="/docs/4.x/directory-structure/app/app-config">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-async-data.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-async-data.md

# useAsyncData

> useAsyncData provides access to data that resolves asynchronously in an SSR-friendly composable.

Within your pages, components, and plugins you can use useAsyncData to get access to data that resolves asynchronously.

<note>

[`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a composable meant to be called directly in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context). It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client **without re-fetching the data on client side** when the page hydrates.

</note>

## Usage

```vue [app/pages/index.vue]
<script setup lang="ts">
const { data, status, pending, error, refresh, clear } = await useAsyncData(
  'mountains',
  (_nuxtApp, { signal }) => $fetch('https://api.nuxtjs.dev/mountains', { signal }),
)
</script>
```

<warning to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata">

If you're using a custom `useAsyncData` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.

</warning>

<note>

`data`, `status`, `pending` and `error` are Vue refs and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.

</note>

### Watch Params

The built-in `watch` option allows automatically rerunning the fetcher function when any changes are detected.

```vue [app/pages/index.vue]
<script setup lang="ts">
const page = ref(1)
const { data: posts } = await useAsyncData(
  'posts',
  (_nuxtApp, { signal }) => $fetch('https://fakeApi.com/posts', {
    params: {
      page: page.value,
    },
    signal,
  }), {
    watch: [page],
  },
)
</script>
```

### Reactive Keys

You can use a computed ref, plain ref or a getter function as the key, allowing for dynamic data fetching that automatically updates when the key changes:

```vue [app/pages/[id].vue]
<script setup lang="ts">
const route = useRoute()
const userId = computed(() => `user-${route.params.id}`)

// When the route changes and userId updates, the data will be automatically refetched
const { data: user } = useAsyncData(
  userId,
  () => fetchUserById(route.params.id),
)
</script>
```

### Make your `handler` abortable

You can make your `handler` function abortable by using the `signal` provided in the second argument. This is useful for cancelling requests when they are no longer needed, such as when a user navigates away from a page. `$fetch` natively supports abort signals.

```ts
const { data, error } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
)

refresh() // will actually cancel the $fetch request (if dedupe: cancel)
refresh() // will actually cancel the $fetch request (if dedupe: cancel)
refresh()

clear() // will cancel the latest pending handler
```

You can also pass an `AbortSignal` to the `refresh`/`execute` function to cancel individual requests manually.

```ts
const { refresh } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => $fetch('/api/users', { signal }),
)
let abortController: AbortController | undefined

function handleUserAction () {
  abortController = new AbortController()
  refresh({ signal: abortController.signal })
}

function handleCancel () {
  abortController?.abort() // aborts the ongoing refresh request
}
```

If your `handler` function does not support abort signals, you can implement your own abort logic using the `signal` provided.

```ts
const { data, error } = await useAsyncData(
  'users',
  (_nuxtApp, { signal }) => {
    return new Promise((resolve, reject) => {
      signal?.addEventListener('abort', () => {
        reject(new Error('Request aborted'))
      })
      return Promise.resolve(callback.call(this, yourHandler)).then(resolve, reject)
    })
  },
)
```

The handler signal will be aborted when:

- A new request is made with `dedupe: 'cancel'`
- The `clear` function is called
- The `options.timeout` duration is exceeded

<warning>

[`useAsyncData`](/docs/4.x/api/composables/use-async-data) is a reserved function name transformed by the compiler, so you should not name your own function [`useAsyncData`](/docs/4.x/api/composables/use-async-data).

</warning>

<read-more to="/docs/4.x/getting-started/data-fetching#useasyncdata">



</read-more>

## Params

- `key`: a unique key to ensure that data fetching can be properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file name and line number of the instance of `useAsyncData` will be generated for you.
- `handler`: an asynchronous function that must return a truthy value (for example, it should not be `undefined` or `null`) or the request may be duplicated on the client side.
<warning>

The `handler` function should be **side-effect free** to ensure predictable behavior during SSR and CSR hydration. If you need to trigger side effects, use the [`callOnce`](/docs/4.x/api/utils/call-once) utility to do so.

</warning>
- `options`:

  - `server`: whether to fetch the data on the server (defaults to `true`)
  - `lazy`: whether to resolve the async function after loading the route, instead of blocking client-side navigation (defaults to `false`)
  - `immediate`: when set to `false`, will prevent the request from firing immediately. (defaults to `true`)
  - `default`: a factory function to set the default value of the `data`, before the async function resolves - useful with the `lazy: true` or `immediate: false` option
  - `transform`: a function that can be used to alter `handler` function result after resolving
  - `getCachedData`: Provide a function which returns cached data. An `undefined` return value will trigger a fetch. By default, this is:
  ```ts
  const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
    ? nuxtApp.payload.data[key]
    : nuxtApp.static.data[key]
  ```
  
  
  Which only caches data when `experimental.payloadExtraction` of `nuxt.config` is enabled.
  - `pick`: only pick specified keys in this array from the `handler` function result
  - `watch`: watch reactive sources to auto-refresh
  - `deep`: return data in a deep ref object. It is `false` by default to return data in a shallow ref object, which can improve performance if your data does not need to be deeply reactive.
  - `dedupe`: avoid fetching same key more than once at a time (defaults to `cancel`). Possible options:
  
    - `cancel` - cancels existing requests when a new one is made
    - `defer` - does not make new requests at all if there is a pending request
  - `timeout` - a number in milliseconds to wait before timing out the request (defaults to `undefined`, which means no timeout)

<note>

Under the hood, `lazy: false` uses `<Suspense>` to block the loading of the route before the data has been fetched. Consider using `lazy: true` and implementing a loading state instead for a snappier user experience.

</note>

<read-more to="/docs/4.x/api/composables/use-lazy-async-data">

You can use `useLazyAsyncData` to have the same behavior as `lazy: true` with `useAsyncData`.

</read-more>

<video-accordion title="Watch a video from Alexander Lichter about client-side caching with getCachedData" video-id="aQPR0xn-MMk">



</video-accordion>

### Shared State and Option Consistency

When using the same key for multiple `useAsyncData` calls, they will share the same `data`, `error`, `status` and `pending` refs. This ensures consistency across components but requires option consistency.

The following options **must be consistent** across all calls with the same key:

- `handler` function
- `deep` option
- `transform` function
- `pick` array
- `getCachedData` function
- `default` value

The following options **can differ** without triggering warnings:

- `server`
- `lazy`
- `immediate`
- `dedupe`
- `watch`

```ts
// ❌ This will trigger a development warning
const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: false })
const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { deep: true })

// ✅ This is allowed
const { data: users1 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: true })
const { data: users2 } = useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', { signal }), { immediate: false })
```

<tip>

Keyed state created using `useAsyncData` can be retrieved across your Nuxt application using [`useNuxtData`](/docs/4.x/api/composables/use-nuxt-data).

</tip>

## Return Values

- `data`: the result of the asynchronous function that is passed in.
- `refresh`/`execute`: a function that can be used to refresh the data returned by the `handler` function.
- `error`: an error object if the data fetching failed.
- `status`: a string indicating the status of the data request:

  - `idle`: when the request has not started, such as:
  
    - when `execute` has not yet been called and `{ immediate: false }` is set
    - when rendering HTML on the server and `{ server: false }` is set
  - `pending`: the request is in progress
  - `success`: the request has completed successfully
  - `error`: the request has failed
- `pending`: a `Ref<boolean>` that is `true` while the request is in progress (that is, while `status.value === 'pending'`).
- `clear`: a function that can be used to set `data` to `undefined` (or the value of `options.default()` if provided), set `error` to `undefined`, set `status` to `idle`, and mark any currently pending requests as cancelled.

By default, Nuxt waits until a `refresh` is finished before it can be executed again.

<note>

If you have not fetched data on the server (for example, with `server: false`), then the data *will not* be fetched until hydration completes. This means even if you await [`useAsyncData`](/docs/4.x/api/composables/use-async-data) on the client side, `data` will remain `undefined` within `<script setup>`.

</note>

## Type

```ts [Signature]
export type AsyncDataHandler<ResT> = (nuxtApp: NuxtApp, options: { signal: AbortSignal }) => Promise<ResT>

export function useAsyncData<DataT, DataE> (
  handler: AsyncDataHandler<DataT>,
  options?: AsyncDataOptions<DataT>,
): AsyncData<DataT, DataE>
export function useAsyncData<DataT, DataE> (
  key: MaybeRefOrGetter<string>,
  handler: AsyncDataHandler<DataT>,
  options?: AsyncDataOptions<DataT>,
): Promise<AsyncData<DataT, DataE>>

type AsyncDataOptions<DataT> = {
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  default?: () => DataT | Ref<DataT> | null
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  watch?: MultiWatchSources | false
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  timeout?: number
}

type AsyncDataRequestContext = {
  /** The reason for this data request */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | undefined>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | undefined>
  status: Ref<AsyncDataRequestStatus>
  pending: Ref<boolean>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
```

<read-more to="/docs/4.x/getting-started/data-fetching">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/use-cookie.md

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-cookie.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/use-cookie.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-cookie.md

# useCookie

> useCookie is an SSR-friendly composable to read and write cookies.

## Usage

Within your pages, components, and plugins, you can use `useCookie` to read and write cookies in an SSR-friendly way.

```ts
const cookie = useCookie(name, options)
```

<note>

`useCookie` only works in the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context).

</note>

<tip>

The returned ref will automatically serialize and deserialize cookie values to JSON.

</tip>

## Type

```ts [Signature]
import type { Ref } from 'vue'
import type { CookieParseOptions, CookieSerializeOptions } from 'cookie-es'

export interface CookieOptions<T = any> extends Omit<CookieSerializeOptions & CookieParseOptions, 'decode' | 'encode'> {
  decode?(value: string): T
  encode?(value: T): string
  default?: () => T | Ref<T>
  watch?: boolean | 'shallow'
  readonly?: boolean
}

export interface CookieRef<T> extends Ref<T> {}

export function useCookie<T = string | null | undefined> (
  name: string,
  options?: CookieOptions<T>,
): CookieRef<T>
```

## Parameters

`name`: The name of the cookie.

`options`: Options to control cookie behavior. The object can have the following properties:

Most of the options will be directly passed to the [cookie](https://github.com/jshttp/cookie) package.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        decode
      </code>
    </td>
    
    <td>
      <code>
        (value: string) => T
      </code>
    </td>
    
    <td>
      <code>
        decodeURIComponent
      </code>
      
       + <a href="https://github.com/unjs/destr" rel="nofollow">
        destr
      </a>
      
      .
    </td>
    
    <td>
      Custom function to decode the cookie value.  Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to decode a previously encoded cookie value into a JavaScript string or other object. <br />
      
       <strong>
        Note:
      </strong>
      
       If an error is thrown from this function, the original, non-decoded cookie value will be returned as the cookie's value.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encode
      </code>
    </td>
    
    <td>
      <code>
        (value: T) => string
      </code>
    </td>
    
    <td>
      <code>
        JSON.stringify
      </code>
      
       + <code>
        encodeURIComponent
      </code>
    </td>
    
    <td>
      Custom function to encode the cookie value. Since the value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      <code>
        () => T | Ref<T>
      </code>
    </td>
    
    <td>
      <code>
        undefined
      </code>
    </td>
    
    <td>
      Function returning the default value if the cookie does not exist.  The function can also return a <code>
        Ref
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        watch
      </code>
    </td>
    
    <td>
      <code>
        boolean | 'shallow'
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Whether to watch for changes and update the cookie. <code>
        true
      </code>
      
       for deep watch, <code>
        'shallow'
      </code>
      
       for shallow watch, i.e. data changes for only top level properties, <code>
        false
      </code>
      
       to disable. <br />
      
       <strong>
        Note:
      </strong>
      
       Refresh <code>
        useCookie
      </code>
      
       values manually when a cookie has changed with <a href="/docs/4.x/api/utils/refresh-cookie">
        <code>
          refreshCookie
        </code>
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        readonly
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If <code>
        true
      </code>
      
      , disables writing to the cookie.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        maxAge
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        undefined
      </code>
    </td>
    
    <td>
      Max age in seconds for the cookie, i.e. the value for the <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.2" rel="nofollow">
        <code>
          Max-Age
        </code>
        
         <code>
          Set-Cookie
        </code>
        
         attribute
      </a>
      
      . The given number will be converted to an integer by rounding down. By default, no maximum age is set.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        expires
      </code>
    </td>
    
    <td>
      <code>
        Date
      </code>
    </td>
    
    <td>
      <code>
        undefined
      </code>
    </td>
    
    <td>
      Expiration date for the cookie. By default, no expiration is set. Most clients will consider this a "non-persistent cookie" and will delete it on a condition like exiting a web browser application. <br />
      
       <strong>
        Note:
      </strong>
      
       The <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-5.3" rel="nofollow">
        cookie storage model specification
      </a>
      
       states that if both <code>
        expires
      </code>
      
       and <code>
        maxAge
      </code>
      
       is set, then <code>
        maxAge
      </code>
      
       takes precedence, but not all clients may obey this, so if both are set, they should point to the same date and time! <br />
      
      If neither of <code>
        expires
      </code>
      
       and <code>
        maxAge
      </code>
      
       is set, the cookie will be session-only and removed when the user closes their browser.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        httpOnly
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Sets the HttpOnly attribute. <br />
      
       <strong>
        Note:
      </strong>
      
       Be careful when setting this to <code>
        true
      </code>
      
      , as compliant clients will not allow client-side JavaScript to see the cookie in <code>
        document.cookie
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        secure
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Sets the <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.5" rel="nofollow">
        <code>
          Secure
        </code>
        
         <code>
          Set-Cookie
        </code>
        
         attribute
      </a>
      
      . <br />
      
      <strong>
        Note:
      </strong>
      
       Be careful when setting this to <code>
        true
      </code>
      
      , as compliant clients will not send the cookie back to the server in the future if the browser does not have an HTTPS connection. This can lead to hydration errors.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        partitioned
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Sets the <a href="https://datatracker.ietf.org/doc/html/draft-cutler-httpbis-partitioned-cookies#section-2.1" rel="nofollow">
        <code>
          Partitioned
        </code>
        
         <code>
          Set-Cookie
        </code>
        
         attribute
      </a>
      
      . <br />
      
      <strong>
        Note:
      </strong>
      
       This is an attribute that has not yet been fully standardized, and may change in the future. <br />
      
      This also means many clients may ignore this attribute until they understand it.<br />
      
      More information can be found in the <a href="https://github.com/privacycg/CHIPS" rel="nofollow">
        proposal
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        domain
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        undefined
      </code>
    </td>
    
    <td>
      Sets the <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.3" rel="nofollow">
        <code>
          Domain
        </code>
        
         <code>
          Set-Cookie
        </code>
        
         attribute
      </a>
      
      . By default, no domain is set, and most clients will consider applying the cookie only to the current domain.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        '/'
      </code>
    </td>
    
    <td>
      Sets the <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4" rel="nofollow">
        <code>
          Path
        </code>
        
         <code>
          Set-Cookie
        </code>
        
         attribute
      </a>
      
      . By default, the path is considered the <a href="https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.4" rel="nofollow">
        "default path"
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sameSite
      </code>
    </td>
    
    <td>
      <code>
        boolean | string
      </code>
    </td>
    
    <td>
      <code>
        undefined
      </code>
    </td>
    
    <td>
      Sets the <a href="https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7" rel="nofollow">
        <code>
          SameSite
        </code>
        
         <code>
          Set-Cookie
        </code>
        
         attribute
      </a>
      
      . <br />
      
      - <code>
        true
      </code>
      
       will set the <code>
        SameSite
      </code>
      
       attribute to <code>
        Strict
      </code>
      
       for strict same-site enforcement.<br />
      
      - <code>
        false
      </code>
      
       will not set the <code>
        SameSite
      </code>
      
       attribute.<br />
      
      - <code>
        'lax'
      </code>
      
       will set the <code>
        SameSite
      </code>
      
       attribute to <code>
        Lax
      </code>
      
       for lax same-site enforcement.<br />
      
      - <code>
        'none'
      </code>
      
       will set the <code>
        SameSite
      </code>
      
       attribute to <code>
        None
      </code>
      
       for an explicit cross-site cookie.<br />
      
      - <code>
        'strict'
      </code>
      
       will set the <code>
        SameSite
      </code>
      
       attribute to <code>
        Strict
      </code>
      
       for strict same-site enforcement.
    </td>
  </tr>
</tbody>
</table>

## Return Values

Returns a Vue `Ref<T>` representing the cookie value. Updating the ref will update the cookie (unless `readonly` is set). The ref is SSR-friendly and will work on both client and server.

## Examples

### Basic Usage

The example below creates a cookie called `counter`. If the cookie doesn't exist, it is initially set to a random value. Whenever we update the `counter` variable, the cookie will be updated accordingly.

```vue [app/app.vue]
<script setup lang="ts">
const counter = useCookie('counter')

counter.value ||= Math.round(Math.random() * 1000)
</script>

<template>
  <div>
    <h1>Counter: {{ counter || '-' }}</h1>
    <button @click="counter = null">
      reset
    </button>
    <button @click="counter--">
      -
    </button>
    <button @click="counter++">
      +
    </button>
  </div>
</template>
```

### Readonly Cookies

```vue
<script setup lang="ts">
const user = useCookie(
  'userInfo',
  {
    default: () => ({ score: -1 }),
    watch: false,
  },
)

if (user.value) {
  // the actual `userInfo` cookie will not be updated
  user.value.score++
}
</script>

<template>
  <div>User score: {{ user?.score }}</div>
</template>
```

### Writable Cookies

```vue
<script setup lang="ts">
const list = useCookie(
  'list',
  {
    default: () => [],
    watch: 'shallow',
  },
)

function add () {
  list.value?.push(Math.round(Math.random() * 1000))
  // list cookie won't be updated with this change
}

function save () {
  // the actual `list` cookie will be updated
  list.value &&= [...list.value]
}
</script>

<template>
  <div>
    <h1>List</h1>
    <pre>{{ list }}</pre>
    <button @click="add">
      Add
    </button>
    <button @click="save">
      Save
    </button>
  </div>
</template>
```

### Cookies in API Routes

You can use `getCookie` and `setCookie` from [`h3`](https://github.com/h3js/h3) package to set cookies in server API routes.

```ts [server/api/counter.ts]
export default defineEventHandler((event) => {
  // Read counter cookie
  let counter = getCookie(event, 'counter') || 0

  // Increase counter cookie by 1
  setCookie(event, 'counter', ++counter)

  // Send JSON response
  return { counter }
})
```

<link-example to="/docs/4.x/examples/advanced/use-cookie">



</link-example>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/advanced/use-custom-fetch-composable.md

# Source: https://nuxt.com/raw/docs/4.x/examples/advanced/use-custom-fetch-composable.md

# Use Custom Fetch Composable

> This example shows a convenient wrapper for the useFetch composable from nuxt. It allows you to customize the fetch request with default values and user authentication token.

<read-more to="/docs/guide/recipes/custom-usefetch">



</read-more>

<sandbox branch="main" dir="examples/advanced/use-custom-fetch-composable" file="composables/useCustomFetch.ts" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-error.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-error.md

# useError

> useError composable returns the global Nuxt error that is being handled.

## Usage

The `useError` composable returns the global Nuxt error that is being handled and is available on both client and server. It provides a reactive, SSR-friendly error state across your app.

```ts
const error = useError()
```

You can use this composable in your components, pages, or plugins to access or react to the current Nuxt error.

## Type

```ts
interface NuxtError<DataT = unknown> {
  status: number
  statusText: string
  message: string
  data?: DataT
  error?: true
}

export const useError: () => Ref<NuxtError | undefined>
```

## Parameters

This composable does not take any parameters.

## Return Values

Returns a `Ref` containing the current Nuxt error (or `undefined` if there is no error). The error object is reactive and will update automatically when the error state changes.

## Example

```vue
<script setup lang="ts">
const error = useError()

if (error.value) {
  console.error('Nuxt error:', error.value)
}
</script>
```

<read-more to="/docs/4.x/getting-started/error-handling">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-fetch.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-fetch.md

# useFetch

> Fetch data from an API endpoint with an SSR-friendly composable.

This composable provides a convenient wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`$fetch`](/docs/4.x/api/utils/dollarfetch).
It automatically generates a key based on URL and fetch options, provides type hints for request url based on server routes, and infers API response type.

<note>

`useFetch` is a composable meant to be called directly in a setup function, plugin, or route middleware. It returns reactive composables and handles adding responses to the Nuxt payload so they can be passed from server to client without re-fetching the data on client side when the page hydrates.

</note>

## Usage

```vue [app/pages/modules.vue]
<script setup lang="ts">
const { data, status, error, refresh, clear } = await useFetch('/api/modules', {
  pick: ['title'],
})
</script>
```

<warning to="/docs/4.x/guide/recipes/custom-usefetch#custom-usefetchuseasyncdata">

If you're using a custom `useFetch` wrapper, do not await it in the composable as that can cause unexpected behavior. See recipe for custom async data fetcher.

</warning>

<note>

`data`, `status`, and `error` are Vue refs, and they should be accessed with `.value` when used within the `<script setup>`, while `refresh`/`execute` and `clear` are plain functions.

</note>

Using the `query` option, you can add search parameters to your query. This option is extended from [unjs/ofetch](https://github.com/unjs/ofetch) and is using [unjs/ufo](https://github.com/unjs/ufo) to create the URL. Objects are automatically stringified.

```ts
const param1 = ref('value1')
const { data, status, error, refresh } = await useFetch('/api/modules', {
  query: { param1, param2: 'value2' },
})
```

The above example results in `https://api.nuxt.com/modules?param1=value1&param2=value2`.

You can also use [interceptors](https://github.com/unjs/ofetch#%EF%B8%8F-interceptors):

```ts
const { data, status, error, refresh, clear } = await useFetch('/api/auth/login', {
  onRequest ({ request, options }) {
    // Set the request headers
    // note that this relies on ofetch >= 1.4.0 - you may need to refresh your lockfile
    options.headers.set('Authorization', '...')
  },
  onRequestError ({ request, options, error }) {
    // Handle the request errors
  },
  onResponse ({ request, response, options }) {
    // Process the response data
    localStorage.setItem('token', response._data.token)
  },
  onResponseError ({ request, response, options }) {
    // Handle the response errors
  },
})
```

### Reactive Keys and Shared State

You can use a computed ref or a plain ref as the URL, allowing for dynamic data fetching that automatically updates when the URL changes:

```vue [app/pages/[id].vue]
<script setup lang="ts">
const route = useRoute()
const id = computed(() => route.params.id)

// When the route changes and id updates, the data will be automatically refetched
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
</script>
```

When using `useFetch` with the same URL and options in multiple components, they will share the same `data`, `error` and `status` refs. This ensures consistency across components.

<tip>

Keyed state created using `useFetch` can be retrieved across your Nuxt application using [`useNuxtData`](/docs/4.x/api/composables/use-nuxt-data).

</tip>

<warning>

`useFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useFetch`.

</warning>

<warning>

If you encounter the `data` variable destructured from a `useFetch` returns a string and not a JSON parsed object then make sure your component doesn't include an import statement like `import { useFetch } from '@vueuse/core`.

</warning>

<video-accordion title="Watch the video from Alexander Lichter to avoid using useFetch the wrong way" video-id="njsGVmcWviY">



</video-accordion>

<read-more to="/docs/4.x/getting-started/data-fetching">



</read-more>

### Reactive Fetch Options

Fetch options can be provided as reactive, supporting `computed`, `ref` and [computed getters](https://vuejs.org/guide/essentials/computed). When a reactive fetch option is updated it will trigger a refetch using the updated resolved reactive value.

```ts
const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
})
// triggers a refetch: /api/search?q=new%20search
searchQuery.value = 'new search'
```

If needed, you can opt out of this behavior using `watch: false`:

```ts
const searchQuery = ref('initial')
const { data } = await useFetch('/api/search', {
  query: { q: searchQuery },
  watch: false,
})
// does not trigger a refetch
searchQuery.value = 'new search'
```

## Type

```ts [Signature]
export function useFetch<DataT, ErrorT> (
  url: string | Request | Ref<string | Request> | (() => string | Request),
  options?: UseFetchOptions<DataT>,
): Promise<AsyncData<DataT, ErrorT>>

type UseFetchOptions<DataT> = {
  key?: MaybeRefOrGetter<string>
  method?: MaybeRefOrGetter<string>
  query?: MaybeRefOrGetter<SearchParams>
  params?: MaybeRefOrGetter<SearchParams>
  body?: MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
  headers?: MaybeRefOrGetter<Record<string, string> | [key: string, value: string][] | Headers>
  baseURL?: MaybeRefOrGetter<string>
  server?: boolean
  lazy?: boolean
  immediate?: boolean
  getCachedData?: (key: string, nuxtApp: NuxtApp, ctx: AsyncDataRequestContext) => DataT | undefined
  deep?: boolean
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  default?: () => DataT
  transform?: (input: DataT) => DataT | Promise<DataT>
  pick?: string[]
  $fetch?: typeof globalThis.$fetch
  watch?: MultiWatchSources | false
  timeout?: MaybeRefOrGetter<number>
}

type AsyncDataRequestContext = {
  /** The reason for this data request */
  cause: 'initial' | 'refresh:manual' | 'refresh:hook' | 'watch'
}

type AsyncData<DataT, ErrorT> = {
  data: Ref<DataT | undefined>
  refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>
  execute: (opts?: AsyncDataExecuteOptions) => Promise<void>
  clear: () => void
  error: Ref<ErrorT | undefined>
  status: Ref<AsyncDataRequestStatus>
}

interface AsyncDataExecuteOptions {
  dedupe?: 'cancel' | 'defer'
  timeout?: number
  signal?: AbortSignal
}

type AsyncDataRequestStatus = 'idle' | 'pending' | 'success' | 'error'
```

## Parameters

- `URL` (`string | Request | Ref<string | Request> | () => string | Request`): The URL or request to fetch. Can be a string, a Request object, a Vue ref, or a function returning a string/Request. Supports reactivity for dynamic endpoints.
- `options` (object): Configuration for the fetch request. Extends [unjs/ofetch](https://github.com/unjs/ofetch) options and [`AsyncDataOptions`](/docs/4.x/api/composables/use-async-data#params). All options can be a static value, a `ref`, or a computed value.

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<string>
      </code>
    </td>
    
    <td>
      auto-gen
    </td>
    
    <td>
      Unique key for de-duplication. If not provided, generated from URL and options.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        method
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<string>
      </code>
    </td>
    
    <td>
      <code>
        'GET'
      </code>
    </td>
    
    <td>
      HTTP request method.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<SearchParams>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Query/search params to append to the URL. Alias: <code>
        params
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        params
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<SearchParams>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Alias for <code>
        query
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        body
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<RequestInit['body'] | Record<string, any>>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Request body. Objects are automatically stringified.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        headers
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<Record<string, string> | [key, value][] | Headers>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Request headers.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        baseURL
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<string>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Base URL for the request.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout
      </code>
    </td>
    
    <td>
      <code>
        MaybeRefOrGetter<number>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Timeout in milliseconds to abort the request.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cache
      </code>
    </td>
    
    <td>
      <code>
        boolean | string
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Cache control. Boolean disables cache, or use Fetch API values: <code>
        default
      </code>
      
      , <code>
        no-store
      </code>
      
      , etc.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        server
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Whether to fetch on the server.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        lazy
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      If true, resolves after route loads (does not block navigation).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        immediate
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      If false, prevents request from firing immediately.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      <code>
        () => DataT
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Factory for default value of <code>
        data
      </code>
      
       before async resolves.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      A number in milliseconds to wait before timing out the request (defaults to <code>
        undefined
      </code>
      
      , which means no timeout)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transform
      </code>
    </td>
    
    <td>
      <code>
        (input: DataT) => DataT | Promise<DataT>
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Function to transform the result after resolving.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        getCachedData
      </code>
    </td>
    
    <td>
      <code>
        (key, nuxtApp, ctx) => DataT | undefined
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Function to return cached data. See below for default.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pick
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Only pick specified keys from the result.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        watch
      </code>
    </td>
    
    <td>
      <code>
        MultiWatchSources | false
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Array of reactive sources to watch and auto-refresh. <code>
        false
      </code>
      
       disables watching.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        deep
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Return data in a deep ref object.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        dedupe
      </code>
    </td>
    
    <td>
      <code>
        'cancel' | 'defer'
      </code>
    </td>
    
    <td>
      <code>
        'cancel'
      </code>
    </td>
    
    <td>
      Avoid fetching same key more than once at a time.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $fetch
      </code>
    </td>
    
    <td>
      <code>
        typeof globalThis.$fetch
      </code>
    </td>
    
    <td>
      -
    </td>
    
    <td>
      Custom $fetch implementation. See <a href="/docs/4.x/guide/recipes/custom-usefetch">
        Custom useFetch in Nuxt
      </a>
    </td>
  </tr>
</tbody>
</table>

<note>

All fetch options can be given a `computed` or `ref` value. These will be watched and new requests made automatically with any new values if they are updated.

</note>

**getCachedData default:**

```ts
const getDefaultCachedData = (key, nuxtApp, ctx) => nuxtApp.isHydrating
  ? nuxtApp.payload.data[key]
  : nuxtApp.static.data[key]
```

This only caches data when `experimental.payloadExtraction` in `nuxt.config` is enabled.

## Return Values

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        Ref<DataT | undefined>
      </code>
    </td>
    
    <td>
      The result of the asynchronous fetch.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refresh
      </code>
    </td>
    
    <td>
      <code>
        (opts?: AsyncDataExecuteOptions) => Promise<void>
      </code>
    </td>
    
    <td>
      Function to manually refresh the data. By default, Nuxt waits until a <code>
        refresh
      </code>
      
       is finished before it can be executed again.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        execute
      </code>
    </td>
    
    <td>
      <code>
        (opts?: AsyncDataExecuteOptions) => Promise<void>
      </code>
    </td>
    
    <td>
      Alias for <code>
        refresh
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        Ref<ErrorT | undefined>
      </code>
    </td>
    
    <td>
      Error object if the data fetching failed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        Ref<'idle' | 'pending' | 'success' | 'error'>
      </code>
    </td>
    
    <td>
      Status of the data request. See below for possible values.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clear
      </code>
    </td>
    
    <td>
      <code>
        () => void
      </code>
    </td>
    
    <td>
      Resets <code>
        data
      </code>
      
       to <code>
        undefined
      </code>
      
       (or the value of <code>
        options.default()
      </code>
      
       if provided), <code>
        error
      </code>
      
       to <code>
        undefined
      </code>
      
      , set <code>
        status
      </code>
      
       to <code>
        idle
      </code>
      
      , and cancels any pending requests.
    </td>
  </tr>
</tbody>
</table>

### Status values

- `idle`: Request has not started (e.g. `{ immediate: false }` or `{ server: false }` on server render)
- `pending`: Request is in progress
- `success`: Request completed successfully
- `error`: Request failed

<note>

If you have not fetched data on the server (for example, with `server: false`), then the data *will not* be fetched until hydration completes. This means even if you await `useFetch` on client-side, `data` will remain null within `<script setup>`.

</note>

### Examples

<link-example to="/docs/4.x/examples/advanced/use-custom-fetch-composable">



</link-example>

<link-example to="/docs/4.x/examples/features/data-fetching">



</link-example>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-head-safe.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-head-safe.md

# useHeadSafe

> The recommended way to provide head data with user input.

## Usage

The `useHeadSafe` composable is a wrapper around the [`useHead`](/docs/4.x/api/composables/use-head) composable that restricts the input to only allow safe values. This is the recommended way to manage head data when working with user input, as it prevents XSS attacks by sanitizing potentially dangerous attributes.

<warning>

When using `useHeadSafe`, potentially dangerous attributes like `innerHTML` in scripts or `http-equiv` in meta tags are automatically stripped out to prevent XSS attacks. Use this composable whenever you're working with user-generated content.

</warning>

## Type

```ts [Signature]
export function useHeadSafe (input: MaybeComputedRef<HeadSafe>): void
```

### Allowed Attributes

The following attributes are whitelisted for each head element type:

```ts
const WhitelistAttributes = {
  htmlAttrs: ['class', 'style', 'lang', 'dir'],
  bodyAttrs: ['class', 'style'],
  meta: ['name', 'property', 'charset', 'content', 'media'],
  noscript: ['textContent'],
  style: ['media', 'textContent', 'nonce', 'title', 'blocking'],
  script: ['type', 'textContent', 'nonce', 'blocking'],
  link: ['color', 'crossorigin', 'fetchpriority', 'href', 'hreflang', 'imagesrcset', 'imagesizes', 'integrity', 'media', 'referrerpolicy', 'rel', 'sizes', 'type'],
}
```

See [@unhead/vue](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/safeSchema.ts) for more detailed types.

## Parameters

`input`: A `MaybeComputedRef<HeadSafe>` object containing head data. You can pass all the same values as [`useHead`](/docs/4.x/api/composables/use-head), but only safe attributes will be rendered.

## Return Values

This composable does not return any value.

## Example

```vue [app/pages/user-profile.vue]
<script setup lang="ts">
// User-generated content that might contain malicious code
const userBio = ref('<script>alert("xss")<' + '/script>')

useHeadSafe({
  title: `User Profile`,
  meta: [
    {
      name: 'description',
      content: userBio.value, // Safely sanitized
    },
  ],
})
</script>
```

<read-more target="_blank" to="https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe">

Read more on the `Unhead` documentation.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-head.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-head.md

# useHead

> useHead customizes the head properties of individual pages of your Nuxt app.

## Usage

The `useHead` composable allows you to manage your head tags in a programmatic and reactive way, powered by [Unhead](https://unhead.unjs.io). It lets you customize the meta tags, links, scripts, and other elements in the `<head>` section of your HTML document.

```vue [app/app.vue]
<script setup lang="ts">
useHead({
  title: 'My App',
  meta: [
    { name: 'description', content: 'My amazing site.' },
  ],
  bodyAttrs: {
    class: 'test',
  },
  script: [{ innerHTML: 'console.log(\'Hello world\')' }],
})
</script>
```

<warning>

If the data comes from a user or other untrusted source, we recommend you check out [`useHeadSafe`](/docs/4.x/api/composables/use-head-safe).

</warning>

<note>

The properties of `useHead` can be dynamic, accepting `ref`, `computed` and `reactive` properties. The `meta` parameter can also accept a function returning an object to make the entire object reactive.

</note>

## Type

```ts [Signature]
export function useHead (meta: MaybeComputedRef<MetaObject>): ActiveHeadEntry<UseHeadInput>

interface MetaObject {
  title?: string
  titleTemplate?: string | ((title?: string) => string)
  base?: Base
  link?: Link[]
  meta?: Meta[]
  style?: Style[]
  script?: Script[]
  noscript?: Noscript[]
  htmlAttrs?: HtmlAttributes
  bodyAttrs?: BodyAttributes
}

interface ActiveHeadEntry<Input> {
  /**
   * Updates the entry with new input.
   *
   * Will first clear any side effects for previous input.
   */
  patch: (input: Input) => void
  /**
   * Dispose the entry, removing it from the active head.
   *
   * Will queue side effects for removal.
   */
  dispose: () => void
}
```

See [@unhead/schema](https://github.com/unjs/unhead/blob/main/packages/vue/src/types/schema.ts) for more detailed types.

## Parameters

`meta`: An object accepting head metadata properties to customize the page's `<head>` section. All properties support reactive values (`ref`, `computed`, `reactive`) or can be a function returning the metadata object.

<table>
<thead>
  <tr>
    <th>
      Property
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        title
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Sets the page title.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titleTemplate
      </code>
    </td>
    
    <td>
      <code>
        string | ((title?: string) => string)
      </code>
    </td>
    
    <td>
      Configures a dynamic template to customize the page title. Can be a string with <code>
        %s
      </code>
      
       placeholder or a function.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base
      </code>
    </td>
    
    <td>
      <code>
        Base
      </code>
    </td>
    
    <td>
      Sets the <code>
        <base>
      </code>
      
       tag for the document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        link
      </code>
    </td>
    
    <td>
      <code>
        Link[]
      </code>
    </td>
    
    <td>
      Array of link objects. Each element is mapped to a <code>
        <link>
      </code>
      
       tag, where object properties correspond to HTML attributes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meta
      </code>
    </td>
    
    <td>
      <code>
        Meta[]
      </code>
    </td>
    
    <td>
      Array of meta objects. Each element is mapped to a <code>
        <meta>
      </code>
      
       tag, where object properties correspond to HTML attributes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        style
      </code>
    </td>
    
    <td>
      <code>
        Style[]
      </code>
    </td>
    
    <td>
      Array of style objects. Each element is mapped to a <code>
        <style>
      </code>
      
       tag, where object properties correspond to HTML attributes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        script
      </code>
    </td>
    
    <td>
      <code>
        Script[]
      </code>
    </td>
    
    <td>
      Array of script objects. Each element is mapped to a <code>
        <script>
      </code>
      
       tag, where object properties correspond to HTML attributes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        noscript
      </code>
    </td>
    
    <td>
      <code>
        Noscript[]
      </code>
    </td>
    
    <td>
      Array of noscript objects. Each element is mapped to a <code>
        <noscript>
      </code>
      
       tag, where object properties correspond to HTML attributes.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        htmlAttrs
      </code>
    </td>
    
    <td>
      <code>
        HtmlAttributes
      </code>
    </td>
    
    <td>
      Sets attributes of the <code>
        <html>
      </code>
      
       tag. Each object property is mapped to the corresponding attribute.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bodyAttrs
      </code>
    </td>
    
    <td>
      <code>
        BodyAttributes
      </code>
    </td>
    
    <td>
      Sets attributes of the <code>
        <body>
      </code>
      
       tag. Each object property is mapped to the corresponding attribute.
    </td>
  </tr>
</tbody>
</table>

## Return Values

This composable does not return any value. It registers the head metadata with Unhead, which manages the actual DOM updates.

## Examples

### Basic Meta Tags

```vue [app/pages/about.vue]
<script setup lang="ts">
useHead({
  title: 'About Us',
  meta: [
    { name: 'description', content: 'Learn more about our company' },
    { property: 'og:title', content: 'About Us' },
    { property: 'og:description', content: 'Learn more about our company' },
  ],
})
</script>
```

### Reactive Meta Tags

```vue [app/pages/profile.vue]
<script setup lang="ts">
const profile = ref({ name: 'John Doe' })

useHead({
  title: computed(() => profile.value.name),
  meta: [
    {
      name: 'description',
      content: computed(() => `Profile page for ${profile.value.name}`),
    },
  ],
})
</script>
```

### Using a Function for Full Reactivity

```vue [app/pages/dynamic.vue]
<script setup lang="ts">
const count = ref(0)

useHead(() => ({
  title: `Count: ${count.value}`,
  meta: [
    { name: 'description', content: `Current count is ${count.value}` },
  ],
}))
</script>
```

### Adding External Scripts and Styles

```vue [app/pages/external.vue]
<script setup lang="ts">
useHead({
  link: [
    {
      rel: 'stylesheet',
      href: 'https://cdn.example.com/styles.css',
    },
  ],
  script: [
    {
      src: 'https://cdn.example.com/script.js',
      async: true,
    },
  ],
})
</script>
```

### Body and HTML Attributes

```vue [app/pages/themed.vue]
<script setup lang="ts">
const isDark = ref(true)

useHead({
  htmlAttrs: {
    lang: 'en',
    class: computed(() => isDark.value ? 'dark' : 'light'),
  },
  bodyAttrs: {
    class: 'themed-page',
  },
})
</script>
```

<read-more to="/docs/4.x/getting-started/seo-meta">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-hydration.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-hydration.md

# useHydration

> Allows full control of the hydration cycle to set and receive data from the server.

`useHydration` is a built-in composable that provides a way to set data on the server side every time a new HTTP request is made and receive that data on the client side. This way `useHydration` allows you to take full control of the hydration cycle.

<note>

This is an advanced composable, primarily designed for use within plugins, mostly used by Nuxt modules.

</note>

<note>

`useHydration` is designed to **ensure state synchronization and restoration during SSR**. If you need to create a globally reactive state that is SSR-friendly in Nuxt, [`useState`](/docs/4.x/api/composables/use-state) is the recommended choice.

</note>

## Usage

The data returned from the `get` function on the server is stored in `nuxtApp.payload` under the unique key provided as the first parameter to `useHydration`. During hydration, this data is then retrieved on the client, preventing redundant computations or API calls.

<code-group>

```ts [With useHydration]
export default defineNuxtPlugin((nuxtApp) => {
  const myStore = new MyStore()

  useHydration(
    'myStoreState',
    () => myStore.getState(),
    data => myStore.setState(data),
  )
})
```

```ts [Without useHydration]
export default defineNuxtPlugin((nuxtApp) => {
  const myStore = new MyStore()

  if (import.meta.server) {
    nuxt.hooks.hook('app:rendered', () => {
      nuxtApp.payload.myStoreState = myStore.getState()
    })
  }

  if (import.meta.client) {
    nuxt.hooks.hook('app:created', () => {
      myStore.setState(nuxtApp.payload.myStoreState)
    })
  }
})
```

</code-group>

## Type

```ts [Signature]
export function useHydration<T> (key: string, get: () => T, set: (value: T) => void): void
```

## Parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      A unique key that identifies the data in your Nuxt application.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        get
      </code>
    </td>
    
    <td>
      <code>
        () => T
      </code>
    </td>
    
    <td>
      A function executed <strong>
        only on the server
      </strong>
      
       (called when SSR rendering is done) to set the initial value.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        set
      </code>
    </td>
    
    <td>
      <code>
        (value: T) => void
      </code>
    </td>
    
    <td>
      A function executed <strong>
        only on the client
      </strong>
      
       (called when initial Vue instance is created) to receive the data.
    </td>
  </tr>
</tbody>
</table>

## Return Values

This composable does not return any value.

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-lazy-async-data.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-lazy-async-data.md

# useLazyAsyncData

> This wrapper around useAsyncData triggers navigation immediately.

`useLazyAsyncData` provides a wrapper around [`useAsyncData`](/docs/4.x/api/composables/use-async-data) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.

<note>

By default, [`useAsyncData`](/docs/4.x/api/composables/use-async-data) blocks navigation until its async handler is resolved. `useLazyAsyncData` allows navigation to occur immediately while data fetching continues in the background.

</note>

## Usage

```vue [app/pages/index.vue]
<script setup lang="ts">
const { status, data: posts } = await useLazyAsyncData('posts', () => $fetch('/api/posts'))
</script>

<template>
  <div>
    <div v-if="status === 'pending'">
      Loading...
    </div>
    <div v-else-if="status === 'error'">
      Error loading posts
    </div>
    <div v-else>
      {{ posts }}
    </div>
  </div>
</template>
```

When using `useLazyAsyncData`, navigation will occur before fetching is complete. This means you must handle `pending` and `error` states directly within your component's template.

<warning>

`useLazyAsyncData` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyAsyncData`.

</warning>

## Type

```ts [Signature]
export function useLazyAsyncData<DataT, ErrorT> (
  handler: (ctx?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>,
): AsyncData<DataT, ErrorT>

export function useLazyAsyncData<DataT, ErrorT> (
  key: string,
  handler: (ctx?: NuxtApp) => Promise<DataT>,
  options?: AsyncDataOptions<DataT>,
): AsyncData<DataT, ErrorT>
```

`useLazyAsyncData` has the same signature as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).

## Parameters

`useLazyAsyncData` accepts the same parameters as [`useAsyncData`](/docs/4.x/api/composables/use-async-data), with the `lazy` option automatically set to `true`.

<read-more to="/docs/4.x/api/composables/use-async-data#parameters">



</read-more>

## Return Values

`useLazyAsyncData` returns the same values as [`useAsyncData`](/docs/4.x/api/composables/use-async-data).

<read-more to="/docs/4.x/api/composables/use-async-data#return-values">



</read-more>

## Example

```vue [app/pages/index.vue]
<script setup lang="ts">
/* Navigation will occur before fetching is complete.
  Handle 'pending' and 'error' states directly within your component's template
*/
const { status, data: count } = await useLazyAsyncData('count', () => $fetch('/api/count'))

watch(count, (newCount) => {
  // Because count might start out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>

<template>
  <div>
    {{ status === 'pending' ? 'Loading' : count }}
  </div>
</template>
```

<read-more to="/docs/4.x/getting-started/data-fetching">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-lazy-fetch.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-lazy-fetch.md

# useLazyFetch

> This wrapper around useFetch triggers navigation immediately.

`useLazyFetch` provides a wrapper around [`useFetch`](/docs/4.x/api/composables/use-fetch) that triggers navigation before the handler is resolved by setting the `lazy` option to `true`.

## Usage

By default, [`useFetch`](/docs/4.x/api/composables/use-fetch) blocks navigation until its async handler is resolved. `useLazyFetch` allows navigation to proceed immediately, with data being fetched in the background.

```vue [app/pages/index.vue]
<script setup lang="ts">
const { status, data: posts } = await useLazyFetch('/api/posts')
</script>

<template>
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>
```

<note>

`useLazyFetch` has the same signature as [`useFetch`](/docs/4.x/api/composables/use-fetch).

</note>

<warning>

Awaiting `useLazyFetch` only ensures the call is initialized. On client-side navigation, data may not be immediately available, and you must handle the `pending` state in your component's template.

</warning>

<warning>

`useLazyFetch` is a reserved function name transformed by the compiler, so you should not name your own function `useLazyFetch`.

</warning>

## Type

```ts [Signature]
export function useLazyFetch<DataT, ErrorT> (
  url: string | Request | Ref<string | Request> | (() => string | Request),
  options?: UseFetchOptions<DataT>,
): Promise<AsyncData<DataT, ErrorT>>
```

<note>

`useLazyFetch` is equivalent to `useFetch` with `lazy: true` option set. See [`useFetch`](/docs/4.x/api/composables/use-fetch) for full type definitions.

</note>

## Parameters

`useLazyFetch` accepts the same parameters as [`useFetch`](/docs/4.x/api/composables/use-fetch):

- `URL` (`string | Request | Ref<string | Request> | () => string | Request`): The URL or request to fetch.
- `options` (object): Same as [`useFetch` options](/docs/4.x/api/composables/use-fetch#parameters), with `lazy` automatically set to `true`.

<read-more to="/docs/4.x/api/composables/use-fetch#parameters">



</read-more>

## Return Values

Returns the same `AsyncData` object as [`useFetch`](/docs/4.x/api/composables/use-fetch):

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        data
      </code>
    </td>
    
    <td>
      <code>
        Ref<DataT | undefined>
      </code>
    </td>
    
    <td>
      The result of the asynchronous fetch.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refresh
      </code>
    </td>
    
    <td>
      <code>
        (opts?: AsyncDataExecuteOptions) => Promise<void>
      </code>
    </td>
    
    <td>
      Function to manually refresh the data.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        execute
      </code>
    </td>
    
    <td>
      <code>
        (opts?: AsyncDataExecuteOptions) => Promise<void>
      </code>
    </td>
    
    <td>
      Alias for <code>
        refresh
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error
      </code>
    </td>
    
    <td>
      <code>
        Ref<ErrorT | undefined>
      </code>
    </td>
    
    <td>
      Error object if the data fetching failed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        Ref<'idle' | 'pending' | 'success' | 'error'>
      </code>
    </td>
    
    <td>
      Status of the data request.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        clear
      </code>
    </td>
    
    <td>
      <code>
        () => void
      </code>
    </td>
    
    <td>
      Resets <code>
        data
      </code>
      
       to <code>
        undefined
      </code>
      
      , <code>
        error
      </code>
      
       to <code>
        undefined
      </code>
      
      , sets <code>
        status
      </code>
      
       to <code>
        idle
      </code>
      
      , and cancels any pending requests.
    </td>
  </tr>
</tbody>
</table>

<read-more to="/docs/4.x/api/composables/use-fetch#return-values">



</read-more>

## Examples

### Handling Pending State

```vue [app/pages/index.vue]
<script setup lang="ts">
/* Navigation will occur before fetching is complete.
 * Handle 'pending' and 'error' states directly within your component's template
 */
const { status, data: posts } = await useLazyFetch('/api/posts')
watch(posts, (newPosts) => {
  // Because posts might start out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>

<template>
  <div v-if="status === 'pending'">
    Loading ...
  </div>
  <div v-else>
    <div v-for="post in posts">
      <!-- do something -->
    </div>
  </div>
</template>
```

<read-more to="/docs/4.x/getting-started/data-fetching">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-loading-indicator.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-loading-indicator.md

# useLoadingIndicator

> This composable gives you access to the loading state of the app page.

## Description

A composable which returns the loading state of the page. Used by [`<NuxtLoadingIndicator>`](/docs/4.x/api/components/nuxt-loading-indicator) and controllable.
It hooks into [`page:loading:start`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) and [`page:loading:end`](/docs/4.x/api/advanced/hooks#app-hooks-runtime) to change its state.

## Parameters

- `duration`: Duration of the loading bar, in milliseconds (default `2000`).
- `throttle`: Throttle the appearing and hiding, in milliseconds (default `200`).
- `estimatedProgress`: By default Nuxt will back off as it approaches 100%. You can provide a custom function to customize the progress estimation, which is a function that receives the duration of the loading bar (above) and the elapsed time. It should return a value between 0 and 100.

## Properties

### `isLoading`

- **type**: `Ref<boolean>`
- **description**: The loading state

### `error`

- **type**: `Ref<boolean>`
- **description**: The error state

### `progress`

- **type**: `Ref<number>`
- **description**: The progress state. From `0` to `100`.

## Methods

### `start()`

Set `isLoading` to true and start to increase the `progress` value. `start` accepts a `{ force: true }` option to skip the interval and show the loading state immediately.

### `set()`

Set the `progress` value to a specific value. `set` accepts a `{ force: true }` option to skip the interval and show the loading state immediately.

### `finish()`

Set the `progress` value to `100`, stop all timers and intervals then reset the loading state `500` ms later. `finish` accepts a `{ force: true }` option to skip the interval before the state is reset, and `{ error: true }` to change the loading bar color and set the error property to true.

### `clear()`

Used by `finish()`. Clear all timers and intervals used by the composable.

## Example

```vue
<script setup lang="ts">
const { progress, isLoading, start, finish, clear } = useLoadingIndicator({
  duration: 2000,
  throttle: 200,
  // This is how progress is calculated by default
  estimatedProgress: (duration, elapsed) => (2 / Math.PI * 100) * Math.atan(elapsed / duration * 100 / 50),
})
</script>
```

```vue
<script setup lang="ts">
const { start, set } = useLoadingIndicator()
// same as set(0, { force: true })
// set the progress to 0, and show loading immediately
start({ force: true })
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-nuxt-app.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-nuxt-app.md

# useNuxtApp

> Access the shared runtime context of the Nuxt Application.

`useNuxtApp` is a built-in composable that provides a way to access shared runtime context of Nuxt, also known as the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context), which is available on both client and server side (but not within Nitro routes). It helps you access the Vue app instance, runtime hooks, runtime config variables and internal states, such as `ssrContext` and `payload`.

```vue [app/app.vue]
<script setup lang="ts">
const nuxtApp = useNuxtApp()
</script>
```

If runtime context is unavailable in your scope, `useNuxtApp` will throw an exception when called. You can use [`tryUseNuxtApp`](/docs/4.x/api/composables/use-nuxt-app#tryusenuxtapp) instead for composables that do not require `nuxtApp`, or to simply check if context is available or not without an exception.

## Methods

### `provide (name, value)`

`nuxtApp` is a runtime context that you can extend using [Nuxt plugins](/docs/4.x/directory-structure/app/plugins). Use the `provide` function to create Nuxt plugins to make values and helper methods available in your Nuxt application across all composables and components.

`provide` function accepts `name` and `value` parameters.

```ts
const nuxtApp = useNuxtApp()
nuxtApp.provide('hello', name => `Hello ${name}!`)

// Prints "Hello name!"
console.log(nuxtApp.$hello('name'))
```

As you can see in the example above, `$hello` has become the new and custom part of `nuxtApp` context and it is available in all places where `nuxtApp` is accessible.

### `hook(name, cb)`

Hooks available in `nuxtApp` allows you to customize the runtime aspects of your Nuxt application. You can use runtime hooks in Vue.js composables and [Nuxt plugins](/docs/4.x/directory-structure/app/plugins) to hook into the rendering lifecycle.

`hook` function is useful for adding custom logic by hooking into the rendering lifecycle at a specific point. `hook` function is mostly used when creating Nuxt plugins.

See [Runtime Hooks](/docs/4.x/api/advanced/hooks#app-hooks-runtime) for available runtime hooks called by Nuxt.

```ts [app/plugins/test.ts]
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:start', () => {
    /* your code goes here */
  })
  nuxtApp.hook('vue:error', (..._args) => {
    console.log('vue:error')
    // if (import.meta.client) {
    //   console.log(..._args)
    // }
  })
})
```

### `callHook(name, ...args)`

`callHook` returns a promise when called with any of the existing hooks.

```ts
await nuxtApp.callHook('my-plugin:init')
```

## Properties

`useNuxtApp()` exposes the following properties that you can use to extend and customize your app and share state, data and variables.

### `vueApp`

`vueApp` is the global Vue.js [application instance](https://vuejs.org/api/application#application-api) that you can access through `nuxtApp`.

Some useful methods:

- [`component()`](https://vuejs.org/api/application#app-component) - Registers a global component if passing both a name string and a component definition, or retrieves an already registered one if only the name is passed.
- [`directive()`](https://vuejs.org/api/application#app-directive) - Registers a global custom directive if passing both a name string and a directive definition, or retrieves an already registered one if only the name is passed[(example)](/docs/4.x/directory-structure/app/plugins#vue-directives).
- [`use()`](https://vuejs.org/api/application#app-use) - Installs a **Vue.js Plugin** [(example)](/docs/4.x/directory-structure/app/plugins#vue-plugins).

<read-more to="https://vuejs.org/api/application.html#application-api" icon="i-simple-icons-vuedotjs">



</read-more>

### `ssrContext`

`ssrContext` is generated during server-side rendering and it is only available on the server side.

Nuxt exposes the following properties through `ssrContext`:

- `url` (string) -  Current request url.
- `event` ([h3js/h3](https://github.com/h3js/h3) request event) - Access the request & response of the current route.
- `payload` (object) - NuxtApp payload object.

### `payload`

`payload` exposes data and state variables from server side to client side. The following keys will be available on the client after they have been passed from the server side:

- `serverRendered` (boolean) - Indicates if response is server-side-rendered.
- `data` (object) - When you fetch the data from an API endpoint using either [`useFetch`](/docs/4.x/api/composables/use-fetch) or [`useAsyncData`](/docs/4.x/api/composables/use-async-data) , resulting payload can be accessed from the `payload.data`. This data is cached and helps you prevent fetching the same data in case an identical request is made more than once.<code-group>

```vue [app/app.vue]
<script setup lang="ts">
const { data } = await useAsyncData('count', (_nuxtApp, { signal }) => $fetch('/api/count', { signal }))
</script>
```

```ts [server/api/count.ts]
export default defineEventHandler((event) => {
  return { count: 1 }
})
```

</code-group>

<br />

After fetching the value of `count` using [`useAsyncData`](/docs/4.x/api/composables/use-async-data) in the example above, if you access `payload.data`, you will see `{ count: 1 }` recorded there.<br />

When accessing the same `payload.data` from [`ssrcontext`](/docs/4.x/api/composables/use-nuxt-app#ssrcontext), you can access the same value on the server side as well.
- `state` (object) - When you use [`useState`](/docs/4.x/api/composables/use-state) composable in Nuxt to set shared state, this state data is accessed through `payload.state.[name-of-your-state]`.```ts [app/plugins/my-plugin.ts]
export const useColor = () => useState<string>('color', () => 'pink')

export default defineNuxtPlugin((nuxtApp) => {
  if (import.meta.server) {
    const color = useColor()
  }
})
```

<br />

It is also possible to use more advanced types, such as `ref`, `reactive`, `shallowRef`, `shallowReactive` and `NuxtError`.

#### Custom Reducer/Reviver

Since [Nuxt v3.4](https://nuxt.com/blog/v3-4#payload-enhancements), it is possible to define your own reducer/reviver for types that are not supported by Nuxt.

<video-accordion title="Watch a video from Alexander Lichter about serializing payloads, especially with regards to classes" video-id="8w6ffRBs8a4">



</video-accordion>

In the example below, we define a reducer (or a serializer) and a reviver (or deserializer) for the [Luxon](https://moment.github.io/luxon/#/) DateTime class, using a payload plugin.

```ts [app/plugins/date-time-payload.ts]
/**
 * This kind of plugin runs very early in the Nuxt lifecycle, before we revive the payload.
 * You will not have access to the router or other Nuxt-injected properties.
 *
 * Note that the "DateTime" string is the type identifier and must
 * be the same on both the reducer and the reviver.
 */
export default definePayloadPlugin((nuxtApp) => {
  definePayloadReducer('DateTime', (value) => {
    return value instanceof DateTime && value.toJSON()
  })
  definePayloadReviver('DateTime', (value) => {
    return DateTime.fromISO(value)
  })
})
```

### `isHydrating`

Use `nuxtApp.isHydrating` (boolean) to check if the Nuxt app is hydrating on the client side.

```ts [app/components/nuxt-error-boundary.ts]
export default defineComponent({
  setup (_props, { slots, emit }) {
    const nuxtApp = useNuxtApp()
    onErrorCaptured((err) => {
      if (import.meta.client && !nuxtApp.isHydrating) {
        // ...
      }
    })
  },
})
```

### `runWithContext`

<note>

You are likely here because you got a "Nuxt instance unavailable" message. Please use this method sparingly, and report examples that are causing issues, so that it can ultimately be solved at the framework level.

</note>

The `runWithContext` method is meant to be used to call a function and give it an explicit Nuxt context. Typically, the Nuxt context is passed around implicitly and you do not need to worry about this. However, when working with complex `async`/`await` scenarios in middleware/plugins, you can run into instances where the current instance has been unset after an async call.

```ts [app/middleware/auth.ts]
export default defineNuxtRouteMiddleware(async (to, from) => {
  const nuxtApp = useNuxtApp()
  let user
  try {
    user = await fetchUser()
    // the Vue/Nuxt compiler loses context here because of the try/catch block.
  } catch (e) {
    user = null
  }
  if (!user) {
    // apply the correct Nuxt context to our `navigateTo` call.
    return nuxtApp.runWithContext(() => navigateTo('/auth'))
  }
})
```

#### Usage

```ts
const result = nuxtApp.runWithContext(() => functionWithContext())
```

- `functionWithContext`: Any function that requires the context of the current Nuxt application. This context will be correctly applied automatically.

`runWithContext` will return whatever is returned by `functionWithContext`.

#### A Deeper Explanation of Context

Vue.js Composition API (and Nuxt composables similarly) work by depending on an implicit context. During the lifecycle, Vue sets the temporary instance of the current component (and Nuxt temporary instance of nuxtApp) to a global variable and unsets it in same tick. When rendering on the server side, there are multiple requests from different users and nuxtApp running in a same global context. Because of this, Nuxt and Vue immediately unset this global instance to avoid leaking a shared reference between two users or components.

What it does mean? The Composition API and Nuxt Composables are only available during lifecycle and in same tick before any async operation:

```ts
// --- Vue internal ---
const _vueInstance = null
const getCurrentInstance = () => _vueInstance
// ---

// Vue / Nuxt sets a global variable referencing to current component in _vueInstance when calling setup()
async function setup () {
  getCurrentInstance() // Works
  await someAsyncOperation() // Vue unsets the context in same tick before async operation!
  getCurrentInstance() // null
}
```

The classic solution to this, is caching the current instance on first call to a local variable like `const instance = getCurrentInstance()` and use it in the next composable call but the issue is that any nested composable calls now needs to explicitly accept the instance as an argument and not depend on the implicit context of composition-api. This is design limitation with composables and not an issue per-se.

To overcome this limitation, Vue does some behind the scenes work when compiling our application code and restores context after each call for `<script setup>`:

```ts
const __instance = getCurrentInstance() // Generated by Vue compiler
getCurrentInstance() // Works!
await someAsyncOperation() // Vue unsets the context
__restoreInstance(__instance) // Generated by Vue compiler
getCurrentInstance() // Still works!
```

For a better description of what Vue actually does, see [unjs/unctx#2 (comment)](https://github.com/unjs/unctx/issues/2#issuecomment-942193723).

#### Solution

This is where `runWithContext` can be used to restore context, similarly to how `<script setup>` works.

Nuxt internally uses [unjs/unctx](https://github.com/unjs/unctx) to support composables similar to Vue for plugins and middleware. This enables composables like `navigateTo()` to work without directly passing `nuxtApp` to them - bringing the DX and performance benefits of Composition API to the whole Nuxt framework.

Nuxt composables have the same design as the Vue Composition API and therefore need a similar solution to magically do this transform. Check out [unjs/unctx#2](https://github.com/unjs/unctx/issues/2) (proposal), [unjs/unctx#4](https://github.com/unjs/unctx/pull/4) (transform implementation), and [nuxt/framework#3884](https://github.com/nuxt/framework/pull/3884) (Integration to Nuxt).

Vue currently only supports async context restoration for `<script setup>` for async/await usage. In Nuxt, the transform support for `defineNuxtPlugin()` and `defineNuxtRouteMiddleware()` was added, which means when you use them Nuxt automatically transforms them with context restoration.

#### Remaining Issues

The `unjs/unctx` transformation to automatically restore context seems buggy with `try/catch` statements containing `await` which ultimately needs to be solved in order to remove the requirement of the workaround suggested above.

#### Native Async Context

Using a new experimental feature, it is possible to enable native async context support using [Node.js `AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) and new unctx support to make async context available **natively** to **any nested async composable** without needing a transform or manual passing/calling with context.

<tip>

Native async context support works currently in Bun and Node.

</tip>

<read-more to="/docs/4.x/guide/going-further/experimental-features#asynccontext">



</read-more>

## tryUseNuxtApp

This function works exactly the same as `useNuxtApp`, but returns `null` if context is unavailable instead of throwing an exception.

You can use it for composables that do not require `nuxtApp`, or to simply check if context is available or not without an exception.

Example usage:

```ts [composable.ts]
export function useStandType () {
  // Always works on the client
  if (tryUseNuxtApp()) {
    return useRuntimeConfig().public.STAND_TYPE
  } else {
    return process.env.STAND_TYPE
  }
}
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-nuxt-data.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-nuxt-data.md

# useNuxtData

> Access the current cached value of data fetching composables.

<note>

`useNuxtData` gives you access to the current cached value of [`useAsyncData`](/docs/4.x/api/composables/use-async-data) , [`useLazyAsyncData`](/docs/4.x/api/composables/use-lazy-async-data), [`useFetch`](/docs/4.x/api/composables/use-fetch) and [`useLazyFetch`](/docs/4.x/api/composables/use-lazy-fetch) with explicitly provided key.

</note>

## Usage

The `useNuxtData` composable is used to access the current cached value of data-fetching composables such as `useAsyncData`, `useLazyAsyncData`, `useFetch`, and `useLazyFetch`. By providing the key used during the data fetch, you can retrieve the cached data and use it as needed.

This is particularly useful for optimizing performance by reusing already-fetched data or implementing features like Optimistic Updates or cascading data updates.

To use `useNuxtData`, ensure that the data-fetching composable (`useFetch`, `useAsyncData`, etc.) has been called with an explicitly provided key.

<video-accordion title="Watch a video from LearnVue about useNuxtData" video-id="e-_u6swXRWk">



</video-accordion>

## Params

- `key`: The unique key that identifies the cached data. This key should match the one used during the original data fetch.

## Return Values

- `data`: A reactive reference to the cached data associated with the provided key. If no cached data exists, the value will be `null`. This `Ref` automatically updates if the cached data changes, allowing seamless reactivity in your components.

## Example

The example below shows how you can use cached data as a placeholder while the most recent data is being fetched from the server.

```vue [app/pages/posts.vue]
<script setup lang="ts">
// We can access same data later using 'posts' key
const { data } = await useFetch('/api/posts', { key: 'posts' })
</script>
```

```vue [app/pages/posts/[id].vue]
<script setup lang="ts">
// Access to the cached value of useFetch in posts.vue (parent route)
const { data: posts } = useNuxtData('posts')

const route = useRoute()

const { data } = useLazyFetch(`/api/posts/${route.params.id}`, {
  key: `post-${route.params.id}`,
  default () {
    // Find the individual post from the cache and set it as the default value.
    return posts.value.find(post => post.id === route.params.id)
  },
})
</script>
```

## Optimistic Updates

The example below shows how implementing Optimistic Updates can be achieved using useNuxtData.

Optimistic Updates is a technique where the user interface is updated immediately, assuming a server operation will succeed. If the operation eventually fails, the UI is rolled back to its previous state.

```vue [app/pages/todos.vue]
<script setup lang="ts">
// We can access same data later using 'todos' key
const { data } = await useAsyncData('todos', (_nuxtApp, { signal }) => $fetch('/api/todos', { signal }))
</script>
```

```vue [app/components/NewTodo.vue]
<script setup lang="ts">
const newTodo = ref('')
let previousTodos = []

// Access to the cached value of useAsyncData in todos.vue
const { data: todos } = useNuxtData('todos')

async function addTodo () {
  await $fetch('/api/addTodo', {
    method: 'post',
    body: {
      todo: newTodo.value,
    },
    onRequest () {
      // Store the previously cached value to restore if fetch fails.
      previousTodos = todos.value

      // Optimistically update the todos.
      todos.value = [...todos.value, newTodo.value]
    },
    onResponseError () {
      // Rollback the data if the request failed.
      todos.value = previousTodos
    },
    async onResponse () {
      // Invalidate todos in the background if the request succeeded.
      await refreshNuxtData('todos')
    },
  })
}
</script>
```

## Type

```ts [Signature]
export function useNuxtData<DataT = any> (key: string): { data: Ref<DataT | undefined> }
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-preview-mode.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-preview-mode.md

# `usePreviewMode`

Preview mode allows you to see how your changes would be displayed on a live site without revealing them to users.

You can use the built-in `usePreviewMode` composable to access and control preview state in Nuxt. If the composable detects preview mode it will automatically force any updates necessary for [`useAsyncData`](/docs/4.x/api/composables/use-async-data) and [`useFetch`](/docs/4.x/api/composables/use-fetch) to rerender preview content.

```ts
const { enabled, state } = usePreviewMode()
```

## Options

### Custom `enable` check

You can specify a custom way to enable preview mode. By default the `usePreviewMode` composable will enable preview mode if there is a `preview` param in url that is equal to `true` (for example, `http://localhost:3000?preview=true`). You can wrap the `usePreviewMode` into custom composable, to keep options consistent across usages and prevent any errors.

```ts
export function useMyPreviewMode () {
  const route = useRoute()
  return usePreviewMode({
    shouldEnable: () => {
      return !!route.query.customPreview
    },
  })
}
```

### Modify default state

`usePreviewMode` will try to store the value of a `token` param from url in state. You can modify this state and it will be available for all [`usePreviewMode`](/docs/4.x/api/composables/use-preview-mode) calls.

```ts
const data1 = ref('data1')

const { enabled, state } = usePreviewMode({
  getState: (currentState) => {
    return { data1, data2: 'data2' }
  },
})
```

<note>

The `getState` function will append returned values to current state, so be careful not to accidentally overwrite important state.

</note>

### Customize the `onEnable` and `onDisable` callbacks

By default, when `usePreviewMode` is enabled, it will call `refreshNuxtData()` to re-fetch all data from the server.

When preview mode is disabled, the composable will attach a callback to call `refreshNuxtData()` to run after a subsequent router navigation.

You can specify custom callbacks to be triggered by providing your own functions for the `onEnable` and `onDisable` options.

```ts
const { enabled, state } = usePreviewMode({
  onEnable: () => {
    console.log('preview mode has been enabled')
  },
  onDisable: () => {
    console.log('preview mode has been disabled')
  },
})
```

## Example

The example below creates a page where part of a content is rendered only in preview mode.

```vue [app/pages/some-page.vue]
<script setup>
const { enabled, state } = usePreviewMode()

const { data } = await useFetch('/api/preview', {
  query: {
    apiKey: state.token,
  },
})
</script>

<template>
  <div>
    Some base content
    <p v-if="enabled">
      Only preview content: {{ state.token }}
      <br>
      <button @click="enabled = false">
        disable preview mode
      </button>
    </p>
  </div>
</template>
```

Now you can generate your site and serve it:

```bash [Terminal]
npx nuxt generate
npx nuxt preview
```

Then you can see your preview page by adding the query param `preview` to the end of the page you want to see once, for example `http://localhost:3000/?preview=true`.

<note>

`usePreviewMode` should be tested locally with `nuxt generate` and then `nuxt preview` rather than `nuxt dev`. (The [preview command](/docs/4.x/api/commands/preview) is not related to preview mode.)

</note>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-request-event.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-request-event.md

# useRequestEvent

> Access the incoming request event with the useRequestEvent composable.

Within the [Nuxt context](/docs/4.x/guide/going-further/nuxt-app#the-nuxt-context) you can use `useRequestEvent` to access the incoming request.

```ts
// Get underlying request event
const event = useRequestEvent()

// Get the URL
const url = event?.path
```

<tip>

In the browser, `useRequestEvent` will return `undefined`.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-request-fetch.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-request-fetch.md

# useRequestFetch

> Forward the request context and headers for server-side fetch requests with the useRequestFetch composable.

You can use `useRequestFetch` to forward the request context and headers when making server-side fetch requests.

When making a client-side fetch request, the browser automatically sends the necessary headers.
However, when making a request during server-side rendering, due to security considerations, we need to forward the headers manually.

<note>

Headers that are **not meant to be forwarded** will **not be included** in the request. These headers include, for example:
`transfer-encoding`, `connection`, `keep-alive`, `upgrade`, `expect`, `host`, `accept`

</note>

<tip>

The [`useFetch`](/docs/4.x/api/composables/use-fetch) composable uses `useRequestFetch` under the hood to automatically forward the request context and headers.

</tip>

<code-group>

```vue [app/pages/index.vue]
<script setup lang="ts">
// This will forward the user's headers to the `/api/cookies` event handler
// Result: { cookies: { foo: 'bar' } }
const requestFetch = useRequestFetch()
const { data: forwarded } = await useAsyncData(() => requestFetch('/api/cookies'))

// This will NOT forward anything
// Result: { cookies: {} }
const { data: notForwarded } = await useAsyncData((_nuxtApp, { signal }) => $fetch('/api/cookies', { signal }))
</script>
```

```ts [server/api/cookies.ts]
export default defineEventHandler((event) => {
  const cookies = parseCookies(event)

  return { cookies }
})
```

</code-group>

<tip>

In the browser during client-side navigation, `useRequestFetch` will behave just like regular [`$fetch`](/docs/4.x/api/utils/dollarfetch).

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-request-header.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-request-header.md

# useRequestHeader

> Use useRequestHeader to access a certain incoming request header.

You can use the built-in [`useRequestHeader`](/docs/4.x/api/composables/use-request-header) composable to access any incoming request header within your pages, components, and plugins.

```ts
// Get the authorization request header
const authorization = useRequestHeader('authorization')
```

<tip>

In the browser, `useRequestHeader` will return `undefined`.

</tip>

## Example

We can use `useRequestHeader` to easily figure out if a user is authorized or not.

The example below reads the `authorization` request header to find out if a person can access a restricted resource.

```ts [app/middleware/authorized-only.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  if (!useRequestHeader('authorization')) {
    return navigateTo('/not-authorized')
  }
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-request-headers.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-request-headers.md

# useRequestHeaders

> Use useRequestHeaders to access the incoming request headers.

You can use built-in [`useRequestHeaders`](/docs/4.x/api/composables/use-request-headers) composable to access the incoming request headers within your pages, components, and plugins.

```ts
// Get all request headers
const headers = useRequestHeaders()

// Get only cookie request header
const { cookie } = useRequestHeaders(['cookie'])
```

<tip>

In the browser, `useRequestHeaders` will return an empty object.

</tip>

## Example

We can use `useRequestHeaders` to access and proxy the initial request's `authorization` header to any future internal requests during SSR.

The example below adds the `authorization` request header to an isomorphic `$fetch` call.

```vue [app/pages/some-page.vue]
<script setup lang="ts">
const { data } = await useFetch('/api/confidential', {
  headers: useRequestHeaders(['authorization']),
})
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-request-url.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-request-url.md

# useRequestURL

> Access the incoming request URL with the useRequestURL composable.

`useRequestURL` is a helper function that returns an [URL object](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) working on both server-side and client-side.

<important>

When utilizing [Hybrid Rendering](/docs/4.x/guide/concepts/rendering#hybrid-rendering) with cache strategies, all incoming request headers are dropped when handling the cached responses via the [Nitro caching layer](https://nitro.build/guide/cache) (meaning `useRequestURL` will return `localhost` for the `host`).

You can define the [`cache.varies` option](https://nitro.build/guide/cache#options) to specify headers that will be considered when caching and serving the responses, such as `host` and `x-forwarded-host` for multi-tenant environments.

</important>

<code-group>

```vue [app/pages/about.vue]
<script setup lang="ts">
const url = useRequestURL()
</script>

<template>
  <p>URL is: {{ url }}</p>
  <p>Path is: {{ url.pathname }}</p>
</template>
```

```html [Result in development]
<p>URL is: http://localhost:3000/about</p>
<p>Path is: /about</p>
```

</code-group>

<tip icon="i-simple-icons-mdnwebdocs" target="_blank" to="https://developer.mozilla.org/en-US/docs/Web/API/URL#instance_properties">

Read about the URL instance properties on the MDN documentation.

</tip>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-response-header.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-response-header.md

# useResponseHeader

> Use useResponseHeader to set a server response header.

<important>

This composable is available in Nuxt v3.14+.

</important>

You can use the built-in [`useResponseHeader`](/docs/4.x/api/composables/use-response-header) composable to set any server response header within your pages, components, and plugins.

```ts
// Set a custom response header
const header = useResponseHeader('X-My-Header')
header.value = 'my-value'
```

## Example

We can use `useResponseHeader` to easily set a response header on a per-page basis.

```vue [app/pages/test.vue]
<script setup>
// pages/test.vue
const header = useResponseHeader('X-My-Header')
header.value = 'my-value'
</script>

<template>
  <h1>Test page with custom header</h1>
  <p>The response from the server for this "/test" page will have a custom "X-My-Header" header.</p>
</template>
```

We can use `useResponseHeader` for example in Nuxt [middleware](/docs/4.x/directory-structure/app/middleware) to set a response header for all pages.

```ts [app/middleware/my-header-middleware.ts]
export default defineNuxtRouteMiddleware((to, from) => {
  const header = useResponseHeader('X-My-Always-Header')
  header.value = `I'm Always here!`
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-route-announcer.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-route-announcer.md

# useRouteAnnouncer

> This composable observes the page title changes and updates the announcer message accordingly.

<important>

This composable is available in Nuxt v3.12+.

</important>

## Description

A composable which observes the page title changes and updates the announcer message accordingly. Used by [`<NuxtRouteAnnouncer>`](/docs/4.x/api/components/nuxt-route-announcer) and controllable.
It hooks into Unhead's `dom:rendered` hook to read the page's title and set it as the announcer message.

## Parameters

- `politeness`: Sets the urgency for screen reader announcements: `off` (disable the announcement), `polite` (waits for silence), or `assertive` (interrupts immediately).  (default `polite`).

## Properties

### `message`

- **type**: `Ref<string>`
- **description**: The message to announce

### `politeness`

- **type**: `Ref<string>`
- **description**: Screen reader announcement urgency level `off`, `polite`, or `assertive`

## Methods

### `set(message, politeness = "polite")`

Sets the message to announce with its urgency level.

### `polite(message)`

Sets the message with `politeness = "polite"`

### `assertive(message)`

Sets the message with `politeness = "assertive"`

## Example

```vue [app/pages/index.vue]
<script setup lang="ts">
const { message, politeness, set, polite, assertive } = useRouteAnnouncer({
  politeness: 'assertive',
})
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-route.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-route.md

# useRoute

> The useRoute composable returns the current route.

<note>

Within the template of a Vue component, you can access the route using `$route`.

</note>

The `useRoute` composable is a wrapper around the identically named composable from `vue-router`, providing access to the current route in a Nuxt application.

The key difference is that in Nuxt, the composable ensures that the route is updated **only after** the page content has changed after navigation.
In contrast, the `vue-router` version updates the route **immediately**, which can lead to synchronization issues between different parts of the template
that rely on the route metadata, for example.

## Example

In the following example, we call an API via [`useFetch`](/docs/4.x/api/composables/use-fetch) using a dynamic page parameter - `slug` - as part of the URL.

```html [~/pages/[slug].vue]
<script setup lang="ts">
const route = useRoute()
const { data: mountain } = await useFetch(`/api/mountains/${route.params.slug}`)
</script>

<template>
  <div>
    <h1>{{ mountain.title }}</h1>
    <p>{{ mountain.description }}</p>
  </div>
</template>
```

If you need to access the route query parameters (for example `example` in the path `/test?example=true`), then you can use `useRoute().query` instead of `useRoute().params`.

## API

Apart from dynamic parameters and query parameters, `useRoute()` also provides the following computed references related to the current route:

- `fullPath`: encoded URL associated with the current route that contains path, query and hash
- `hash`: decoded hash section of the URL that starts with a #
- `query`: access route query parameters
- `matched`: array of normalized matched routes with current route location
- `meta`: custom data attached to the record
- `name`: unique name for the route record
- `path`: encoded pathname section of the URL
- `redirectedFrom`: route location that was attempted to access before ending up on the current route location

## Common Pitfalls

### Route Synchronization Issues

It’s important to use the `useRoute()` composable from Nuxt rather than the one from `vue-router` to avoid synchronization issues during page navigation.
Importing `useRoute` directly from `vue-router` bypasses Nuxt's implementation.

```tstwoslash
// ❌ do not use `useRoute` from `vue-router`
// @errors: 2300
import { useRoute } from 'vue-router'
// ✅ use Nuxt's `useRoute` composable
import { useRoute } from '#app'
```

### Calling `useRoute` in Middleware

Using `useRoute` in middleware is not recommended because it can lead to unexpected behavior.
There is no concept of a "current route" in middleware.
The `useRoute()` composable should only be used in the setup function of a Vue component or in a Nuxt plugin.

<warning>

This applies to any composable that uses `useRoute()` internally too.

</warning>

<read-more to="/docs/4.x/directory-structure/app/middleware">

Read more about accessing the route in the middleware section.

</read-more>

### Hydration Issues with `route.fullPath`

Browsers don't send [URL fragments](https://url.spec.whatwg.org/#concept-url-fragment) (for example `#foo`) when making requests. So using `route.fullPath` to affect the template can trigger hydration issues because this will include the fragment on client but not the server.

<read-more to="https://router.vuejs.org/api/type-aliases/routelocationnormalizedloaded" icon="i-simple-icons-vuedotjs">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-router.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-router.md

# useRouter

> The useRouter composable returns the router instance.

```vue [app/pages/index.vue]
<script setup lang="ts">
const router = useRouter()
</script>
```

If you only need the router instance within your template, use `$router`:

```vue [app/pages/index.vue]
<template>
  <button @click="$router.back()">
    Back
  </button>
</template>
```

If you have a `app/pages/` directory, `useRouter` is identical in behavior to the one provided by `vue-router`.

<read-more to="https://router.vuejs.org/api/interfaces/router#Properties-currentRoute-" icon="i-simple-icons-vuedotjs" target="_blank">

Read `vue-router` documentation about the `Router` interface.

</read-more>

## Basic Manipulation

- [`addRoute()`](https://router.vuejs.org/api/interfaces/router#addRoute-): Add a new route to the router instance. `parentName` can be provided to add new route as the child of an existing route.
- [`removeRoute()`](https://router.vuejs.org/api/interfaces/router#removeRoute-): Remove an existing route by its name.
- [`getRoutes()`](https://router.vuejs.org/api/interfaces/router#getRoutes-): Get a full list of all the route records.
- [`hasRoute()`](https://router.vuejs.org/api/interfaces/router#hasRoute-): Checks if a route with a given name exists.
- [`resolve()`](https://router.vuejs.org/api/interfaces/router#resolve-): Returns the normalized version of a route location. Also includes an `href` property that includes any existing base.

```ts [Example]
const router = useRouter()

router.addRoute({ name: 'home', path: '/home', component: Home })
router.removeRoute('home')
router.getRoutes()
router.hasRoute('home')
router.resolve({ name: 'home' })
```

<note>

`router.addRoute()` adds route details into an array of routes and it is useful while building [Nuxt plugins](/docs/4.x/directory-structure/app/plugins) while `router.push()` on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.

</note>

## Based on History API

- [`back()`](https://router.vuejs.org/api/interfaces/router#back-): Go back in history if possible, same as `router.go(-1)`.
- [`forward()`](https://router.vuejs.org/api/interfaces/router#forward-): Go forward in history if possible, same as `router.go(1)`.
- [`go()`](https://router.vuejs.org/api/interfaces/router#go-): Move forward or backward through the history without the hierarchical restrictions enforced in `router.back()` and `router.forward()`.
- [`push()`](https://router.vuejs.org/api/interfaces/router#push-): Programmatically navigate to a new URL by pushing an entry in the history stack. **It is recommended to use navigateTo instead.**
- [`replace()`](https://router.vuejs.org/api/interfaces/router#replace-): Programmatically navigate to a new URL by replacing the current entry in the routes history stack. **It is recommended to use navigateTo instead.**

```ts [Example]
const router = useRouter()

router.back()
router.forward()
router.go(3)
router.push({ path: '/home' })
router.replace({ hash: '#bio' })
```

<read-more to="https://developer.mozilla.org/en-US/docs/Web/API/History" icon="i-simple-icons-mdnwebdocs" target="_blank">

Read more about the browser's History API.

</read-more>

## Navigation Guards

`useRouter` composable provides `afterEach`, `beforeEach` and `beforeResolve` helper methods that acts as navigation guards.

However, Nuxt has a concept of **route middleware** that simplifies the implementation of navigation guards and provides a better developer experience.

<read-more to="/docs/4.x/directory-structure/app/middleware">



</read-more>

## Promise and Error Handling

- [`isReady()`](https://router.vuejs.org/api/interfaces/router#isReady-): Returns a Promise that resolves when the router has completed the initial navigation.
- [`onError`](https://router.vuejs.org/api/interfaces/router#onError-): Adds an error handler that is called every time a non caught error happens during navigation.

<read-more to="https://router.vuejs.org/api/interfaces/router#Methods-" icon="i-simple-icons-vuedotjs" target="_blank" title="Vue Router Docs">



</read-more>

## Universal Router Instance

If you do not have a `app/pages/` folder, then [`useRouter`](/docs/4.x/api/composables/use-router)  will return a universal router instance with similar helper methods, but be aware that not all features may be supported or behave in exactly the same way as with `vue-router`.

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-runtime-config.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-runtime-config.md

# useRuntimeConfig

> Access runtime config variables with the useRuntimeConfig composable.

## Usage

```vue [app/app.vue]
<script setup lang="ts">
const config = useRuntimeConfig()
</script>
```

```ts [server/api/foo.ts]
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)
})
```

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

## Define Runtime Config

The example below shows how to set a public API base URL and a secret API token that is only accessible on the server.

We should always define `runtimeConfig` variables inside `nuxt.config`.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  runtimeConfig: {
    // Private keys are only available on the server
    apiSecret: '123',

    // Public keys that are exposed to the client
    public: {
      apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api',
    },
  },
})
```

<note>

Variables that need to be accessible on the server are added directly inside `runtimeConfig`. Variables that need to be accessible on both the client and the server are defined in `runtimeConfig.public`.

</note>

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

## Access Runtime Config

To access runtime config, we can use `useRuntimeConfig()` composable:

```ts [server/api/test.ts]
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)

  // Access public variables
  const result = await $fetch(`/test`, {
    baseURL: config.public.apiBase,
    headers: {
      // Access a private variable (only available on the server)
      Authorization: `Bearer ${config.apiSecret}`,
    },
  })
  return result
})
```

In this example, since `apiBase` is defined within the `public` namespace, it is universally accessible on both server and client-side, while `apiSecret` **is only accessible on the server-side**.

## Environment Variables

It is possible to update runtime config values using a matching environment variable name prefixed with `NUXT_`.

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

### Using the `.env` File

We can set the environment variables inside the `.env` file to make them accessible during **development** and **build/generate**.

```ini [.env]
NUXT_PUBLIC_API_BASE = "https://api.localhost:5555"
NUXT_API_SECRET = "123"
```

<note>

Any environment variables set within `.env` file are accessed using `process.env` in the Nuxt app during **development** and **build/generate**.

</note>

<warning>

In **production runtime**, you should use platform environment variables and `.env` is not used.

</warning>

<read-more to="/docs/4.x/directory-structure/env">



</read-more>

## `app` namespace

Nuxt uses `app` namespace in runtime-config with keys including `baseURL` and `cdnURL`. You can customize their values at runtime by setting environment variables.

<note>

This is a reserved namespace. You should not introduce additional keys inside `app`.

</note>

### `app.baseURL`

By default, the `baseURL` is set to `'/'`.

However, the `baseURL` can be updated at runtime by setting the `NUXT_APP_BASE_URL` as an environment variable.

Then, you can access this new base URL using `config.app.baseURL`:

```ts [/plugins/my-plugin.ts]
export default defineNuxtPlugin((NuxtApp) => {
  const config = useRuntimeConfig()

  // Access baseURL universally
  const baseURL = config.app.baseURL
})
```

### `app.cdnURL`

This example shows how to set a custom CDN url and access them using `useRuntimeConfig()`.

You can use a custom CDN for serving static assets inside `.output/public` using the `NUXT_APP_CDN_URL` environment variable.

And then access the new CDN url using `config.app.cdnURL`.

```ts [server/api/foo.ts]
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)

  // Access cdnURL universally
  const cdnURL = config.app.cdnURL
})
```

<read-more to="/docs/4.x/guide/going-further/runtime-config">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-runtime-hook.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-runtime-hook.md

# useRuntimeHook

> Registers a runtime hook in a Nuxt application and ensures it is properly disposed of when the scope is destroyed.

<important>

This composable is available in Nuxt v3.14+.

</important>

```ts [signature]
function useRuntimeHook<THookName extends keyof RuntimeNuxtHooks> (
  name: THookName,
  fn: RuntimeNuxtHooks[THookName] extends HookCallback ? RuntimeNuxtHooks[THookName] : never,
): void
```

## Usage

### Parameters

- `name`: The name of the runtime hook to register. You can see the full list of [runtime Nuxt hooks here](/docs/4.x/api/advanced/hooks#app-hooks-runtime).
- `fn`: The callback function to execute when the hook is triggered. The function signature varies based on the hook name.

### Returns

The composable doesn't return a value, but it automatically unregisters the hook when the component's scope is destroyed.

## Example

```vue [pages/index.vue]twoslash
<script setup lang="ts">
// Register a hook that runs every time a link is prefetched, but which will be
// automatically cleaned up (and not called again) when the component is unmounted
useRuntimeHook('link:prefetch', (link) => {
  console.log('Prefetching', link)
})
</script>
```

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-seo-meta.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-seo-meta.md

# useSeoMeta

> The useSeoMeta composable lets you define your site's SEO meta tags as a flat object with full TypeScript support.

This helps you avoid common mistakes, such as using `name` instead of `property`, as well as typos - with over 100+ meta tags fully typed.

<important>

This is the recommended way to add meta tags to your site as it is XSS safe and has full TypeScript support.

</important>

<read-more to="/docs/4.x/getting-started/seo-meta">



</read-more>

## Usage

```vue [app/app.vue]
<script setup lang="ts">
useSeoMeta({
  title: 'My Amazing Site',
  ogTitle: 'My Amazing Site',
  description: 'This is my amazing site, let me tell you all about it.',
  ogDescription: 'This is my amazing site, let me tell you all about it.',
  ogImage: 'https://example.com/image.png',
  twitterCard: 'summary_large_image',
})
</script>
```

When inserting tags that are reactive, you should use the computed getter syntax (`() => value`):

```vue [app/app.vue]
<script setup lang="ts">
const title = ref('My title')

useSeoMeta({
  title,
  description: () => `This is a description for the ${title.value} page`,
})
</script>
```

## Parameters

There are over 100 parameters. See the [full list of parameters in the source code](https://github.com/harlan-zw/zhead/blob/main/packages/zhead/src/metaFlat.ts#L1035).

<read-more to="/docs/4.x/getting-started/seo-meta">



</read-more>

## Performance

In most instances, SEO meta tags don't need to be reactive as search engine robots primarily scan the initial page load.

For better performance, you can wrap your `useSeoMeta` calls in a server-only condition when the meta tags don't need to be reactive:

```vue [app/app.vue]
<script setup lang="ts">
if (import.meta.server) {
  // These meta tags will only be added during server-side rendering
  useSeoMeta({
    robots: 'index, follow',
    description: 'Static description that does not need reactivity',
    ogImage: 'https://example.com/image.png',
    // other static meta tags...
  })
}

const dynamicTitle = ref('My title')
// Only use reactive meta tags outside the condition when necessary
useSeoMeta({
  title: () => dynamicTitle.value,
  ogTitle: () => dynamicTitle.value,
})
</script>
```

This previously used the [`useServerSeoMeta`](/docs/4.x/api/composables/use-server-seo-meta) composable, but it has been deprecated in favor of this approach.

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-server-seo-meta.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-server-seo-meta.md

# useServerSeoMeta

> The useServerSeoMeta composable lets you define your site's SEO meta tags as a flat object with full TypeScript support.

Just like [`useSeoMeta`](/docs/4.x/api/composables/use-seo-meta), `useServerSeoMeta` composable lets you define your site's SEO meta tags as a flat object with full TypeScript support.

<read-more to="/docs/4.x/api/composables/use-seo-meta">



</read-more>

In most instances, the meta doesn't need to be reactive as robots will only scan the initial load. So we recommend using [`useServerSeoMeta`](/docs/4.x/api/composables/use-server-seo-meta) as a performance-focused utility that will not do anything (or return a `head` object) on the client.

```vue [app/app.vue]
<script setup lang="ts">
useServerSeoMeta({
  robots: 'index, follow',
})
</script>
```

Parameters are exactly the same as with [`useSeoMeta`](/docs/4.x/api/composables/use-seo-meta)

<read-more to="/docs/4.x/getting-started/seo-meta">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/api/composables/use-state.md

# Source: https://nuxt.com/raw/docs/4.x/api/composables/use-state.md

# useState

> The useState composable creates a reactive and SSR-friendly shared state.

## Usage

```ts
// Create a reactive state and set default value
const count = useState('counter', () => Math.round(Math.random() * 100))
```

<read-more to="/docs/4.x/getting-started/state-management">



</read-more>

<important>

Because the data inside `useState` will be serialized to JSON, it is important that it does not contain anything that cannot be serialized, such as classes, functions or symbols.

</important>

<warning>

`useState` is a reserved function name transformed by the compiler, so you should not name your own function `useState`.

</warning>

<video-accordion title="Watch a video from Alexander Lichter about why and when to use useState" video-id="mv0WcBABcIk">



</video-accordion>

## Using `shallowRef`

If you don't need your state to be deeply reactive, you can combine `useState` with [`shallowRef`](https://vuejs.org/api/reactivity-advanced#shallowref). This can improve performance when your state contains large objects and arrays.

```ts
const state = useState('my-shallow-state', () => shallowRef({ deep: 'not reactive' }))
// isShallow(state) === true
```

## Type

```ts [Signature]
export function useState<T> (init?: () => T | Ref<T>): Ref<T>
export function useState<T> (key: string, init?: () => T | Ref<T>): Ref<T>
```

- `key`: A unique key ensuring that data fetching is properly de-duplicated across requests. If you do not provide a key, then a key that is unique to the file and line number of the instance of [`useState`](/docs/4.x/api/composables/use-state) will be generated for you.
- `init`: A function that provides initial value for the state when not initiated. This function can also return a `Ref`.
- `T`: (typescript only) Specify the type of state

## Troubleshooting

### `Cannot stringify arbitrary non-POJOs`

This error occurs when you try to store a non-serializable payload with `useState`, such as class instances.

If you want to store class instances with `useState` that are not supported by Nuxt, you can use [`definePayloadPlugin`](/docs/4.x/api/composables/use-nuxt-app#custom-reducerreviver) to add a custom serializer and deserializer for your classes.

<read-more to="/docs/4.x/api/composables/use-nuxt-app#payload">



</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/directory-structure/utils.md

# Source: https://nuxt.com/raw/docs/4.x/directory-structure/app/utils.md

# utils

> Use the utils/ directory to auto-import your utility functions throughout your application.

The main purpose of the [`app/utils/` directory](/docs/4.x/directory-structure/app/utils) is to allow a semantic distinction between your Vue composables and other auto-imported utility functions.

## Usage

**Method 1:** Using named export

```ts [utils/index.ts]twoslash
export const { format: formatNumber } = Intl.NumberFormat('en-GB', {
  notation: 'compact',
  maximumFractionDigits: 1,
})
```

**Method 2:** Using default export

```ts [utils/random-entry.ts or utils/randomEntry.ts]twoslash
// It will be available as randomEntry() (camelCase of file name without extension)
export default function (arr: Array<any>) {
  return arr[Math.floor(Math.random() * arr.length)]
}
```

You can now use auto imported utility functions in `.js`, `.ts` and `.vue` files

```vue [app/app.vue]
<template>
  <p>{{ formatNumber(1234) }}</p>
</template>
```

<read-more to="/docs/4.x/guide/concepts/auto-imports">



</read-more>

<link-example to="/docs/4.x/examples/features/auto-imports">



</link-example>

<tip>

The way `app/utils/` auto-imports work and are scanned is identical to the [`app/composables/`](/docs/4.x/directory-structure/app/composables) directory.

</tip>

<important>

These utils are only available within the Vue part of your app. <br />


Only `server/utils` are auto-imported in the [`server/`](/docs/4.x/directory-structure/server#server-utilities) directory.

</important>

---

# Source: https://nuxt.com/raw/blog/v3-10.md

# Nuxt 3.10

> Nuxt 3.10 is out - packed with features and fixes. Here are a few highlights.

v3.10 comes quite close on the heels of v3.9, but it's packed with features and fixes. Here are a few highlights.

### ✨ Experimental shared `asyncData` when prerendering

When prerendering routes, we can end up refetching the same data over and over again. In Nuxt 2 it was possible to create a 'payload' which could be fetched once and then accessed in every page (and this is of course possible to do manually in Nuxt 3 - see [this article](https://roe.dev/blog/shared-data-nuxt-generate)).

With [#24894](https://github.com/nuxt/nuxt/pull/24894), we are now able to do this automatically for you when prerendering your site. Your [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch) calls will be deduplicated and cached between renders of your site.

```ts [nuxt.config.ts]
export defineNuxtConfig({
  experimental: {
    sharedPrerenderData: true
  }
})
```

<important>

It is particularly important to make sure that any unique key of your data is always resolvable to the same data. For example, if you are using `useAsyncData` to fetch data related to a particular page, you should provide a key that uniquely matches that data. (`useFetch` should do this automatically.)

</important>

<read-more to="/docs/guide/going-further/experimental-features#sharedprerenderdata">



</read-more>

### 🆔 SSR-safe accessible unique ID creation

We now ship a `useId` composable for generating SSR-safe unique IDs ([#23368](https://github.com/nuxt/nuxt/pull/23368)). This allows creating more accessible interfaces in your app. For example:

```vue [components/MyForm.vue]
<script setup>
const emailId = useId()
const passwordId = useId()
</script>

<template>
  <form>
    <label :for="emailId">Email</label>
    <input
      :id="emailId"
      name="email"
      type="email"
    >
    <label :for="passwordId">Password</label>
    <input
      :id="passwordId"
      name="password"
      type="password"
    >
  </form>
</template>
```

### ✍️ Extending `app/router.options`

It's now possible for module authors to inject their own `router.options` files ([#24922](https://github.com/nuxt/nuxt/pull/24922)). The new `pages:routerOptions` hook allows module authors to do things like add custom `scrollBehavior` or add runtime augmenting of routes.

<read-more to="/docs/guide/going-further/custom-routing#router-options">



</read-more>

### <icon name="i-vscode-icons-file-type-node"></icon> Client-side Node.js support

We now support (experimentally) polyfilling key Node.js built-ins ([#25028](https://github.com/nuxt/nuxt/pull/25028)), just as we already do via Nitro on the server when deploying to non-Node environments.

That means that, within your client-side code, you can import directly from Node built-ins (`node:` and node imports are supported). However, nothing is globally injected for you, to avoid increasing your bundle size unnecessarily. You can either import them where needed.

```ts [some-file.ts]
import { Buffer } from 'node:buffer'
import process from 'node:process'
```

Or provide your own polyfill, for example, inside a Nuxt plugin.

```ts [plugins/node.client.ts]
import { Buffer } from 'node:buffer'
import process from 'node:process'

globalThis.Buffer = Buffer
globalThis.process = process

export default defineNuxtPlugin({})
```

This should make life easier for users who are working with libraries without proper browser support. However, because of the risk in increasing your bundle unnecessarily, we would strongly urge users **to choose other alternatives** if at all possible.

### 🍪 Better cookie reactivity

We now allow you to opt-in to using the [CookieStore](https://developer.mozilla.org/en-US/docs/Web/API/CookieStore). If browser support is present, this will then be used instead of a BroadcastChannel to update `useCookie` values reactively when the cookies are updated ([#25198](https://github.com/nuxt/nuxt/pull/25198)).

This also comes paired with a new composable, `refreshCookie` which allows manually refreshing cookie values, such as after performing a request.

<read-more to="/docs/api/utils/refresh-cookie">



</read-more>

### 🏥 Detecting anti-patterns

In this release, we've also shipped a range of features to detect potential bugs and performance problems.

- We now will throw an error if `setInterval` is used on server ([#25259](https://github.com/nuxt/nuxt/pull/25259)).
- We warn (in development only) if data fetch composables are used wrongly ([#25071](https://github.com/nuxt/nuxt/pull/25071)), such as outside of a plugin or setup context.
- We warn (in development only) if you are not using `<NuxtPage />` but have the `vue-router` integration enabled ([#25490](https://github.com/nuxt/nuxt/pull/25490)). (`<RouterView />` should not be used on its own.)

### 🧂 Granular view transitions support

It's now possible to control view transitions support on a per-page basis, using `definePageMeta` ([#25264](https://github.com/nuxt/nuxt/pull/25264)).

You need to have experimental view transitions support enabled first:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    viewTransition: true
  },
  app: {
    // you can disable them globally if necessary (they are enabled by default)
    viewTransition: false
  }
})
```

And you can opt in/out granularly:

```vue [pages/index.vue]
<script setup lang="ts">
definePageMeta({
  viewTransition: false
})
</script>
```

Finally, Nuxt will not apply View Transitions if the user's browser matches `prefers-reduced-motion: reduce` ([#22292](https://github.com/nuxt/nuxt/pull/22292)). You can set `viewTransition: 'always'`; it will then be up to you to respect the user's preference.

### 🏗️ Build-time route metadata

It's now possible to access routing metadata defined in `definePageMeta` at build-time, allowing modules and hooks to modify and change these values ([#25210](https://github.com/nuxt/nuxt/pull/25210)).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    scanPageMeta: true
  }
})
```

Please, experiment with this and let us know how it works for you. We hope to improve performance and enable this by default in a future release so modules like `@nuxtjs/i18n` and others can provide a deeper integration with routing options set in `definePageMeta`.

### 📦 Bundler module resolution

With [#24837](https://github.com/nuxt/nuxt/pull/24837), we are now opting in to the TypeScript `bundler` resolution which should more closely resemble the actual way that we resolve subpath imports for modules in Nuxt projects.

'Bundler' module resolution is [recommended by Vue](https://github.com/vuejs/tsconfig/blob/mainz/tsconfig.json#L24-L26) and [by Vite](https://vitejs.dev/guide/performance.html#reduce-resolve-operations), but unfortunately there are still many packages that do not have the correct entries in their `package.json`.

As part of this, we opened 85 PRs across the ecosystem to test switching the default, and identified and fixed some issues.

If you need to switch off this behaviour, you can do so. However, please consider raising an issue (feel free to tag me in it) in the library or module's repo so it can be resolved at source.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  future: {
    typescriptBundlerResolution: false
  }
})
```

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## Full Release Notes

<read-more to="https://github.com/nuxt/nuxt/releases/tag/v3.10.0" icon="i-simple-icons-github" target="_blank">

Read the full release notes of Nuxt `v3.10.0`.

</read-more>

Thank you for reading this far! We hope you enjoy the new release. Please do let us know if you have any feedback or issues.

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/v3-11.md

# Nuxt 3.11

> Nuxt 3.11 is out - with better logging, preview mode, server pages and much more!

This is possibly the last minor release before Nuxt v4, and so we've packed it full of features and improvements we hope will delight you! ✨

## 🪵 Better logging

When developing a Nuxt application and using `console.log` in your application, you may have noticed that these logs are not displayed in your browser console when refreshing the page (during server-side rendering). This can be frustrating, as it makes it difficult to debug your application. This is now a thing of the past!

Now, when you have server logs associated with a request, they will be bundled up and passed to the client and displayed in your browser console. [Asynchronous context](https://nodejs.org/docs/latest-v20.x/api/async_context.html) is used to track and associate these logs with the request that triggered them. ([#25936](https://github.com/nuxt/nuxt/pull/25936)).

For example, this code:

```vue [pages/index.vue]
<script setup>
console.log('Log from index page')

const { data } = await useAsyncData(() => {
  console.log('Log inside useAsyncData')
  return $fetch('/api/test')
})
</script>
```

will now log to your browser console when you refresh the page:

```bash
Log from index page
[ssr] Log inside useAsyncData 
    at pages/index.vue
```

👉 We also plan to support streaming of subsequent logs to the Nuxt DevTools in future.

We've also added a `dev:ssr-logs` hook (both in Nuxt and Nitro) which is called on server and client, allowing you to handle them yourself if you want to.

If you encounter any issues with this, it is possible to disable them - or prevent them from logging to your browser console.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  features: {
    devLogs: false
    // or 'silent' to allow you to handle yourself with `dev:ssr-logs` hook
  },
})
```

## 🎨 Preview mode

A new `usePreviewMode` composable aims to make it simple to use preview mode in your Nuxt app.

```ts [plugins/test.client.ts]
const { enabled, state } = usePreviewMode()
```

When preview mode is enabled, all your data fetching composables, like `useAsyncData` and `useFetch` will rerun, meaning any cached data in the payload will be bypassed.

<read-more to="/docs/api/composables/use-preview-mode">



</read-more>

## 💰 Cache-busting payloads

We now automatically cache-bust your payloads if you haven't disabled Nuxt's app manifest, meaning you shouldn't be stuck with outdated data after a deployment ([#26068](https://github.com/nuxt/nuxt/pull/26068)).

## 👮‍♂️ Middleware `routeRules`

It's now possible to define middleware for page paths within the Vue app part of your application (that is, not your Nitro routes) ([#25841](https://github.com/nuxt/nuxt/pull/25841)).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/admin/**': {
      // or appMiddleware: 'auth'
      appMiddleware: ['auth']
    },
    '/admin/login': {
      // You can 'turn off' middleware that would otherwise run for a page
      appMiddleware: {
        auth: false
      }
    },
  },
})
```

<read-more to="/docs/guide/concepts/rendering#route-rules">



</read-more>

## ⌫ New `clear` data fetching utility

Now, `useAsyncData` and `useFetch` expose a `clear` utility. This is a function that can be used to set `data` to undefined, set `error` to `null`, set `pending` to `false`, set `status` to `idle`, and mark any currently pending requests as cancelled. ([#26259](https://github.com/nuxt/nuxt/pull/26259))

```vue
<script setup lang="ts">
const { data, clear } = await useFetch('/api/test')

const route = useRoute()
watch(() => route.path, (path) => {
  if (path === '/') clear()
})
</script>
```

<read-more to="/docs/getting-started/data-fetching">



</read-more>

## 🕳️ New `#teleports` target

Nuxt now includes a new `<div id="teleports"></div>` element in your app within your `<body>` tag. It supports server-side teleports, meaning you can do this safely on the server:

```vue [app.vue]
<template>
  <Teleport to="#teleports">
    <span>
      Something
    </span>
  </Teleport>
</template>
```

## 🚦 Loading indicator and transition controls

It's now possible to set custom timings for hiding the loading indicator, and forcing the `finish()` method if needed ([#25932](https://github.com/nuxt/nuxt/pull/25932)).

There's also a new `page:view-transition:start` hook for hooking into the View Transitions API ([#26045](https://github.com/nuxt/nuxt/pull/26045)) if you have that feature enabled.

## 🛍️ Server- and client-only pages

This release sees server- and client-only pages land in Nuxt! You can now add a `.server.vue` or `.client.vue` suffix to a page to get automatic handling of it.

**Client-only pages** will render entirely on the client-side, and skip server-rendering entirely, just as if the entire page was wrapped in `<ClientOnly>`. Use this responsibly. The flash of load on the client-side can be a bad user experience so make sure you really need to avoid server-side loading. Also consider using `<ClientOnly>` with a `fallback` slot to render a skeleton loader ([#25037](https://github.com/nuxt/nuxt/pull/25037)).

⚗️ **Server-only pages** are even more useful because they enable you to integrate fully-server rendered HTML within client-side navigation. They will even be prefetched when links to them are in the viewport - so you will get instantaneous loading ([#24954](https://github.com/nuxt/nuxt/pull/24954)).

## 🤠 Server component bonanza

When you are using server components, you can now use the `nuxt-client` attribute anywhere within your tree ([#25479](https://github.com/nuxt/nuxt/pull/25479)).

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    componentIslands: {
      selectiveClient: 'deep'
    }
  },
})
```

You can listen to an `@error` event from server components that will be triggered if there is any issue loading the component ([#25798](https://github.com/nuxt/nuxt/pull/25798)).

Finally, server-only components are now smartly enabled when you have a server-only component or a server-only page within your project or any of its layers ([#26223](https://github.com/nuxt/nuxt/pull/26223)).

<callout type="warning">

Server components remain experimental and their API may change, so be careful
before depending on implementation details.

</callout>

## 🔥 Performance improvements

We've shipped a number of performance improvements, including only updating changed virtual templates ([#26250](https://github.com/nuxt/nuxt/pull/26250)), using a 'layered' prerender cache ([#26104](https://github.com/nuxt/nuxt/pull/26104)) that falls back to filesystem instead of keeping everything in memory when prerendering - and lots of other examples.

## 📂 Public assets handling

We have shipped a reimplementation of Vite's public asset handling, meaning that public assets in your `public/` directory or your layer directories are now resolved entirely by Nuxt ([#26163](https://github.com/nuxt/nuxt/pull/26163)), so if you have added `nitro.publicAssets` directories with a custom prefix, these will now work.

## 📦 Chunk naming

We have changed the default `_nuxt/[name].[hash].js` file name pattern for your JS chunks. Now, we default to `_nuxt/[hash].js`. This is to avoid false positives by ad blockers triggering off your component or chunk names, which can be a very difficult issue to debug. ([#26203](https://github.com/nuxt/nuxt/pull/26203))

You can easily configure this to revert to previous behaviour if you wish:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  vite: {
    $client: {
      build: {
        rollupOptions: {
          output: {
            chunkFileNames: '_nuxt/[name].[hash].js',
            entryFileNames: '_nuxt/[name].[hash].js'
          }
        }
      }
    }
  },
})
```

## 💪 Type fixes

Previously users with `shamefully-hoist=false` may have encountered issues with types not being resolved or working correctly. You may also have encountered problems with excessive type instantiation.

We now try to tell TypeScript about certain key types so they can be resolved even if deeply nested ([#26158](https://github.com/nuxt/nuxt/pull/26158)).

There are a whole raft of other type fixes, including some regarding import types ([#26218](https://github.com/nuxt/nuxt/pull/26218) and [#25965](https://github.com/nuxt/nuxt/pull/25965)) and module typings ([#25548](https://github.com/nuxt/nuxt/pull/25548)).

## ✅ Upgrading

As usual, our recommendation for upgrading Nuxt is to run:

```bash
nuxi upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## 👉 Full release notes

<read-more to="https://github.com/nuxt/nuxt/releases/tag/v3.11.0" icon="i-simple-icons-github" target="_blank">

Read the full release notes of Nuxt `v3.11.0`.

</read-more>

Thank you for reading this far! We hope you enjoy the new release. Please do let us know if you have any feedback or issues.

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/v3-12.md

# Nuxt 3.12

> Nuxt 3.12 is out - full of improvements and preparing the way for Nuxt 4!

We're on the road to the release of Nuxt 4, but we've not held back in Nuxt v3.12.

## 🚀 Testing Nuxt 4 changes

Nuxt 4 is on the horizon, and it's now possible to test out the behaviour changes that will be coming in the next major release ([#26925](https://github.com/nuxt/nuxt/pull/26925)) by setting an option in your `nuxt.config.ts` file:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
})
```

As we've been merging PRs for Nuxt 4, we've been enabling them behind this flag. As much as possible we're aiming for backwards compatibility - our test matrix is running the same fixtures in both v3 and v4 compatibility mode.

There is a lot to say here, with 10+ different PRs and behaviour changes documented and testable, but for full details, including migration steps, see [the v4 upgrade documentation](/docs/getting-started/upgrade#testing-nuxt-4).

We'd be very grateful for early testing of what's coming in Nuxt 4! 🙏

## 📜 Nuxt Scripts auto-install

We've been gradually working to release [Nuxt Scripts](https://scripts.nuxt.com/). It's currently in public preview, but we're near a public release, so we've added some stubs for composables that (when used) will prompt installing the `@nuxt/scripts` module.

👉 Watch out for the launch - and an article explaining more!

## 🌈 Layer auto-registration and bugfixes

Just like `~/modules`, any layers within your project in the `~/layers` directory will now be automatically registered as layers in your project ([#27221](https://github.com/nuxt/nuxt/pull/27221)).

We also now correctly load layer dependencies, which should resolve a range of issues with monorepos and git installations ([#27338](https://github.com/nuxt/nuxt/pull/27338)).

## 🌐 Built-in accessibility improvements

We now have a built-in [`<NuxtRouteAnnouncer>`](/docs/api/components/nuxt-route-announcer) component and corresponding [`useRouteAnnouncer`](/docs/api/composables/use-route-announcer) composable, which will be added by default to new Nuxt templates going forward.

For full details, see [the original PR (#25741)](https://github.com/nuxt/nuxt/pull/25741) and [documentation](/docs/api/components/nuxt-route-announcer).

We're continuing to work on `nuxt/a11y` - expect to hear more on that in future!

## 🔥 Performance improvements

We've landed some performance improvements as well, many of which are behind the `compatibilityVersion: 4` flag, such as a move away from deeply reactive asyncData payloads.

Significant improvements include deduplicating modules ([#27475](https://github.com/nuxt/nuxt/pull/27475)) - which will apply mostly to layer users who specify modules in their layers. In one project, we saw 30s+ improvement in starting Nuxt.

We've also improved Vite dev server start up time by excluding common ESM dependencies from pre-bundling, and would suggest module authors consider doing the same ([#27372](https://github.com/nuxt/nuxt/pull/27372)).

We improved chunk determinism, so sequential builds should be less likely to have *completely* different chunk hashes ([#27258](https://github.com/nuxt/nuxt/pull/27258)).

And we tree shake more client-only composables from your server builds ([#27044](https://github.com/nuxt/nuxt/pull/27044)), and have reduced the size of server component payloads ([#26863](https://github.com/nuxt/nuxt/pull/26863)).

## 👨‍👩‍👧‍👦 Multi-app support

We've landed a couple of changes that take us toward a place of supporting multi-app natively in Nuxt, including a `multiApp` experimental flag ([#27291](https://github.com/nuxt/nuxt/pull/27291)) and the ability to have multiple Nuxt app instances running in parallel at runtime ([#27068](https://github.com/nuxt/nuxt/pull/27068)).

While it's not yet ready, please do follow along on [the tracker issue](https://github.com/nuxt/nuxt/issues/21635), and feel free to pitch in if this is interesting to you.

## ⛑️ DX wins

We now serialise more things in your dev server logs, including VNodes ([#27309](https://github.com/nuxt/nuxt/pull/27309)) and [URLs](https://github.com/nuxt/nuxt/commit/a549b46e9). We also addressed a bug that could lead to a frozen dev server.

When accessing private runtime config in the browser, we now let you know with a more informative error message ([#26441](https://github.com/nuxt/nuxt/pull/26441)).

## 🪨 Stabilising features

We've removed some experimental options that have been stabilised and which we feel no longer need to be configurable:

- `experimental.treeshakeClientOnly` (enabled by default since v3.0.0)
- `experimental.configSchema` (enabled by default since v3.3.0)
- `experimental.polyfillVueUseHead` (disabled since v3.4.0) - implementable in user-land with [plugin](https://github.com/nuxt/nuxt/blob/f209158352b09d1986aa320e29ff36353b91c358/packages/nuxt/src/head/runtime/plugins/vueuse-head-polyfill.ts#L10-L11)
- `experimental.respectNoSSRHeader` (disabled since v3.4.0) - implementable in user-land with [server middleware](https://github.com/nuxt/nuxt/blob/c660b39447f0d5b8790c0826092638d321cd6821/packages/nuxt/src/core/runtime/nitro/no-ssr.ts#L8-L9)

We've also enabled `scanPageMeta` by default ([#27134](https://github.com/nuxt/nuxt/pull/27134)). This pulls out any page metadata in your `definePageMeta` macro, and makes it available to modules (like `@nuxtjs/i18n`) so they can augment it.

This unlocks much better module/typed routing integration, but has a potential performance cost - so please file an issue if you experience any problems.

## 💪 Type improvements

We now have support for typed `#fallback` slots in server components ([#27097](https://github.com/nuxt/nuxt/pull/27097)).

We've also improved some defaults in your generated `tsconfig.json`, including setting `module: 'preserve'` if you have a locally installed TypeScript v5.4 version ([see docs](https://www.typescriptlang.org/tsconfig/#preserve)) - see [#26667](https://github.com/nuxt/nuxt/pull/26667), [#27485](https://github.com/nuxt/nuxt/pull/27485).

## 📦 Module author/power user improvements

We have shipped a range of type improvements for module authors, including:

- support for typed module options in `installModule` ([#26744](https://github.com/nuxt/nuxt/pull/26744))
- the option to specify compatibility with certain builders (vite/webpack) in module options ([#27022](https://github.com/nuxt/nuxt/pull/27022))
- a new `onPrehydrate` hook for hooking into the browser hydration cycle ([#27037](https://github.com/nuxt/nuxt/pull/27037))
- the ability to access and update *resolved* runtime configuration within modules, with new build-time `useRuntimeConfig` and `updateRuntimeConfig` utils ([#27117](https://github.com/nuxt/nuxt/pull/27117))

## 🎨 Inlined UI templates

If you previously used `@nuxt/ui-templates` then it may be worth knowing that we have moved them from [a separate repository](https://github.com/nuxt/ui-templates) into the [nuxt/nuxt](https://github.com/nuxt/nuxt) monorepo. (This is purely a refactor rather than a change, although you can expect some new designs for Nuxt v4.)

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## Full Release Notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.12.0">

Read the full release notes of Nuxt `v3.12.0`.

</read-more>

A huge thank you to the 75+ Nuxt contributors and community members who have been part of this release. ❤️

Finally, thank you for reading this far! We hope you enjoy v3.12, and please do let us know if you have any feedback or issues. 🙏

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/v3-13.md

# Nuxt 3.13

> Nuxt 3.13 is out - porting back some of the new features we're building for Nuxt 4!

## 🏘️ Route Groups

We now support naming directories with parentheses/brackets to organise your routes without affecting the path.

For example:

```bash [Directory structure]
-| pages/
---| index.vue
---| (marketing)/
-----| about.vue
-----| contact.vue
```

This will produce `/`, `/about` and `/contact` pages in your app. The `marketing` group is ignored for purposes of your URL structure.

Read more in [the original PR](https://github.com/nuxt/nuxt/pull/28276).

## 🏝️ Islands and Head Metadata

It's now possible for server component islands to manipulate the head, such as by adding SEO metadata when rendering.

Read more in [#27987](https://github.com/nuxt/nuxt/pull/27987).

## 🪝 Custom Prefetch Triggers

We now support custom prefetch triggers for `NuxtLink` ([#27846](https://github.com/nuxt/nuxt/pull/27846)).

For example:

```vue [pages/index.vue]
<template>
  <div>
    <NuxtLink prefetch-on="interaction">
      This will prefetch when hovered or when it gains focus
    </NuxtLink>
    <!-- note that you probably don't want both enabled! -->
    <NuxtLink :prefetch-on="{ visibility: true, interaction: true }">
      This will prefetch when hovered/focus - or when it becomes visible
    </NuxtLink>
  </div>
</template>
```

It's also possible to enable/disable these globally for your app and override them per link.

For example:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        prefetch: true,
        prefetchOn: { visibility: false, interaction: true }
      }
    }
  }
})
```

## 🗺️  Better Server Source Maps

When running with `node --enable-source-maps`, you may have noticed that the source maps for the Vue files in your server build pointed to the Vite build output (something like `.nuxt/dist/server/_nuxt/index-O15BBwZ3.js`).

Now, even after your Nitro build, your server source maps will reference your original source files ([#28521](https://github.com/nuxt/nuxt/pull/28521)).

Note that one of the easiest ways of improving your build performance is to turn off source maps if you aren't using them, which you can do easily in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  sourcemap: {
    server: false,
    client: true,
  },
})
```

## 🎁 New Features for Module Authors

In the run-up to Nuxt v4, we're working on adding some key functionality for module authors, including a new `isNuxtMajorVersion` utility where required ([#27579](https://github.com/nuxt/nuxt/pull/27579)) and better inferred typing for merged module options using the new `defineNuxtModule().with()` method ([#27520](https://github.com/nuxt/nuxt/pull/27520)).

## ✨ Improved Dev Warnings

We no longer warn when using data fetching composables in middleware ([#28604](https://github.com/nuxt/nuxt/pull/28604)) and we warn when user components' names begin with Lazy ([#27838](https://github.com/nuxt/nuxt/pull/27838)).

## 🚨 Vue TypeScript Changes

For a while, in the Vue ecosystem, we've been augmenting `@vue/runtime-core` to add custom properties and more to `vue`. However, this inadvertently breaks the types for projects that augment `vue` - which is now the officially recommended and documented way to augment these interfaces (for example, [ComponentCustomProperties](https://vuejs.org/api/utility-types.html#componentcustomproperties), [GlobalComponents](https://vuejs.org/guide/extras/web-components.html#web-components-and-typescript) and [so on](https://vuejs.org/guide/typescript/options-api.html#augmenting-global-properties)).

This means *all* libraries must update their code (or it will break the types of libraries that augment `vue` instead).

We've updated our types in Nuxt along these lines but you may experience issues with the latest `vue-router` when used with libraries which haven't yet done so.

Please create an issue with a reproduction - I'll happily help create a PR to resolve in the upstream library in question. Or you may be able to work around the issue by creating a `declarations.d.ts` in the root of your project with the following code ([credit](https://github.com/nuxt/nuxt/pull/28542#issuecomment-2293282891) to [@BobbieGoede](https://github.com/BobbieGoede)):

```ts [declarations.d.ts]
import type {
  ComponentCustomOptions as _ComponentCustomOptions,
  ComponentCustomProperties as _ComponentCustomProperties,
} from 'vue';

declare module '@vue/runtime-core' {
  interface ComponentCustomProperties extends _ComponentCustomProperties {}
  interface ComponentCustomOptions extends _ComponentCustomOptions {}
}
```

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## Full Release Notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.13.0">

Read the full release notes of Nuxt `v3.13.0`.

</read-more>

A huge thank you to everyone who's been a part of this release - you are the ones who make Nuxt possible. ❤️

Don't hesitate to let us know if you have any feedback or issues! 🙏

---

# Source: https://nuxt.com/raw/blog/v3-14.md

# Nuxt 3.14

> Nuxt 3.14 is out - with a new rspack builder, shared folder, and performance enhancements!

Behind the scenes, a lot has been going on in preparation for the release of Nuxt v4 (particularly on the `unjs` side with preparations for Nitro v3!)

### ⚡️ Faster starts powered by `jiti`

Loading the nuxt config file, as well as modules and other build-time code, is now powered by `jiti` v2. You can see more about the release in the [jiti v2 release notes](https://github.com/unjs/jiti/releases/tag/v2.0.0), but one of the most important pieces is native node esm import (where possible), which should mean a faster start. ✨

### 📂 Shared folder for code and types shared with client/server

You should never import Vue app code in your nitro code (or the other way around). But this has meant a friction point when it comes to sharing types or utilities that *don't* rely on the nitro/vue contexts.

For this, we have a new `shared/` folder ([#28682](https://github.com/nuxt/nuxt/pull/28682)). You can't import Vue or nitro code *into* files in this folder, but it produces auto-imports (if you're using `compatibilityVersion: 4`) which you can consume throughout the rest of your app.

If needed you can use the new `#shared` alias which points to this folder.

The shared folder is alongside your `server/` folder. (If you're using `compatibilityVersion: 4`, this means it's not inside your `app/` folder.)

### 🦀 `rspack` builder

We're excited to announce a new first-class Nuxt builder for `rspack`. It's still experimental but we've refactored the internal Nuxt virtual file system to use `unplugin` to make this possible.

Let us know if you like it - and feel free to raise any issues you experience with it.

👉 To try it out, you can use [this starter](https://github.com/danielroe/nuxt-rspack-starter) - or just install `@nuxt/rspack-builder` and set `builder: 'rspack'` in your nuxt config file.

### ✨ New composables

We have new `useResponseHeader` and `useRuntimeHook` composables ([#27131](https://github.com/nuxt/nuxt/pull/27131) and [#29741](https://github.com/nuxt/nuxt/pull/29741)).

### 🔧 New module utilities

We now have a new `addServerTemplate` utility ([#29320](https://github.com/nuxt/nuxt/pull/29320)) for adding virtual files for access inside nitro runtime routes.

### 🚧 v4 changes

We've merged some changes which only take effect with `compatibilityVersion: 4`, but which [you can opt-into earlier](/docs/getting-started/upgrade#testing-nuxt-4).

1. previously, if you had a component like `~/components/App/Header.vue` this would be visible in your devtools as `<Header>`. From v4 we ensure this is `<AppHeader>`, but it's opt-in to avoid breaking any manual `<KeepAlive>` you might have implemented. ([#28745](https://github.com/nuxt/nuxt/pull/28745)).
2. Nuxt scans page metadata from your files, before calling `pages:extend`. But this has led to some confusing behaviour, as pages added at this point do not end up having their page metadata respected. So we now do not scan metadata before calling `pages:extend`. Instead, we have a new `pages:resolved` hook, which is called after `pages:extend`, after all pages have been augmented with their metadata. I'd recommend opting into this by setting `experimental.scanPageMeta` to `after-resolve`, as it solves a number of bugs.

## 🗺️ Roadmap to v3.15

They didn't quite make it in time for v3.14 but for the next minor release you can expect (among other things):

- auto-imported directives from modules ([#29203](https://github.com/nuxt/nuxt/pull/29203))
- 'isolated' page renders ([#29366](https://github.com/nuxt/nuxt/pull/29366))
- delayed hydration ([#26468](https://github.com/nuxt/nuxt/pull/26468))

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## Full Release Notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.14.0">

Read the full release notes of Nuxt `v3.14.0`.

</read-more>

A huge thank you to everyone who's been a part of this release. We have exciting things in store with our next releases! ❤️

Don't hesitate to let us know if you have any feedback or issues! 🙏

---

# Source: https://nuxt.com/raw/blog/v3-15.md

# Nuxt 3.15

> Nuxt 3.15 is out - with Vite 6, better HMR and faster performance

We're continuing to work on the release of Nitro v3, Nuxt v4 and more. But we're delighted to ship Nuxt v3.15 (just) in time for Christmas.

## ❄️ Snowfall!

Happy holidays! You'll notice when you start Nuxt that (if you're in the Northern Hemisphere) there's some snow on the loading screen ([#29871](https://github.com/nuxt/nuxt/pull/29871)).

## ⚡️ Vite 6 included

Nuxt v3.15 includes [Vite 6](https://vite.dev/blog/announcing-vite6) for the first time. Although this is a major version, we expect that this won't be a breaking change for Nuxt users (see full [migration guide](https://vite.dev/guide/migration.html)). However, please take care if you have dependencies that rely on a particular Vite version.

One of the most significant changes with Vite 6 is the new Environment API, which we hope to use in conjunction with Nitro to improve the server dev environment. Watch this space!

You can read the full list of changes in the [Vite 6 changelog](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md#600-2024-11-26).

## 🪵 Chromium devtools improvements

We talk a lot about the Nuxt DevTools, but v3.15 ships with better integration in dev mode for Chromium-based browser devtools.

We now use the [Chrome DevTools extensibility API](https://developer.chrome.com/docs/devtools/performance/extension) to add support for printing nuxt hook timings in the browser devtools performance panel.

![CleanShot 2024-11-14 at 15 05 22@2x](https://github.com/user-attachments/assets/57525027-750a-462f-b713-398302aec0cd)

## 🗺️ Navigation mode for `callOnce`

`callOnce` is a built-in Nuxt composable for running code only once. For example, if the code runs on the server it won't run again on the client. But sometimes you do want code to run on *every navigation* - just avoid the initial server/client double load. For this, there's a new `mode: 'navigation'` option that will run the code only once *per navigation*. (See [#30260](https://github.com/nuxt/nuxt/pull/30260) for more info.)

```ts
await callOnce(() => counter.value++, { mode: 'navigation' })
```

## 🥵 HMR for templates, pages + page metadata

We now implement hot module reloading for Nuxt's virtual files (like routes, plugins, generated files) as well as for the content of page metadata (within a `definePageMeta` macro) ([#30113](https://github.com/nuxt/nuxt/pull/30113)).

This should mean you have a faster experience in development, as well as not needing to reload the page when making changes to your routes.

## 📋 Page meta enhancements

We now support extracting extra page meta keys (likely used by module authors) via `experimental.extraPageMetaExtractionKeys` ([#30015](https://github.com/nuxt/nuxt/pull/30015)). This enables module authors to use this information at build time, in the `pages:resolved` hook.

We also now support local functions in `definePageMeta` ([#30241](https://github.com/nuxt/nuxt/pull/30241)). This means you can do something like this:

```ts
function validateIdParam(route) {
  return !!(route.params.id && !isNaN(Number(route.params.id)))
}

definePageMeta({
  validate: validateIdParam,
})
```

## 🔥 Performance improvements

We now preload the app manifest in the browser if it will be used when hydrating the app ([#30017](https://github.com/nuxt/nuxt/pull/30017)).

We'll also tree shake vue-router's hash mode history out of your bundle if we can - specifically, if you haven't customised your `app/router.options.ts` ([#30297](https://github.com/nuxt/nuxt/pull/30297)).

## 🐣 v4 updates

If A few more changes shipped for the new defaults for v4, including only inlining styles by default for Vue components ([#30305](https://github.com/nuxt/nuxt/pull/30305)).

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## Full release notes

<read-more color="neutral" icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.15.0">

Read the full release notes of Nuxt `v3.15.0`.

</read-more>

A huge thank you to everyone who's been a part of this release. ❤️

Don't hesitate to let us know if you have any feedback or issues! 🙏

---

# Source: https://nuxt.com/raw/blog/v3-16.md

# Nuxt 3.16

> Nuxt 3.16 is out - packed with features and performance improvements

There's a lot in this one!

## ⚡️ A New New Nuxt

Say hello to `create-nuxt`, a new tool for starting Nuxt projects (big thanks to [@devgar](https://github.com/devgar) for donating the package name)!

It's a streamlined version of `nuxi init` - just a sixth of the size and bundled as a single file with all dependencies inlined, to get you going as fast as possible.

Starting a new project is as simple as:

```bash
npm create nuxt
```

![screenshot of create nuxt app](/assets/blog/create-nuxt-ascii.jpeg)

Special thanks to [@cmang](https://github.com/cmang) for the [beautiful ASCII-art](https://bsky.app/profile/durdraw.org/post/3liadod3gv22a). ❤️

Want to learn more about where we're headed with the Nuxt CLI? Check out our roadmap [here](https://github.com/nuxt/cli/issues/648), including our plans for an [interactive modules selector](https://github.com/nuxt/cli/issues/754).

## 🚀 Unhead v2

We've upgraded to `unhead` v2, the engine behind Nuxt's `<head>` management. This major version removes deprecations and improves how context works:

- For Nuxt 3 users, we're shipping a legacy compatibility build so nothing breaks
- The context implementation is now more direct via Nuxt itself

```ts
// Nuxt now re-exports composables while properly resolving the context
export function useHead(input, options = {}) {
  const unhead = injectHead(options.nuxt)
  return head(input, { head: unhead, ...options })
}
```

If you're using Unhead directly in your app, keep in mind:

1. Import from Nuxt's auto-imports or `#app/composables/head` instead of `@unhead/vue`
2. Importing directly from `@unhead/vue` might lose async context

Don't worry though - we've maintained backward compatibility in Nuxt 3, so most users won't need to change anything!

If you've opted into `compatibilityVersion: 4`, check out [our upgrade guide](/docs/getting-started/upgrade#unhead-v2) for additional changes.

## 🔧 Devtools v2 Upgrade

Nuxt Devtools has leveled up to v2 ([#30889](https://github.com/nuxt/nuxt/pull/30889))!

You'll love the new features like custom editor selection, Discovery.js for inspecting resolved configs (perfect for debugging), the return of the schema generator, and slimmer dependencies.

One of our favorite improvements is the ability to track how modules modify your Nuxt configuration - giving you X-ray vision into what's happening under the hood.

👉 Discover all the details in the [Nuxt DevTools release notes](https://github.com/nuxt/devtools/releases).

## ⚡️ Performance Improvements

We're continuing to make Nuxt faster, and there are a number of improvements in v3.16:

1. Using [`exsolve`](https://github.com/unjs/exsolve) for module resolution ([#31124](https://github.com/nuxt/nuxt/pull/31124)) along with the rest of the unjs ecosystem (nitro, c12, pkg-types, and more) - which dramatically speeds up module resolution
2. Smarter module resolution paths ([#31037](https://github.com/nuxt/nuxt/pull/31037)) - prioritizes direct imports for better efficiency
3. Eliminated duplicated Nitro alias resolution ([#31088](https://github.com/nuxt/nuxt/pull/31088)) - leaner file handling
4. Streamlined `loadNuxt` by skipping unnecessary resolution steps ([#31176](https://github.com/nuxt/nuxt/pull/31176)) - faster startups
5. Adopt `oxc-parser` for parsing in Nuxt plugins ([#30066](https://github.com/nuxt/nuxt/pull/30066))

All these speed boosts happen automatically - no configuration needed!

Shout out to [CodSpeed](https://codspeed.io/) with [Vitest benchmarking](https://vitest.dev/guide/features.html#benchmarking) to measure these improvements in CI - it has been really helpful.

To add some anecdotal evidence, my personal site at [roe.dev](https://github.com/danielroe/roe.dev) loads 32% faster with v3.16, and [nuxt.com](https://github.com/nuxt/nuxt.com) is 28% faster. I hope you see similar results! ⚡️

## 🕰️ Delayed Hydration Support

We're very pleased to bring you native delayed/lazy hydration support ([#26468](https://github.com/nuxt/nuxt/pull/26468))! This lets you control exactly when components hydrate, which can improve initial load performance and time-to-interactive. We're leveraging Vue's built-in hydration strategies - [check them out in the Vue docs](https://vuejs.org/guide/components/async.html#lazy-hydration).

```vue
<template>
  <!-- Hydrate when component becomes visible in viewport -->
  <LazyExpensiveComponent hydrate-on-visible />
  
  <!-- Hydrate when browser is idle -->
  <LazyHeavyComponent hydrate-on-idle />
  
  <!-- Hydrate on interaction (mouseover in this case) -->
  <LazyDropdown hydrate-on-interaction="mouseover" />
  
  <!-- Hydrate when media query matches -->
  <LazyMobileMenu hydrate-on-media-query="(max-width: 768px)" />
  
  <!-- Hydrate after a specific delay in milliseconds -->
  <LazyFooter :hydrate-after="2000" />
</template>
```

You can also listen for when hydration happens with the `@hydrated` event:

```vue
<LazyComponent hydrate-on-visible @hydrated="onComponentHydrated" />
```

Learn more about lazy hydration in [our components documentation](/docs/guide/directory-structure/components#delayed-or-lazy-hydration).

## 🧩 Advanced Pages Configuration

You can now fine-tune which files Nuxt scans for pages ([#31090](https://github.com/nuxt/nuxt/pull/31090)), giving you more control over your project structure:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  pages: {
    // Filter specific files or directories
    pattern: ['**/*.vue'],
  }
})
```

## 🔍 Enhanced Debugging

We've made debugging with the `debug` option more flexible! Now you can enable just the debug logs you need ([#30578](https://github.com/nuxt/nuxt/pull/30578)):

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  debug: {
    // Enable specific debugging features
    templates: true,
    modules: true,
    watchers: true,
    hooks: {
      client: true,
      server: true,
    },
    nitro: true,
    router: true,
    hydration: true,
  }
})
```

Or keep it simple with `debug: true` to enable all these debugging features.

## 🎨 Decorators Support

For the decorator fans out there (whoever you are!), we've added experimental support ([#27672](https://github.com/nuxt/nuxt/pull/27672)). As with all experimental features, feedback is much appreciated.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    decorators: true
  }
})
```

```ts
function something (_method: () => unknown) {
  return () => 'decorated'
}

class SomeClass {
  @something
  public someMethod () {
    return 'initial'
  }
}

const value = new SomeClass().someMethod()
// returns 'decorated'
```

## 📛 Named Layer Aliases

It's been much requested, and it's here! Auto-scanned local layers (from your `~~/layers` directory) now automatically create aliases. You can access your `~~/layers/test` layer via `#layers/test` ([#30948](https://github.com/nuxt/nuxt/pull/30948)) - no configuration needed.

If you want named aliases for other layers, you can add a name to your layer configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  $meta: {
    name: 'example-layer',
  },
})
```

This creates the alias `#layers/example-layer` pointing to your layer - making imports cleaner and more intuitive.

## 🧪 Error Handling Improvements

We've greatly improved error messages and source tracking ([#31144](https://github.com/nuxt/nuxt/pull/31144)):

1. Better warnings for undefined `useAsyncData` calls with precise file location information
2. Error pages now appear correctly on island page errors ([#31081](https://github.com/nuxt/nuxt/pull/31081))

Plus, we're now using Nitro's beautiful error handling (powered by [youch](https://github.com/poppinss/youch)) to provide more helpful error messages in the terminal, complete with stacktrace support.

Nitro now also automatically applies source maps without requiring extra Node options, and we set appropriate security headers when rendering error pages.

## 📦 Module Development Improvements

For module authors, we've added the ability to augment Nitro types with `addTypeTemplate` ([#31079](https://github.com/nuxt/nuxt/pull/31079)):

```ts
// Inside your Nuxt module
export default defineNuxtModule({
  setup(options, nuxt) {
    addTypeTemplate({
      filename: 'types/my-module.d.ts',
      getContents: () => `
        declare module 'nitropack' {
          interface NitroRouteConfig {
            myCustomOption?: boolean
          }
        }
      `
    }, { nitro: true })
  }
})
```

## ⚙️ Nitro v2.11 Upgrade

We've upgraded to Nitro v2.11. There are so many improvements - more than I can cover in these brief release notes.

👉 Check out all the details in the [Nitro v2.11.0 release notes](https://github.com/nitrojs/nitro/releases/tag/v2.11.0).

## 📦 New `unjs` Major Versions

This release includes several major version upgrades from the unjs ecosystem, focused on performance and smaller bundle sizes through ESM-only distributions:

- unenv upgraded to v2 (full rewrite)
- db0 upgraded to v0.3 (ESM-only, native node:sql, improvements)
- ohash upgraded to v2 (ESM-only, native node:crypto support, much faster)
- untyped upgraded to v2 (ESM-only, smaller install size)
- unimport upgraded to v4 (improvements)
- c12 upgraded to v3 (ESM-only)
- pathe upgraded to v2 (ESM-only)
- cookie-es upgraded to v2 (ESM-only)
- esbuild upgraded to v0.25
- chokidar upgraded to v4

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --dedupe
```

This refreshes your lockfile and pulls in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

## Full release notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.16.0">

Read the full release notes of Nuxt `v3.16.0`.

</read-more>

A huge thank you to everyone who's been a part of this release. ❤️

I'm aware there have been lots of very significant changes in this release - please don't hesitate to let us know if you have any feedback or issues! 🙏

---

# Source: https://nuxt.com/raw/blog/v3-17.md

# Nuxt 3.17

> Nuxt 3.17 is out - bringing a major reworking of the async data layer, a new built-in component, better warnings, and performance improvements!

## 📊 Data Fetching Improvements

A major reorganization of Nuxt's data fetching layer brings significant improvements to `useAsyncData` and `useFetch`.

Although we have aimed to maintain backward compatibility and put breaking changes behind the `experimental.granularCachedData` flag (disabled by default), we recommend testing your application thoroughly after upgrading. You can also disable `experimental.purgeCachedData` to revert to the previous behavior if you are relying on cached data being available indefinitely after components using `useAsyncData` are unmounted.

<read-more target="_blank" to="https://github.com/nuxt/nuxt/pull/31373">

Read the original PR for full details.

</read-more>

### Consistent Data Across Components

All calls to `useAsyncData` or `useFetch` with the same key now share the underlying refs, ensuring consistency across your application:

```vue
<!-- ComponentA.vue -->
<script setup>
const { data: users, pending } = useAsyncData('users', fetchUsers)
</script>

<!-- ComponentB.vue -->
<script setup>
// This will reference the same data state as ComponentA
const { data: users, status } = useAsyncData('users', fetchUsers)
// When either component refreshes the data, both will update consistently
</script>
```

This solves various issues where components could have inconsistent data states.

### Reactive Keys

You can now use computed refs, plain refs, or getter functions as keys:

```ts
const userId = ref('123')
const { data: user } = useAsyncData(
  computed(() => `user-${userId.value}`),
  () => fetchUser(userId.value)
)

// Changing the userId will automatically trigger a new data fetch
// and clean up the old data if no other components are using it
userId.value = '456'
```

### Optimized Data Refetching

Multiple components watching the same data source will now trigger only a single data fetch when dependencies change:

```ts
// In multiple components:
const { data } = useAsyncData(
  'users', 
  () => $fetch(`/api/users?page=${route.query.page}`),
  { watch: [() => route.query.page] }
)

// When route.query.page changes, only one fetch operation will occur
// All components using this key will update simultaneously
```

## 🎭 Built-In Nuxt Components

### `<NuxtTime>` - A new component for safe time display

We've added a new `<NuxtTime>` component for SSR-safe time display, which resolves hydration mismatches when working with dates ([#31876](https://github.com/nuxt/nuxt/pull/31876)):

```vue
<template>
  <NuxtTime :datetime="Date.now()" />
</template>
```

The component accepts multiple time formats and gracefully handles both client and server rendering.

### Enhanced `<NuxtErrorBoundary>`

The `<NuxtErrorBoundary>` component has been converted to a Single File Component and now exposes `error` and `clearError` from the component - as well as in the error slot types, giving you greater ability to handle errors in your templates and via `useTemplateRef` ([#31847](https://github.com/nuxt/nuxt/pull/31847)):

```vue
<NuxtErrorBoundary @error="handleError">
  <template #error="{ error, clearError }">
    <div>
      <p>{{ error.message }}</p>
      <button @click="clearError">Try again</button>
    </div>
  </template>
  
  <!-- Content that might error -->
  <MyComponent />
</NuxtErrorBoundary>
```

## 🔗 Router Improvements

`<NuxtLink>` now accepts a `trailingSlash` prop, giving you more control over URL formatting ([#31820](https://github.com/nuxt/nuxt/pull/31820)):

```vue
<NuxtLink to="/about" trailing-slash>About</NuxtLink>
<!-- Will render <a href="/about/"> -->
```

## 🔄 Loading Indicator Customization

You can now customize the loading indicator with new props directly on the component ([#31532](https://github.com/nuxt/nuxt/pull/31532)):

- `hideDelay`: Controls how long to wait before hiding the loading bar
- `resetDelay`: Controls how long to wait before resetting loading indicator state

```vue
<template>
  <NuxtLoadingIndicator :hide-delay="500" :reset-delay="300" />
</template>
```

## 📚 Documentation as a Package

The Nuxt documentation is now available as an npm package! You can install `@nuxt/docs` to access the raw markdown and YAML content used to build the documentation website ([#31353](https://github.com/nuxt/nuxt/pull/31353)).

## 💻 Developer Experience Improvements

We've added several warnings to help catch common mistakes:

- Warning when server components don't have a root element [#31365](https://github.com/nuxt/nuxt/pull/31365)
- Warning when using the reserved `runtimeConfig.app` namespace [#31774](https://github.com/nuxt/nuxt/pull/31774)
- Warning when core auto-import presets are overridden [#29971](https://github.com/nuxt/nuxt/pull/29971)
- Error when `definePageMeta` is used more than once in a file [#31634](https://github.com/nuxt/nuxt/pull/31634)

## 🔌 Enhanced Module Development

Module authors will be happy to know:

- A new `experimental.enforceModuleCompatibility` allows Nuxt to throw an error when a module is loaded that isn't compatible with it ([#31657](https://github.com/nuxt/nuxt/pull/31657)). It will be enabled by default in Nuxt v4.
- You can now automatically register every component exported via named exports from a file with `addComponentExports` [#27155](https://github.com/nuxt/nuxt/pull/27155)

## 🔥 Performance Improvements

Several performance improvements have been made:

- Switched to `tinyglobby` for faster file globbing [#31668](https://github.com/nuxt/nuxt/pull/31668)
- Excluded `.data` directory from type-checking for faster builds [#31738](https://github.com/nuxt/nuxt/pull/31738)
- Improved tree-shaking by hoisting the `purgeCachedData` check [#31785](https://github.com/nuxt/nuxt/pull/31785)

## ✅ Upgrading

Our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --dedupe
```

This refreshes your lockfile and pulls in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

## Full release notes

<read-more target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.17.0" icon="i-simple-icons-github">

Read the full release notes of Nuxt `v3.17.0`.

</read-more>

A huge thank you to everyone who's been a part of this release. ❤️

---

# Source: https://nuxt.com/raw/blog/v3-18.md

# Nuxt 3.18

> Nuxt 3.18 is out - bringing v4 features to v3, improved accessibility, better browser dev tooling integration, and performance enhancements!

## 🧪 Lazy Hydration Macros

Building on the delayed hydration support from v3.16, we now support **lazy hydration macros** ([#31192](https://github.com/nuxt/nuxt/pull/31192))! These provide a more ergonomic way to control component hydration:

```vue
<script setup lang="ts">
const LazyHydrationMyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./components/MyComponent.vue')
)
</script>
<template>
  <div>
    <!-- 
      Hydration will be triggered when
      the element(s) is 100px away from entering the viewport.
    -->
    <LazyHydrationMyComponent :hydrate-on-visible="{ rootMargin: '100px' }" />
  </div>
</template>
```

These macros make it possible to use Nuxt's lazy hydration utilities alongside explicit component imports.

## ♿️ Accessibility Improvements

We've enhanced accessibility by including `<NuxtRouteAnnouncer>` in the built-in `app.vue` ([#32621](https://github.com/nuxt/nuxt/pull/32621)). This means page changes will be announced to screen readers, making navigation more accessible for users with visual impairments. (This only applies if you do not have an `app.vue` in your project. If you do, please keep `<NuxtRouteAnnouncer>` in your `app.vue`!)

## 🛠️ Enhanced Development Experience

### Chrome DevTools Workspace Integration

We've added **Chrome DevTools workspace integration** ([#32084](https://github.com/nuxt/nuxt/pull/32084)), allowing you to edit your Nuxt source files directly from Chrome DevTools. This creates a better debugging experience where changes made in DevTools are reflected in your actual source files.

### Better Component Type Safety

Component type safety has been improved with:

- **Typed slots for <ClientOnly> and <DevOnly>** ([#32707](https://github.com/nuxt/nuxt/pull/32707)) - better IntelliSense and error checking
- **Exported <NuxtTime> prop types** ([#32547](https://github.com/nuxt/nuxt/pull/32547)) - easier to extend and customize

### New Auto-Import: `onWatcherCleanup`

The `onWatcherCleanup` function from `vue` is now available as an auto-import ([#32396](https://github.com/nuxt/nuxt/pull/32396)), making it easier to clean up watchers and prevent memory leaks:

```ts
const { data } = useAsyncData('users', fetchUsers)

watch(data, (newData) => {
  const interval = setInterval(() => {
    // Some periodic task
  }, 1000)
  
  // Clean up when the watcher is stopped
  onWatcherCleanup(() => {
    clearInterval(interval)
  })
})
```

## 📊 Observability Enhancements

Page routes are now **exposed to Nitro for observability** ([#32617](https://github.com/nuxt/nuxt/pull/32617)), enabling better monitoring and analytics integration with supported platforms. This allows observability tools to track page-level metrics more effectively.

## 🔧 Module Development Improvements

Module authors get several quality-of-life improvements:

### Simplified Server Imports

The `addServerImports` kit utility now **supports single imports** ([#32289](https://github.com/nuxt/nuxt/pull/32289)), making it easier to add individual server utilities:

```ts
// Before: had to wrap in array
addServerImports([{ from: 'my-package', name: 'myUtility' }])

// Now: can pass directly
addServerImports({ from: 'my-package', name: 'myUtility' })
```

### TypeScript Configuration

Modules can now **add to typescript.hoist** ([#32601](https://github.com/nuxt/nuxt/pull/32601)), giving them more control over TypeScript configuration and type generation.

## ⚡️ Performance Improvements

We've made several performance optimizations:

- **Improved Vite-node communication** via internal socket ([#32417](https://github.com/nuxt/nuxt/pull/32417)) for faster development builds
- **Migration to oxc-walker** ([#32250](https://github.com/nuxt/nuxt/pull/32250)) and **oxc for onPrehydrate transforms** ([#32045](https://github.com/nuxt/nuxt/pull/32045)) for faster code transformations

## 🐛 Bug Fixes

This release also includes several important fixes:

- **Improved data fetching**: When computed keys change, old data is now properly retained ([#32616](https://github.com/nuxt/nuxt/pull/32616))
- **Better scroll behavior**: `scrollBehaviorType` is now only used for hash scrolling ([#32622](https://github.com/nuxt/nuxt/pull/32622))
- **Fixed directory aliases**: Added trailing slashes to some directory aliases for better consistency ([#32755](https://github.com/nuxt/nuxt/pull/32755))

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi@latest upgrade --dedupe
```

This refreshes your lockfile and pulls in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

## Full release notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.18.0">

Read the full release notes of Nuxt `v3.18.0`.

</read-more>

A huge thank you to everyone who's been a part of this release. Over the next six months, we'll continue backporting compatible v4 features and bug fixes, so please keep the feedback coming! ❤️

---

# Source: https://nuxt.com/raw/blog/v3-3.md

# Nuxt 3.3

> The 3.3.0 is a minor (feature) release with lots of performance and DX improvements, bug fixes and new features to play with.

## ✨ Local module development DX

We've landed a raft of changes to enable local modules and improve DX.

We now auto-scan your [`~/modules`](/docs/guide/directory-structure/modules) folder and register top level files there as modules in your project ([#19394](https://github.com/nuxt/nuxt/pull/19394)).

When these files are changed, we'll automatically restart the nuxt server.

```diff
export default defineNuxtConfig({
  modules: [
    '@nuxtjs/tailwindcss',
-   '~/modules/purge-comments'
  ]
})
```

We also now expose `nuxt/kit` for easy access to kit composables in your local project without having to install `@nuxt/kit` ([#19422](https://github.com/nuxt/nuxt/pull/19422)).

[Read the documentation about local modules](/docs/guide/directory-structure/modules).

## ♻️ Restarting Nuxt

You can add files to the `watch` array to automatically restart the server ([#19530](https://github.com/nuxt/nuxt/pull/19530)). This is likely to be particularly useful for module authors. You can also trigger a restart of the Nuxt server with the new `restart` hook ([#19084](https://github.com/nuxt/nuxt/pull/19084)).

## 🔥 Performance improvements

We've increased static asset maxAge to 1 year as a matter of best practice ([#19335](https://github.com/nuxt/nuxt/pull/19335)), and support tree-shaking more of your build ([#19508](https://github.com/nuxt/nuxt/pull/19508)).

![nuxt-performance-improvements](/assets/blog/nuxt-performance-improvements.png)

We also now support preloading [`<NuxtLink>`](/docs/api/components/nuxt-link) with a route in object-syntax ([#19120](https://github.com/nuxt/nuxt/pull/19120)):

```html
<NuxtLink :to="{ name: 'home', query: { year: '2023' } }">Home</NuxtLink>
```

We also track how long it takes each module you use to perform its setup, and warn if it takes too long. You can see all these values by running your dev server with `DEBUG=1` ([#18648](https://github.com/nuxt/nuxt/pull/18648)).

```sh
DEBUG=1 npx nuxt dev
ℹ Module pages took 1.5ms to setup.
ℹ Module meta took 3.15ms to setup
ℹ Module components took 4.5ms to setup.
...
```

You can also opt-in to some of Nuxt's internal optimisations by configuring composables to be treeshaken in a particular environment ([#19383](https://github.com/nuxt/nuxt/pull/19383)) or to have magic keys automatically injected ([#19490](https://github.com/nuxt/nuxt/pull/19490)).

## 🐛 Error handling

We now handle chunk errors by default ([#19086](https://github.com/nuxt/nuxt/pull/19086)), meaning if your site updates with a redeploy, **we automatically handle reloading it on navigation**.

To disable this behavior, set `experimental.emitRouteChunkError` option to `'manual'` and handle it yourself with the new [`reloadNuxtApp`](https://nuxt.com/docs/api/utils/reload-nuxt-app) composable. Learn more how we implemented in our [chunk-reload.client.ts plugin](https://github.com/nuxt/nuxt/blob/main/packages/nuxt/src/app/plugins/chunk-reload.client.ts).

You can also set `experimental.restoreState` to preserve some of your app state across reloads:

```ts [nuxt.config.ts]
defineNuxtConfig({
  experimental: {
    restoreState: true
  }
})
```

We also have a new experimental error handling component: [`<NuxtClientFallback>`](/docs/api/components/nuxt-client-fallback) ([#8216](https://github.com/nuxt/framework/pull/8216)) which can capture errors rendering on server, replace them with fallback content, and granularly trigger rerendering the part with an error on the client. This can be enabled with `experimental.clientFallback` - feedback very welcome!

## ⚡️ Head improvements

We've migrated to use [unhead](https://github.com/unjs/unhead) directly ([#19519](https://github.com/nuxt/nuxt/pull/19519)) - and automatically tree-shake server-only head composables like `useServerHead` from your client build ([#19576](https://github.com/nuxt/nuxt/pull/19576)), meaning you can have great SEO without needing to include meta tag logic that's relevant only for crawlers in your client build.

There's also a new [`useHeadSafe`](/docs/api/composables/use-head-safe) composable that handles sanitising untrusted user input ([#19548](https://github.com/nuxt/nuxt/pull/19548)).

## 🪵 Better logging in browser DevTools

Working with the Chrome DevTools team, we've landed a couple of features across the unjs + Nuxt ecosystem meaning we now have first-class support for hiding Nuxt internal stack traces from logs in your (Chromium-based, for now) browser [#19243](https://github.com/nuxt/nuxt/pull/19243). We also landed a couple of improvements with stacktraces involving Nuxt hooks ([unjs/hookable#69](https://github.com/unjs/hookable/pull/69) and [unjs/hookable#68](https://github.com/unjs/hookable/pull/68)) implementing [`console.createTask`](https://developer.chrome.com/blog/devtools-modern-web-debugging/#linked-stack-traces).

<table>
<thead>
  <tr>
    <th>
      Before
    </th>
    
    <th>
      After
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <img width="529" alt="before-nuxt-console-improvements" src="https://user-images.githubusercontent.com/28706372/220933126-56d9a0e5-e846-4958-a40a-e528a48bcb32.png" />
    </td>
    
    <td>
      <img width="534" alt="after-nuxt-console-improvements" src="https://user-images.githubusercontent.com/28706372/220932932-932f193b-59a6-4385-8796-a62dcfd59c20.png" />
    </td>
  </tr>
</tbody>
</table>

## 💪 Type improvements

Types for server API routes are now more correct - with non-serialisable types stripped out of the return type ([unjs/nitro#1002](https://github.com/unjs/nitro/pull/1002)).

We also now type more of `NuxtApp` and correctly type unknown injections for greater type-safety ([#19643](https://github.com/nuxt/nuxt/pull/19643)).

And if you were struggling with correct types when using `transform` + `default` with Nuxt data fetching composables, fear no more - we now infer the types correctly ([#19487](https://github.com/nuxt/nuxt/pull/19487)).

## ⚗️ Nitro enhancements

This release comes with Nitro v2.3, which brings lots of improvements of its own. Check out [the release](https://github.com/unjs/nitro/releases/tag/v2.3.0) for more info.

We now support [`useAppConfig`](/docs/api/composables/use-app-config) in nitro server routes ([#19489](https://github.com/nuxt/nuxt/pull/19489)) - a long-awaited change. Now [`useAppConfig`](/docs/api/composables/use-app-config) is consistently available throughout your app for non-runtime configuration from layers, modules, etc.

We've also added a `nitro:build:public-assets` hook to allow modifying assets output from nitro's prerender/build phase ([#19638](https://github.com/nuxt/nuxt/pull/19638)).

## 🛠️ Build changes

As part of moving towards [first-class support for PNP and pnpm support without `--shamefully-hoist`](https://github.com/nuxt/nuxt/issues/14146), we've dropped support for some internal (deprecated) utilities using CJS resolve patterns ([#19537](https://github.com/nuxt/nuxt/pull/19537) and [#19608](https://github.com/nuxt/nuxt/pull/19608)).

We also now resolve dependencies like `nuxt`, `@nuxt/kit` and more using ESM search-paths. We'll be keeping a close eye on this.

We're also preparing the groundwork for support of new TypeScript Node16 module resolution ([#19606](https://github.com/nuxt/nuxt/issues/19606)), and as part of this have changed the format of our runtime output (using `.js` instead of `.mjs` extensions, providing `types` fields for subpath exports, and more).

## 🗺️ Custom config schema (advanced)

We've been testing out an experimental feature to allow modules and users to extend the Nuxt config schema ([#15592](https://github.com/nuxt/nuxt/issues/15592)), and we've now enabled this by default ([#19172](https://github.com/nuxt/nuxt/pull/19172)). We expect this will be particularly useful for module and layer/theme authors, and should result in some nicer DX for their users.

## Changelog

See the full changelog by [comparing the changes](https://github.com/nuxt/nuxt/compare/v3.2.3...v3.3.0) or checkout the [release on GitHub](https://github.com/nuxt/nuxt/releases/tag/v3.3.0).

We would like to thank all the 28 contributors who helped on this release 💚

---

# Source: https://nuxt.com/raw/blog/v3-4.md

# Nuxt 3.4

> Nuxt 3.4.0 is the latest release of Nuxt 3, bringing exciting new features, including support for the View Transitions API, transferring rich JavaScript payloads from server to client - and much more.

## 🪄 View Transitions API Support

<article-video cloudinary="v1681229056/nuxt3/nuxt-view-transitions_cruvma">



</article-video>

You can check a demo on [https://nuxt-view-transitions.surge.sh](https://nuxt-view-transitions.surge.sh) and the [source on StackBlitz](https://stackblitz.com/edit/nuxt-view-transitions).

You may have noticed that Chromium-based browsers now ship a new web platform API: the [**View Transitions API**](https://developer.chrome.com/docs/web-platform/view-transitions/). This is an exciting new ability for native browser transitions which (among other things) have the ability to transition between unrelated elements on different pages.

Nuxt now ships with an experimental implementation, which will be under active development during the v3.4 release cycle. See the known issues in the [linked PR](https://github.com/nuxt/nuxt/pull/20092).

```ts
export default defineNuxtConfig({
  experimental: {
    viewTransition: true
  }
})
```

## ✨ Payload Enhancements

We've merged a **significant change to how Nuxt handles payloads** (under an experimental flag). Payloads are used to send data from the server to the client when doing server-side rendering and avoid double data-fetching during the hydration phase.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    renderJsonPayloads: true
  }
})
```

With this new option enabled, this now means that **various rich JS types are supported out-of-the-box**: regular expressions, dates, Map and Set and BigInt as well as NuxtError - and Vue-specific objects like `ref`, `reactive`, `shallowRef` and `shallowReactive`.

You can find [an example](https://github.com/nuxt/nuxt/blob/main/test/fixtures/basic/pages/json-payload.vue) in our test suite.

This is all possible due to [Rich-Harris/devalue#58](https://github.com/Rich-Harris/devalue/pull/58). For a long time, Nuxt has been using our own fork of devalue owing to issues serialising Errors and other non-POJO objects, but we now have transitioned back to the original.

You can even register your own custom types with a new object-syntax Nuxt plugin:

```ts [plugins/custom-payload-type.ts]
export default definePayloadPlugin(() => {
  definePayloadReducer('BlinkingText', data => data === '<original-blink>' && '_')
  definePayloadReviver('BlinkingText', () => '<revivified-blink>')
})
```

You can read more about how this works [here](https://github.com/rich-harris/devalue#custom-types).

**Note**: this only affects payloads of the Nuxt app, that is, data stored within `useState`, returned from `useAsyncData` or manually injected via `nuxtApp.payload`. It does not affect data fetched from Nitro server routes via `$fetch` or `useFetch` although this is one area I am keen to explore further.

Preliminary testing shows a significant speed-up: **25% faster in total server response time** for a very minimal app with a large JSON payload, but I'd urge you to run your own tests and share the results with us.

As mentioned, we're merging this behind a flag so we can test this broadly and gather feedback on the new approach. The most significant potential change is that the payload is now no longer available on `window.__NUXT__` immediately. Instead, we now need to initialise the Nuxt app to parse the payload so any code that accesses `__NUXT__` will need to be run in a plugin or later in the Nuxt app lifecycle. Please feel free to raise an issue if you foresee or encounter issues in your projects.

## 🎁 Object-syntax Nuxt plugins

We now support object-syntax Nuxt plugins for better control over plugin *order* and easier registration of hooks.

```ts [plugins/my-plugin.ts]
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre', // or 'post'
  async setup (nuxtApp) {
    // this is the equivalent of a normal functional plugin
  },
  hooks: {
    // You can directly register Nuxt app hooks here
    'app:created'() {
      const nuxtApp = useNuxtApp()
      //
    }
  }
})
```

In future we plan to enable build optimizations based on the metadata you pass in your Nuxt plugins.

## 🛠️ Easier Devtools Configuration

It's even easier to enable Nuxt DevTools in your project: just set `devtools: true` in your `nuxt.config.ts` file to enable devtools.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  devtools: true
})
```

If it's not already installed, Nuxt will prompt to install it locally. This means you no longer need to have Nuxt DevTools enabled globally.

**Note**: the DevTools is still experimental and under active development, so do be prepared for occasional unexpected behaviour, and please report issues directly to [https://github.com/nuxt/devtools](https://github.com/nuxt/devtools) 🙏

## 📚 Layers Improvements

We now support [transforming `~`/`~~`/`@`/`@@` aliases within layers](https://github.com/nuxt/nuxt/pull/19986), meaning you now no longer need to use relative paths when importing within layers.

This should mean it is much easier to use a 'normal' Nuxt project as a [layer](https://nuxt.com/docs/getting-started/layers#layers) without needing to specially write it as one.

## 🧸 Better Context Transforms

We [now transform certain keys](https://github.com/nuxt/nuxt/pull/20182) of `definePageMeta` and `defineNuxtComponent` which means you should have fewer issues with a missing Nuxt instance. This includes support accessing the Nuxt instance after an `await` within `asyncData` and `setup` functions for those still using the Options API. And you no longer need to wrap `middleware` and `validate` with `defineNuxtRouteMiddleware` when using async functions.

## ♻️ Ecosystem Updates

As usual, this release will pull in upstream improvements, including the new [Consola v3](https://github.com/unjs/consola) and [Nitropack v2.3.3](https://github.com/unjs/nitro) (a new minor is expected shortly).

## 🚨 'Breaking fixes'

We've also taken the opportunity to do some cleanup in this minor release.

1. Previously it was possible to pass the `x-nuxt-no-ssr` header (undocumented) to force SPA rendering. We've now disabled this behaviour by default but you can get it back by setting `experimental.respectNoSSRHeader` to true. Alternatively, you can set `event.context.nuxt.noSSR` on the server to force SPA rendering.
2. We've [removed the (deprecated) `#head` alias](https://github.com/nuxt/nuxt/pull/20111) and also disabled the [polyfill for `@vueuse/head` behaviour](https://github.com/nuxt/nuxt/pull/20131) by default. (It can still be enabled with `experimental.polyfillVueUseHead`.)
3. We've [removed the (deprecated) `experimental.viteNode` option](https://github.com/nuxt/nuxt/pull/20112). It can be configured instead with `vite.devBundler`.
4. We've [deprecated accessing public runtime config without the `public` key](https://github.com/nuxt/nuxt/pull/20082). This was an undocument compatibility measure with Nuxt 2 and we plan to remove it entirely in v3.5.
5. To fix a bug with our vue-router integration, we now generate a slightly different path matching syntax. If you were relying on the exact path generated, have a look at [https://github.com/nuxt/nuxt/pull/19902](https://github.com/nuxt/nuxt/pull/19902) for more information.

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

---

# Source: https://nuxt.com/raw/blog/v3-5.md

# Nuxt 3.5

> Nuxt 3.5.0 is out, bringing Vue 3.3, new defaults, interactive server components, typed pages, environment config - and much more.

## ⚡️ Vue 3.3 released

Vue 3.3 has been released, with lots of exciting features, particularly around type support.

- new `defineOptions` macro
- 'generic' components
- typed slots and using external types in defineProps
- ... and more

This also brings a significant improvement to data fetching when navigating between nested pages ([#20777](https://github.com/nuxt/nuxt/pull/20777)), thanks to [@antfu](https://github.com/antfu) and [@baiwusanyu-c](https://github.com/baiwusanyu-c).

Read **the full release announcement** for more details.

### 🙌 Nitropack v2.4

We've been working on lots of improvements to Nitro and these have landed already in Nitro v2.4 - you may already have this upgrade, which contains a lot of bug fixes, updates to the module worker format for Cloudflare, Vercel KV support and more.

One note: if you're deploying to Vercel or Netlify and want to benefit from incremental static regeneration, you should now update your route rules:

```diff
routeRules: {
--  '/blog/**': { swr: 3000 },
++  '/blog/**': { isr: 3000 },
}
```

Read **the full release notes**.

### 💖 Rich JSON payloads

**Rich JSON payload serialisation** is now enabled by default ([#19205](https://github.com/nuxt/nuxt/pull/19205), [#20770](https://github.com/nuxt/nuxt/pull/20770)). This is both faster and allows serialising complex objects in the payload passed from the Nuxt server to client (and also when extracting payload data for prerendered sites).

This now means that **various rich JS types are supported out-of-the-box**: regular expressions, dates, Map and Set and BigInt as well as NuxtError - and Vue-specific objects like `ref`, `reactive`, `shallowRef` and `shallowReactive`.

You can find [an example](https://github.com/nuxt/nuxt/blob/main/test/fixtures/basic/pages/json-payload.vue) in our test suite.

This is all possible due to [Rich-Harris/devalue#58](https://github.com/Rich-Harris/devalue/pull/58). For a long time, Nuxt has been using our own fork of devalue owing to issues serialising Errors and other non-POJO objects, but we now have transitioned back to the original.

You can even register your own custom types with a new object-syntax Nuxt plugin:

```ts [plugins/custom-payload-type.ts]
export default definePayloadPlugin(() => {
  definePayloadReducer('BlinkingText', data => data === '<original-blink>' && '_')
  definePayloadReviver('BlinkingText', () => '<revivified-blink>')
})
```

You can read more about how this works [here](https://github.com/rich-harris/devalue#custom-types).

## 🛝 Interactive server components

This feature should be considered highly experimental, but thanks to some great work from @huang-julien we now support interactive content within server components via *slots* ([#20284](https://github.com/nuxt/nuxt/pull/20284)).

You can follow the server component roadmap at [#19772](https://github.com/nuxt/nuxt/issues/19772).

## ⏰ Environment config

You can now configure fully typed, per-environment overrides in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  $production: {
    routeRules: {
      '/**': { isr: true }
    }
  },
  $development: {
    //
  }
})
```

If you're authoring layers, you can also use the `$meta` key to provide metadata that you or the consumers of your layer might use.

Read more [about per-environment overrides](https://github.com/nuxt/nuxt/pull/20329).

## 💪 Fully typed pages

You can benefit from fully typed routing within your Nuxt app via this experimental integration with [unplugin-vue-router](https://github.com/posva/unplugin-vue-router) - thanks to some great work from [@posva](https://github.com/posva)!

Out of the box, this will enable typed usage of [`navigateTo`](/docs/api/utils/navigate-to), [`<NuxtLink>`](/docs/api/components/nuxt-link), `router.push()` and more.

You can even get typed params within a page by using `const route = useRoute('route-name')`.

Enable this feature directly in your `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    typedPages: true
  }
})
```

## 🔎 'Bundler' module resolution

We now have full support within Nuxt for the `bundler` strategy of [module resolution](https://www.typescriptlang.org/docs/handbook/module-resolution.html).

We would recommend adopting this if possible. It has type support for subpath exports, for example, but more exactly matches the behaviour of build tools like Vite and Nuxt than `Node16` resolution.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        moduleResolution: 'bundler'
      }
    }
  }
})
```

This turns on TypeScript's ability to 'follow' Node subpath exports. For example, if a library has a subpath export like `mylib/path` that is mapped to `mylib/dist/path.mjs` then the types for this can be pulled in from `mylib/dist/path.d.ts` rather than requiring the library author to create `mylib/path.d.ts`.

## ⚗️ Separate server types

We plan to improve clarity within your IDE between the 'nitro' and 'vue' part of your app, we've shipped the first part of this via a separate generated `tsconfig.json` for your [`~/server`](/docs/guide/directory-structure/server) directory ([#20559](https://github.com/nuxt/nuxt/pull/20559)).

You can use by adding an additional `~/server/tsconfig.json` with the following content:

```json
{
  "extends": "../.nuxt/tsconfig.server.json"
}
```

Although right now these values won't be respected when type checking (`nuxi typecheck`), you should get better type hints in your IDE.

## 💀 Deprecations

Although we have not typed or documented the `build.extend` hook from Nuxt 2, we have been calling it within the webpack builder. We are now explicitly deprecating this and will remove it in a future minor version.

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## 📃 Full changelog

Read the full release note on [https://github.com/nuxt/nuxt/releases/tag/v3.5.0](https://github.com/nuxt/nuxt/releases/tag/v3.5.0)

---

# Source: https://nuxt.com/raw/blog/v3-6.md

# Nuxt 3.6

> Nuxt 3.6 is out, bringing performance improvements, fully static server components, better style inlining, static presets, increased type safety - and much more.

## ![SPA loading indicator](/assets/design-kit/icon-green.svg)  SPA loading indicator

If your site is served with `ssr: false` or you have disabled server-rendering on some of your pages, you might be particularly interested in the new [built-in SPA loading indicator](https://github.com/nuxt/nuxt/pull/21640).

You can now place an HTML file in `~/app/spa-loading-template.html` with some HTML you would like to use to render a loading screen that will be rendered until your app is hydrated on these pages.

<note>

In Nuxt v4 (or with `compatibilityMode: 4`), this path is now `~/spa-loading-template.html`.

</note>

👉 **By default an animated Nuxt icon is rendered**. You can completely disable this indicator by setting `spaLoadingTemplate: false` in your nuxt configuration file.

## ⚡️ Performance improvements

The first thing that happens when your app is hydrated is that your plugins run, and so we now perform [build-time optimisations on your plugins](https://github.com/nuxt/nuxt/pull/21611), meaning they do not need to be normalised or reordered at runtime.

We also include your error component JS in your main entrypoint, meaning that if an error occurs when a user has no connectivity, you can still handle it with your `~/error.vue`. (This also should decrease your total bundle size.)

👉 Compared to Nuxt 3.5.3, the minimal client bundle has decreased by ~0.7kB. Let's keep this up!

## 🔥 Fully static server components

It has been possible to use server components on static pages, but until now they would increase the payload size of your application. That is no longer true. We now store [rendered server components as separate files, which are preloaded before navigation](https://github.com/nuxt/nuxt/pull/21461).

👉 **This does rely on the new, richer JSON payload format**, so make sure you have not disabled this by setting `experimental.renderJsonPayloads` to false.

## 🎨 Better style inlining

If you're monitoring your metrics closely and have not turned off `experimental.inlineSSRStyles`, you should see more CSS inlined in your page, and a significantly external CSS file. We're now [better at deduplicating global CSS](https://github.com/nuxt/nuxt/pull/21573), particularly added by libraries like tailwind or unocss.

## 🎬 Animation controls

To give you more fine-grained control over your page/layout components, for example to create custom transitions with GSAP or other libraries, we now allow you to set [`pageRef` on `<NuxtPage>`](https://github.com/nuxt/nuxt/pull/19403) and [`layoutRef` on `<NuxtLayout>`](https://github.com/nuxt/nuxt/pull/19465). These will get passed through to the underlying DOM elements.

## ✨ Automatic 'static' preset detection

Up to now, running `nuxt generate` produced the same output on every deployment provider, but with Nuxt 3.6 we now enable [static provider presets](https://github.com/nuxt/nuxt/pull/21655) automatically. That means if you are deploying a static build (produced with `nuxt generate`) to a supported provider (currently vercel and netlify with cloudflare and github pages coming soon) we'll prerender your pages with special support for that provider.

This means we can configure any route rules (redirects/headers/etc) that do not require a server function. So you should get the best of both worlds when deploying a site that doesn't require runtime SSR. It also unblocks use of [Nuxt Image](https://github.com/nuxt/image) on Vercel (with more potential for automatic provider integration coming soon).

## 💪 Increased type safety

We now have better support for server-specific `#imports` and augmentations if you are using the new `~/server/tsconfig.json` we shipped in Nuxt 3.5. So when importing from `#imports` in your server directory, you'll get IDE auto-completion for the right import locations in Nitro, and won't see Vue auto-imports like `useFetch` that are unavailable within your server routes.

You should now also have [type support for runtime Nitro hooks](https://github.com/nuxt/nuxt/pull/21666).

Finally, we have [removed more locations where objects had a default `any` type](https://github.com/nuxt/nuxt/pull/21700). This should improve type safety within Nuxt in a number of locations where unspecified types fell back to any:

- `RuntimeConfig`
- `PageMeta`
- `NuxtApp['payload']` (accessible now from `NuxtPayload` interface)
- `ModuleMeta`

You can find out more about how to [update your code](https://github.com/nuxt/nuxt/pull/21700) if this affects you in the original PR.

## ⚗️ Nitro 2.5 built-in

This release ships with new Nitro 2.5, which has a [whole list of exciting improvements](https://github.com/unjs/nitro/releases/tag/v2.5.0) that are worth checking out.

Of particular note is experimental support for streaming, which is also enabled by a [couple of changes](https://github.com/nuxt/nuxt/pull/21665) in Nuxt itself.

## 🛠️ New tools for module authors

This release brings a number of utilities for modules authors to easily [add type templates](https://github.com/nuxt/nuxt/pull/21331) and [assert compatibility](https://github.com/nuxt/nuxt/pull/21246) with a given version of *another* module.

In addition, this release will finally unlock a new `nuxt/module-builder` mode that should improve type support for module authors. If you're a module author, you might consider following [these migration steps](https://github.com/nuxt/starter/pull/392) to try it out in the coming days.

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

## 📃 Full changelog

Read the full release notes on [https://github.com/nuxt/nuxt/releases/tag/v3.6.0](https://github.com/nuxt/nuxt/releases/tag/v3.6.0)

---

# Source: https://nuxt.com/raw/blog/v3-7.md

# Nuxt 3.7

> Nuxt 3.7 is out, bringing a new CLI, native web streams and response, rendering optimisations, async context support - and much more.

### 🐣 A New CLI

We've refactored `nuxi` using [unjs/citty](http://github.com/unjs/citty) and this marks the first Nuxt release that depends on the new version, safely in its own repository. We have grand plans for this - check out some of the features + roadmap discussions in [nuxt/cli](https://github.com/nuxt/cli) and please feel free to contribute!

- [**Project Goals**](https://github.com/nuxt/cli/discussions/3)
- [Feedbacks and Ideas](https://github.com/nuxt/cli/discussions/4)
- [The journey of Nuxt CLI Generations](https://github.com/nuxt/cli/discussions/7)

Nuxi is now decoupled from the main `nuxt` version - we plan to iterate and release nuxi more quickly in future so you can expect new things coming soon!

### 🕸️ Native Web Streams and `Response`

With improvements in [unjs/h3](https://github.com/unjs/h3) and [unjs/nitro](https://github.com/unjs/nitro), it's now possible to directly return a `Response` object from server routes, meaning it's *also* possible to return and handle streams natively in Nuxt.

👉 Check out the full detail in the [unjs/h3](https://github.com/unjs/h3/releases) and [unjs/nitro](https://github.com/unjs/nitro/releases) release notes.

### 🔥 HTML Rendering Optimisations

This release comes with a couple of improvements in rendering HTML responses from the server. We now determine whether to preload/prefetch resources at build time (so you can customise this in the `build:manifest` hook). We also now manage rendering the HTML for them directly in `unhead` ([#22179](https://github.com/nuxt/nuxt/pull/22179)), which means you can configure the *order* for `<link>`, `<meta>`, `<script>`, `<style>`, and more. And - in our preliminary testing - it's even faster!

It's possible to opt-in to upcoming head improvements with the `experimental.headNext` flag. This currently includes a new ordering algorithm based on [capo.js](https://github.com/rviscomi/capo.js) ([#22431](https://github.com/nuxt/nuxt/pull/22431)) and allows enabling future optimisations as they are released in `unhead`:

```ts
export default defineNuxtConfig({
  experimental: {
    headNext: true
  }
})
```

We'd love your thoughts - you can respond with any issues/feedback in [this discussion](https://github.com/nuxt/nuxt/discussions/22632).

### 🛠️ Build Environment Shortcuts

In your Nuxt config you can now use `$client` and `$server` shortcuts to easily define configuration that is specific to just the Vite client/server ([#22302](https://github.com/nuxt/nuxt/pull/22302)) or webpack client/server ([#22304](https://github.com/nuxt/nuxt/pull/22304)) builds. This previously was only possible with the `vite:extendConfig` and `webpack:config` hooks.

For example:

```ts
export default defineNuxtConfig({
  vite: {
    $client: {
      build: {
        rollupOptions: {
          output: {
            chunkFileNames: '_nuxt/[hash].js',
            assetFileNames: '_nuxt/[hash][extname]',
            entryFileNames: '_nuxt/[hash].js'
          }
        }
      }
    }
  }
})
```

### ⚡️ Vite 4.4

We've chosen to unpin Vite from minor versions, meaning whenever Vite releases a new feature version you can opt-in straight away. Vite 4.4 brings a lot of exciting things, including experimental Lightning CSS support - and much more!

👉 Check out the [Vite release notes](https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md#440-2023-07-06) for more.

### 💪 TypeScript Updates

We now use purely relative paths in the generated `tsconfig.json` instead of setting a `baseUrl`. This means better support for dev environments like docker images where the absolute path may not match your IDE ([#22410](https://github.com/nuxt/nuxt/pull/22410)).

We also set a couple of additional compiler flag defaults to match Vite/TS recommendations ([#22468](https://github.com/nuxt/nuxt/pull/22468)).

Plus, you should now get type hinted access to layouts in `setPageLayout` and also in `<NuxtLayout name>` ([#22363](https://github.com/nuxt/nuxt/pull/22362)).

### 🦄 Async Context support

If you've ever got an issue with 'Nuxt context unavailable' this might be one for you. We now support  native async context for Bun and Node under an experimental flag, in both Nuxt and Nitro ([#20918](https://github.com/nuxt/nuxt/pull/20918)).

This enables using Nuxt composables on the server *without* needing to ensure they are being called directly in a setup function. It also allows the same in Nitro, with a new `useEvent()` utility that is usable in server routes.

To try it out, you can enable `experimental.asyncContext`:

```ts
export default defineNuxtConfig({
  experimental: {
    asyncContext: true
  }
})
```

### 👓 Watcher Updates

We've fixed a couple of issues with watchers, meaning that you should need to restart your server less often - and you should see a significant performance increase if you are using layers.

### ⚗️ Nitro 2.6

There lots more exciting features coming directly from Nitro 2.6, including smaller, lighter servers and new persistent data storage in a `.data` directory.

👉 Read more in [the full release article](https://unjs.io/blog/2023-08-25-nitro-2.6).

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade --force
```

This will refresh your lockfile as well, and ensures that you pull in updates from other dependencies that Nuxt relies on, particularly in the [unjs](https://github.com/unjs) ecosystem.

## 📃 Full changelog

Read the full release notes on [https://github.com/nuxt/nuxt/releases/tag/v3.7.0](https://github.com/nuxt/nuxt/releases/tag/v3.7.0)

---

# Source: https://nuxt.com/raw/blog/v3-8.md

# Nuxt 3.8

> Nuxt 3.8 is out, bringing built-in DevTools, automatic Nuxt Image install, a new app manifest and much more.

### 💻 CLI Improvements

Just to remind you, we're now using [the new Nuxt CLI](https://github.com/nuxt/cli) which is now versioned separately.

<tip>

You can now install a module with `nuxi module add <module-name>`

</tip>

<note icon="i-lucide-rocket">

We now share the same port with the Vite websocket, meaning better support for docker containers in development.

</note>

<read-more to="https://github.com/nuxt/cli/releases/tag/v3.9.0" icon="i-simple-icons-github" color="gray" target="_blank">

Read the Nuxt CLI `v3.9.0` release notes.

</read-more>

### ✨ Built-in Nuxt DevTools

Nuxt DevTools v1.0.0 is out and we now think it's ready to be shipped as a direct dependency of Nuxt.

<read-more to="/blog/nuxt-devtools-v1-0" icon="i-simple-icons-github" color="gray">

Check out Nuxt DevTools v1.0 announcement.

</read-more>

### 📸 Nuxt Image Auto-install

[`<NuxtImg>`](/docs/api/components/nuxt-img) and [`<NuxtPicture>`](/docs/api/components/nuxt-picture) first-class built-in components.

We now auto-installing `@nuxt/image` the first time that they are used ([#23717](https://github.com/nuxt/nuxt/pull/23717)).

<video :controls="true" className="rounded,dark:border,dark:border-gray-700" controls="true" poster="https://res.cloudinary.com/nuxt/video/upload/v1697721767/nuxt3/nuxt-image-auto-install_uqkptq.jpg">
<source src="https://res.cloudinary.com/nuxt/video/upload/v1697721767/nuxt3/nuxt-image-auto-install_uqkptq.webm" type="video/webm" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697721767/nuxt3/nuxt-image-auto-install_uqkptq.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/nuxt/video/upload/v1697721767/nuxt3/nuxt-image-auto-install_uqkptq.ogg" type="video/ogg" />
</video>

<tip>

We advise using [`@nuxt/image`](https://image.nuxt.com) if you're using images in your site; it can apply optimisations to make your site more performant.

</tip>

### 📂 Deeper Layout Scanning

<caution>

This is a behaviour change so do take care with this one.

</caution>

We now support scanning layouts within subfolders in [`~/layouts`](/docs/guide/directory-structure/layouts) in the same way as we do with [`~/components`](/docs/guide/directory-structure/components).

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      Layout name
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      ~/layouts/desktop/default.vue
    </td>
    
    <td>
      'desktop-default'
    </td>
  </tr>
  
  <tr>
    <td>
      ~/layouts/desktop-base/base.vue
    </td>
    
    <td>
      'desktop-base'
    </td>
  </tr>
  
  <tr>
    <td>
      ~/layouts/desktop/index.vue
    </td>
    
    <td>
      'desktop'
    </td>
  </tr>
</tbody>
</table>

<read-more to="/docs/guide/directory-structure/layouts#named-layout">

Read more about **Named Layouts**.

</read-more>

### 📊 App Manifest

We now support a built-in app manifest (see [PR #21641](https://github.com/nuxt/nuxt/pull/21641)), which generates a manifest at `/_nuxt/builds/meta/<buildId>.json`.

It enables loading payloads **only for prerendered routes**, if a site is generated with `nuxt generate`, preventing 404s in the console.

It also enables **client-side route rules**. Only `redirect` route rules is supported for now; they will now redirect when performing client-side navigation.

<code-group>

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/about': { redirect: '/about-us' }
  }
})
```

```vue [pages/index.vue]
<template>
  <div>
    <!-- Will be redirected to /about-us on client-side -->
    <NuxtLink to="/about">About</NuxtLink>
  </div>
</template>
```

</code-group>

<tip icon="i-lucide-rocket">

The app manifest also enables future enhancements including detection of a new deployment by checking `/_nuxt/builds/latest.json`.

</tip>

<note>

You can **opt-on from this behaviour if you need to** by setting `experimental.appManifest` to `false` in your `nuxt.config.ts` file.

</note>

### 🤝 Scope and Context Improvements

We now define a 'scope' for Nuxt composables executed in plugins ([#23667](https://github.com/nuxt/nuxt/pull/23667)), which allows running synchronous cleanup before navigating away from your site, using the Vue [`onScopeDispose`](https://vuejs.org/api/reactivity-advanced.html#onscopedispose) lifecycle method.

<note>

This should fix an edge case with cookies ([#23697](https://github.com/nuxt/nuxt/pull/23697)) and also improves memory management such as Pinia stores ([#23650](https://github.com/nuxt/nuxt/issues/23650)).

</note>

<read-more to="https://vuejs.org/api/reactivity-advanced.html#effectscope" icon="i-simple-icons-vuedotjs" target="_blank">

Read more about Vue effect scopes.

</read-more>

We also now support [**native async context**](https://nodejs.org/api/async_context.html) for the *Vue composition API* ([#23526](https://github.com/nuxt/nuxt/pull/23526)). In case you're unaware, we support native async context on Node and Bun, enabled with [`experimental.asyncContext`](/docs/guide/going-further/experimental-features#asynccontext).

If you experience issues with `Nuxt instance unavailable`, enabling this option may solve your issues:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    asyncContext: true
  }
})
```

<note>

Once we have cross-runtime support, we will enable it by default.

</note>

### 🔗 NuxtLink Defaults

You can define your own [`<NuxtLink>`](/docs/api/components/nuxt-link) components with the [`defineNuxtLink`](/docs/api/components/nuxt-link#definenuxtlink-signature) utility.

Today, you can cutomize the options for the built-in [`<NuxtLink>`](/docs/api/components/nuxt-link), directly in your `nuxt.config.ts` file ([#23724](https://github.com/nuxt/nuxt/pull/23724)).

This can enable you to enforce trailing slash behaviour across your entire site, for example:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    defaults: {
      nuxtLink: {
        activeClass: 'nuxt-link-active',
        trailingSlash: 'append'
      }
    }
  }
})
```

### ⚡️ Data Fetching Improvements

We have two very significant new features for [`useAsyncData`](/docs/api/composables/use-async-data) and [`useFetch`](/docs/api/composables/use-fetch):

1. You can now set `deep: false` to prevent deep reactivity on the `data` object returned from these composables ([#23600](https://github.com/nuxt/nuxt/pull/23600)). It should be a performance improvement if you are returning large arrays or objects. The object will still update when refetched; it just won't trigger reactive effects if you change a property deep within the `data`.
2. You can now use the `getCachedData` option to handle custom caching for these composables ([#20747](https://github.com/nuxt/nuxt/pull/20747))

```vue [pages/index.vue]
<script setup>
const nuxtApp = useNuxtApp()
const { data } = await useAsyncData(() => { /* fetcher */ }, {
  // this will not refetch if the key exists in the payload
  getCachedData: key => nuxtApp.payload.static[key] ?? nuxtApp.payload.data[key]
})
</script>
```

<video-accordion title="Watch the video from Alexander Lichter about Client-side caching with getCachedData." video-id="aQPR0xn-MMk">



</video-accordion>

We also support configuring some default values for these composables in an app-wide way ([#23725](https://github.com/nuxt/nuxt/pull/20747)):

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    defaults: {
      useAsyncData: {
        deep: false
      },
      useFetch: {
        retry: false,
        retryDelay: 100,
        retryStatusCodes: [500],
        timeout: 100
      }
    }
  }
})
```

### 🔢 Layer Improvements

We now more carefully load layer plugins ([#22889](https://github.com/nuxt/nuxt/pull/22889) and [#23148](https://github.com/nuxt/nuxt/pull/23148)) and middleware ([#22925](https://github.com/nuxt/nuxt/pull/22925) and [#23552](https://github.com/nuxt/nuxt/pull/23552)) in the order of the layers, always loading your own plugins and middleware last. This should mean you can rely on utilities that layers may inject.

And probably one of the most significant changes - if you are using remote layers we now clone these within your [`node_modules/`](/docs/guide/directory-structure/node_modules) folder ([#109](https://github.com/unjs/c12/pull/109)) so layers can use dependencies with your project. See [`c12` release notes](https://github.com/unjs/c12/releases/tag/v1.5.1) for full details.

<tip icon="i-lucide-check-circle">

We've also added a test suite to cover these layer resolution changes.

</tip>

### 😴 Nightly Release Channel

Every commit to the `main` branch of Nuxt is automatically deployed to a new release, for easier testing before releases. We've renamed this from the 'edge release channel' to the 'nightly release channel' to avoid confusion with *edge deployments*. And probably also with Microsoft Edge (though I haven't heard that anyone was confused with that one!)

- `nuxt3` is now `nuxt-nightly`
- `nuxi-edge` is now `nuxi-nightly`
- `@​nuxt/kit-edge` is now `@​nuxt/kit-nightly`
- ... and so on.

<read-more to="/docs/guide/going-further/nightly-release-channel#nightly-release-channel">

Read more about the **Nighly Release Channel**.

</read-more>

### ⚗️ Nitro v2.7

Nitro v2.7 has been released with lots of improvements and bug fixes.

<tip icon="i-lucide-rocket">

🔥 One of the most significant is that we now save **40% of bundle size in production** by using native `fetch` supported in Node 18+ ([#1724](https://github.com/unjs/nitro/pull/1724)). So if possible, we'd recommend you update your Node version to at least 18.

</tip>

<read-more to="https://github.com/unjs/nitro/releases/tag/v2.7.0" icon="i-simple-icons-github" color="gray" target="_blank">

Check out Nitro v2.7 release note.

</read-more>

### 💪 Type Import Changes

<warning>

This is likely to need code changes in your project.

</warning>

Vue requires that type imports be explicit (so that the Vue compiler can correctly optimise and resolve type imports for props and so on). See [core Vue `tsconfig.json`](https://github.com/vuejs/tsconfig/blob/main/tsconfig.json#L30-L33).

We've therefore taken the decision to turn on `verbatimModuleSyntax` by default in Nuxt projects, which will throw a type error if types are imported without an explicit `type` import. To resolve it you will need to update your imports:

```diff
- import { someFunction, SomeOptions } from 'some-library'
+ import { someFunction } from 'some-library'
+ import type { SomeOptions } from 'some-library'
```

You may also encounter modules in the Nuxt ecosystem that need to be updated; please open an issue for those modules. I'm also very happy to help if you're encountering any problems with this, if you're a module author. Just tag me and I'll take a look.

If for whatever reason you need to undo this change in your project you can set the following configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      compilerOptions: {
        verbatimModuleSyntax: false
      }
    }
  }
})
```

However, we'd recommend only doing that temporarily, as Vue does need this option to be set for best results.

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade
```

## Full Release Notes

<read-more to="https://github.com/nuxt/nuxt/releases/tag/v3.8.0" icon="i-simple-icons-github" color="gray">

Read the full release notes of Nuxt `v3.8.0`.

</read-more>

Thank you for reading this far! We hope you enjoy the new release. Please do let us know if you have any feedback or issues.

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/v3-9.md

# Nuxt 3.9

> Nuxt 3.9 is out - a Christmas gift from the Nuxt team bringing Vite 5, interactive server components, new composables, a new loading API and more.

A very merry Christmas to you and yours from all Nuxters involved in this release! 🎁🎄

We have lots of features packed into v3.9 and can't wait for you to try them out.

### ⚡️ Vite 5

This release comes with Vite 5 and Rollup 4 support. Module authors may need to check to ensure that any vite plugins you're creating are compatible with these latest releases.

This comes with a whole host of great improvements and bug fixes - check out [the Vite changelog](https://vitejs.dev/guide/migration.html#migration-from-v4) for more info.

### ✨ Vue 3.4 ready

This release is tested with the latest Vue 3.4 release candidate, and has the necessary configuration to take advantage of [new features in Vue 3.4](https://blog.vuejs.org/posts/vue-3-4), including debugging hydration errors in production (just set `debug: true`) in your Nuxt config.

👉 To take advantage, just update your `vue` version once v3.4 is released, or try out the release candidate today:

```json [package.json]
{
  "dependencies": {
    "nuxt": "3.9.0",
    "vue": "3.4.0-rc.1",
    "vue-router": "latest"
  }
}
```

### 🏝️ Interactive Server Components

This is a highly-experimental update, but it's now possible to play around with interactive components within Nuxt server components. You'll need to enable this new feature additionally to component islands:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    componentIslands: {
      selectiveClient: true
    }
  }
})
```

Now, within a server component, you can specify components to hydrate by using the `nuxt-client` directive:

```vue [components/SomeComponent.server.vue]
<NuxtLink :to="/" nuxt-client />
```

We're pretty excited about this one - so do let us know how you're using it! 🙏

### 🔥 Automatic Server Optimisations

We now use Vite's new AST-aware 'define' to perform more accurate replacements on server-side code, meaning code like this will no longer throw an error:

```vue [app.vue]
<script setup lang="ts">
if (document) {
  console.log(document.querySelector('div'))
}
</script>
```

This hasn't been possible until now because we haven't wanted to run the risk of accidentally replacing normal words like `document` within non-JS parts of your apps. But Vite's new `define` functionality is powered by `esbuild` and is syntax-aware, so we feel confident in enabling this functionality. Nevertheless, you can opt out if you need to:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  hooks: {
    'vite:extendConfig' (config) {
      delete config.define!.document
    }
  }
})
```

### 🚦 Granular Loading API

We now have a new hook-based system for [`<NuxtLoadingIndicator>`](/docs/api/components/nuxt-loading-indicator), including a `useLoadingIndicator` composable that lets you control/stop/start the loading state. You can also hook into `page:loading:start` and `page:loading:end` if you prefer.

<tip>

You can read more [in the docs](/docs/api/composables/use-loading-indicator) and in the original PR ([#24010](https://github.com/nuxt/nuxt/pull/24010)).

</tip>

### 🏁 Run single events in `callOnce`

Sometimes you only want to run code once, no matter how many times you load a page - and you don't want to run it again on the client if it ran on the server.

For this, we have a new utility: [`callOnce`](/docs/api/utils/call-once) ([#24787](https://github.com/nuxt/nuxt/pull/24787)).

```vue [app.vue]
<script setup>
const websiteConfig = useState('config')

await callOnce(async () => {
  console.log('This will only be logged once')
  websiteConfig.value = await $fetch('https://my-cms.com/api/website-config')
})
</script>
```

Note that this utility is context-aware so it *must* be called in component setup function or Nuxt plugin, as with other Nuxt composables.

<read-more to="/docs/api/utils/call-once">



</read-more>

### 🚨 Error Types

For a while now, errors returned by `useAsyncData` and `useFetch` have been typed pretty generically as `Error`. We've significantly improved the type possibilities for them to make them more accurate in terms of what you'll actually receive. (We normalise errors with the `h3` `createError` utility under the hood, so they can be serialised from server to client, for example.)

We've tried to implement the type change in a backwards compatible way, but you might notice that you need to update the generic if you're manually configuring the generics for these composables. See ([#24396](https://github.com/nuxt/nuxt/pull/24396)) for more information, and do let us know if you experience any issues.

### 🔥 Schema Performance

We've taken some time in this release to make some minor performance improvements, so you should notice some things are a bit faster. This is an ongoing project and we have ideas for improving initial load time of the Nuxt dev server.

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxi upgrade
```

## Full Release Notes

<read-more to="https://github.com/nuxt/nuxt/releases/tag/v3.9.0" icon="i-simple-icons-github">

Read the full release notes of Nuxt `v3.9.0`.

</read-more>

Thank you for reading this far! We hope you enjoy the new release. Please do let us know if you have any feedback or issues.

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/v3.md

# Announcing Nuxt 3.0 stable

We are thrilled to announce the first stable version of Nuxt 3.0.0 ✨

Nuxt 3 is a modern rewrite of the Nuxt framework based on [Vite](https://vitejs.dev/), [Vue3](https://vuejs.org/), and [Nitro](https://nitro.unjs.io/) with first-class TypeScript support and the result of more than two years of research, community feedback, innovation, and experiment to make a pleasant full-stack Developer Experience for Vue development to everyone.

[Read More In the Documentation](/docs/getting-started/introduction)

## API Stability

Nuxt 3.0.0 comes with a stable, production-ready API and 50+ [supported modules](/modules) built using [Nuxt Kit](/docs/guide/going-further/modules) by the community and Nuxt team.

All composables, filesystem conventions, and configurations are guaranteed to be backward compatible with Nuxt 3.0.0. Due to the nature of the meta-frameworks, some changes happen when we upgrade the underlying dependencies (vite, rollup, and nitropack). Thanks to the new Nuxt Kit and Schema tools, such upgrades will be backward compatible as long as you are using documented features. Kit and Schema also guarantee better future compatibility. This makes it faster for us to iterate and plan the next major versions of Nuxt.

## The browser and Node.js support

Nuxt 3 officially supports evergreen browsers only. The "core browser set" is what we (And [web.dev](http://web.dev) team) believe most developers need to support most of the time in the absence of specific constraints. It takes into account [usage numbers](https://caniuse.com/usage-table), developer expectations, and [existing support in](https://make.wordpress.org/core/handbook/best-practices/browser-support/) [the ecosystem](https://angular.io/guide/browser-support). The core browser set targets the **2 most recent major versions** of Chrome, Firefox, and Edge on a monthly basis and Safari on a yearly basis.

On the server side, Nuxt 3 supports Node.js 14, 16, 18, and 19 at the moment. We encourage everyone to use the latest LTS releases of Node.js, we push them once **widely adopted by major deployment platforms**. This means we keep supporting Node.js versions as long as they are supported by the Node.js team on a rolling basis in non-major releases of Nuxt. Since 14.x is being end-of-life soon, we highly encourage you to update to the latest 18.x whenever possible.

## We Love Community

Nuxt wouldn’t be possible today without an amazing community making amazing modules, feedback, and contributions every day. Check our [Community Documentation](https://nuxt.com/docs/community/getting-help) to be involved!

## To the Future

Releasing Nuxt 3 is a big milestone for us and opens a future-proof basis for new ideas and trust for the users to build their enterprise projects with Nuxt 3.

Server Component Islands, WebSocket layer, new Deployment presets, improved CLI and DevTools and Testing infra are a few to mention. Keep an eye on the [roadmap page](https://nuxt.com/docs/community/roadmap) and [GitHub discussions](https://github.com/nuxt/nuxt/discussions) for updates.

NuxtLabs is working on [new product](https://nuxt.studio) and solutions on top of Nuxt 3 at the time of writing this article.

Stay tuned for more exciting news and Happy Nuxting 💚

---

# Source: https://nuxt.com/raw/blog/v4-1.md

# Nuxt 4.1

> Nuxt 4.1 is out - bringing enhanced build stability, better development experience, and powerful new features for module authors!

## 🔥 Build and Performance Improvements

### 🍫 Enhanced Chunk Stability

Build stability has been significantly improved with import maps ([#33075](https://github.com/nuxt/nuxt/pull/33075)). This prevents cascading hash changes that could invalidate large portions of your build when small changes are made:

```html
<!-- Automatically injected import map -->
<script type="importmap">{"imports":{"#entry":"/_nuxt/DC5HVSK5.js"}}</script>
```

By default, JS chunks emitted in a Vite build are hashed, which means they can be cached immutably. However, this can cause a significant issue: a change to a single component can cause *every* hash to be invalidated, massively increasing the chance of 404s.

In short:

1. a component is changed slightly - the hash of its JS chunk changes
2. the page which uses the component has to be updated to reference the new file name
3. the *entry* now has its hash changed because it dynamically imports the page
4. *every other file* which imports the entry has its hash changed because the entry file name is changed

Obviously this wasn't optimal. With this new feature, the hash of (otherwise) unchanged files which import the entry won't be affected.

This feature is automatically enabled and helps maintain better cache efficiency in production. It does require [native import map support](https://caniuse.com/import-maps), but Nuxt will automatically disable it if you have configured `vite.build.target` to include a browser that doesn't support import maps.

And of course you can disable it if needed:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    entryImportMap: false
  }
})
```

### 🦀 Experimental Rolldown Support

Nuxt now includes experimental support for `rolldown-vite` ([#31812](https://github.com/nuxt/nuxt/pull/31812)), bringing Rust-powered bundling for potentially faster builds.

To try Rolldown in your Nuxt project, you need to override Vite with the rolldown-powered version since Vite is a dependency of Nuxt. Add the following to your `package.json`:

<code-group sync="pm">

```json [npm]
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

```json [pnpm]
{
  "pnpm": {
    "overrides": {
      "vite": "npm:rolldown-vite@latest"
    }
  }
}
```

```json [yarn]
{
  "resolutions": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

```json [bun]
{
  "overrides": {
    "vite": "npm:rolldown-vite@latest"
  }
}
```

</code-group>

After adding the override, reinstall your dependencies. Nuxt will automatically detect when Rolldown is available and adjust its build configuration accordingly.

For more details on Rolldown integration, see the [Vite Rolldown guide](https://vite.dev/guide/rolldown).

<note>

This is experimental and may have some limitations, but offers a glimpse into the future of high-performance bundling in Nuxt.

</note>

## 🧪 Improved Lazy Hydration

Lazy hydration macros now work without auto-imports ([#33037](https://github.com/nuxt/nuxt/pull/33037)), making them more reliable when component auto-discovery is disabled:

```vue
<script setup>
// Works even with components: false
const LazyComponent = defineLazyHydrationComponent(
  'visible',
  () => import('./MyComponent.vue')
)
</script>
```

This ensures that components that are not "discovered" through Nuxt (e.g., because `components` is set to `false` in the config) can still be used in lazy hydration macros.

## 📄 Enhanced Page Rules

If you have enabled experimental extraction of route rules, these are now exposed on a dedicated `rules` property on `NuxtPage` objects ([#32897](https://github.com/nuxt/nuxt/pull/32897)), making them more accessible to modules and improving the overall architecture:

```ts
// In your module
nuxt.hook('pages:extend', pages => {
  pages.push({
    path: '/api-docs',
    rules: { 
      prerender: true,
      cors: true,
      headers: { 'Cache-Control': 's-maxage=31536000' }
    }
  })
})
```

The `defineRouteRules` function continues to work exactly as before, but now provides better integration possibilities for modules.

## 🚀 Module Development Enhancements

### 🪾 Module Dependencies and Integration

Modules can now specify dependencies and modify options for other modules ([#33063](https://github.com/nuxt/nuxt/pull/33063)). This enables better module integration and ensures proper setup order:

```ts
export default defineNuxtModule({
  meta: {
    name: 'my-module',
  },
  moduleDependencies: {
    'some-module': {
      // You can specify a version constraint for the module
      version: '>=2',
      // By default moduleDependencies will be added to the list of modules 
      // to be installed by Nuxt unless `optional` is set.
      optional: true,
      // Any configuration that should override `nuxt.options`.
      overrides: {},
      // Any configuration that should be set. It will override module defaults but
      // will not override any configuration set in `nuxt.options`.
      defaults: {}
    }
  },
  setup (options, nuxt) {
    // Your module setup logic
  }
})
```

This replaces the deprecated `installModule` function and provides a more robust way to handle module dependencies with version constraints and configuration merging.

### 🪝 Module Lifecycle Hooks

Module authors now have access to two new lifecycle hooks: `onInstall` and `onUpgrade` ([#32397](https://github.com/nuxt/nuxt/pull/32397)). These hooks allow modules to perform additional setup steps when first installed or when upgraded to a new version:

```ts
export default defineNuxtModule({
  meta: {
    name: 'my-module',
    version: '1.0.0',
  },

  onInstall(nuxt) {
    // This will be run when the module is first installed
    console.log('Setting up my-module for the first time!')
  },

  onUpgrade(inlineOptions, nuxt, previousVersion) {
    // This will be run when the module is upgraded
    console.log(`Upgrading my-module from v${previousVersion}`)
  }
})
```

The hooks are only triggered when both `name` and `version` are provided in the module metadata. Nuxt uses the `.nuxtrc` file internally to track module versions and trigger the appropriate hooks. (If you haven't come across it before, the `.nuxtrc` file should be committed to version control.)

<tip>

This means module authors can begin implementing their own 'setup wizards' to provide a better experience when some setup is required after installing a module.

</tip>

### 🙈 Enhanced File Resolution

The new `ignore` option for `resolveFiles` ([#32858](https://github.com/nuxt/nuxt/pull/32858)) allows module authors to exclude specific files based on glob patterns:

```ts
// Resolve all .vue files except test files
const files = await resolveFiles(srcDir, '**/*.vue', {
  ignore: ['**/*.test.vue', '**/__tests__/**']
})
```

### 📂 Layer Directories Utility

A new `getLayerDirectories` utility ([#33098](https://github.com/nuxt/nuxt/pull/33098)) provides a clean interface for accessing layer directories without directly accessing private APIs:

```ts
import { getLayerDirectories } from '@nuxt/kit'

const layerDirs = await getLayerDirectories(nuxt)
// Access key directories:
// layerDirs.app        - /app/ by default
// layerDirs.appPages   - /app/pages by default
// layerDirs.server     - /server by default
// layerDirs.public     - /public by default
```

## ✨ Developer Experience Improvements

### 🎱 Simplified Kit Utilities

Several kit utilities have been improved for better developer experience:

- `addServerImports` now supports single imports ([#32289](https://github.com/nuxt/nuxt/pull/32289)):

```ts
// Before: required array
addServerImports([{ from: 'my-package', name: 'myUtility' }])

// Now: can pass directly
addServerImports({ from: 'my-package', name: 'myUtility' })
```

### 🔥 Performance Optimizations

This release includes several internal performance optimizations:

- Improved route rules cache management ([#32877](https://github.com/nuxt/nuxt/pull/32877))
- Optimized app manifest watching ([#32880](https://github.com/nuxt/nuxt/pull/32880))
- Better TypeScript processing for page metadata ([#32920](https://github.com/nuxt/nuxt/pull/32920))

## 🐛 Notable Fixes

- Improved `useFetch` hook typing ([#32891](https://github.com/nuxt/nuxt/pull/32891))
- Better handling of TypeScript expressions in page metadata ([#32902](https://github.com/nuxt/nuxt/pull/32902), [#32914](https://github.com/nuxt/nuxt/pull/32914))
- Enhanced route matching and synchronization ([#32899](https://github.com/nuxt/nuxt/pull/32899))
- Reduced verbosity of Vue server warnings in development ([#33018](https://github.com/nuxt/nuxt/pull/33018))
- Better handling of relative time calculations in `<NuxtTime>` ([#32893](https://github.com/nuxt/nuxt/pull/32893))

## ✅ Upgrading

As usual, our recommendation for upgrading is to run:

```sh
npx nuxt upgrade --dedupe
```

This will refresh your lockfile and pull in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

## 📦 Nuxt 3.19

All of these features are also available in **Nuxt 3.19**, which has been released alongside v4.1. As part of our commitment to the v3 branch, we continue to backport compatible v4 features to ensure v3 users can benefit from the latest improvements.

If you're still using Nuxt 3, you can upgrade to v3.19 to get access to all these features while staying on the stable v3 release line.

## Full release notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v4.1.0">

Read the full release notes of Nuxt `v4.1.0`.

</read-more>

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.19.0">

Read the full release notes of Nuxt `v3.19.0`.

</read-more>

Thank you to everyone who contributed! We're excited to see what you build with these new features. ❤️

---

# Source: https://nuxt.com/raw/blog/v4-2.md

# Nuxt 4.2

> Nuxt 4.2 is out - with experimental TypeScript plugin support, better error handling in development, abort control for data fetching, and more!

We're excited to announce Nuxt 4.2, bringing new capabilities for better TypeScript DX, enhanced error handling, and improved control over data fetching! 🎉

## 🎯 Abort Control for Data Fetching

You can now use `AbortController` signals directly within `useAsyncData`, giving you fine-grained control over request cancellation ([#32531](https://github.com/nuxt/nuxt/pull/32531)).

This works by passing an internal signal to your `useAsyncData` `handler` to cancel any promise that can be canceled, such as `$fetch`.

```vue
<script setup lang="ts">
const { data, error, clear, refresh } = await useAsyncData('users', (_nuxtApp, { signal }) => $fetch('/api/users', {
  signal
}))

refresh() // will actually cancel the $fetch request (if dedupe: cancel)
  
clear() // will cancel the latest pending handler
</script>
```

You also pass an `AbortController` signal directly to `refresh`/`execute`, giving you fine-grained control over request cancellation. This is particularly useful when you need to abort requests based on user actions or component lifecycle events.

```ts
const { data, refresh } = await useAsyncData('posts', fetchPosts)

// Abort an ongoing refresh
const abortController = new AbortController()
refresh({ signal: abortController.signal })

// Later...
abortController.abort()
```

## 🎨 Better Error Pages in Development

When an error occurs during development, Nuxt will now display both your custom error page *and* a detailed technical error overlay ([#33359](https://github.com/nuxt/nuxt/pull/33359)). This gives you the best of both worlds – you can see what your users will experience while also having immediate access to stack traces and debugging information.

![Screenshot of the new development error page](/assets/blog/nuxt-error-page.png)

The technical overlay appears as a toggleable panel that doesn't interfere with your custom error page, making it easier to debug issues while maintaining a realistic preview of your error handling.

## 🔮 Opt-in Vite Environment API

For those wanting to experiment with cutting-edge features, you can now opt into the [Vite Environment API](https://vite.dev/guide/api-environment) ([#33492](https://github.com/nuxt/nuxt/pull/33492)).

The Vite Environment API is a major architectural improvement in Vite 6. It closes the gap between development and production by allowing the Vite dev server to handle multiple environments concurrently (rather than requiring multiple Vite dev servers, as we have done previously in Nuxt).

This should improve performance when developing and eliminate some edge case bugs.

... and it is the foundation for implementing Nitro as a Vite environment, which should speed up the dev server still further, as well as allowing more greater alignment in development with your Nitro preset.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    viteEnvironmentApi: true
  }
})
```

This is also the first breaking change for Nuxt v5. You can opt in to these breaking changes by setting `compatibilityVersion` to `5`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5
  },
})
```

Please only use this for testing, as this opts in to unlimited future breaking changes, including updating to Nitro v3 once we ship the Nuxt integration.

<callout type="warning">

This is highly experimental and the API may change. Only enable if you're prepared for potential breaking changes and want to help shape the future of Nuxt!

</callout>

## 📦 New `@nuxt/nitro-server` Package

We've extracted Nitro server integration into its own package: `@nuxt/nitro-server` ([#33462](https://github.com/nuxt/nuxt/pull/33462)). This architectural change allows for different Nitro integration patterns and paves the way for future innovations in server-side rendering.

While this change is mostly internal, it's part of our ongoing effort to make Nuxt more modular and flexible. The new package provides standalone Nitro integration and sets the foundation for alternative integration approaches (such as using Nitro as a Vite plugin in Nuxt v5+).

<callout type="info">

This is an internal refactor – no changes should be required in your code.

</callout>

## ⚡ Performance Improvements

We've also shipped several performance enhancements:

- **Precomputed renderer dependencies** – We now compute renderer dependencies at build time rather than runtime, improving cold start and initial render performance ([#33361](https://github.com/nuxt/nuxt/pull/33361))
- **Reduced dependencies** – Removed unnecessary dependencies from kit and schema packages ([7ae2cf563](https://github.com/nuxt/nuxt/commit/7ae2cf563))

### 📉 Async Data Handler Extraction

One of the most exciting performance improvements is the new experimental async data handler extraction ([#33131](https://github.com/nuxt/nuxt/pull/33131)). When enabled, handler functions passed to `useAsyncData` and `useLazyAsyncData` are automatically extracted into separate chunks and dynamically imported.

This is **particularly effective for prerendered static sites**, as the data fetching logic is only needed at build time and can be completely excluded from the client bundle.

<callout type="info">

In testing with a previous version of nuxt.com, this feature **reduced JavaScript bundle size by 39%**! Of course, your mileage may vary depending on how much data fetching logic you have.

</callout>

```vue [pages/blog/[slug].vue]
<script setup lang="ts">
// This handler will be extracted into a separate chunk
// and only loaded when needed
const { data: post } = await useAsyncData('post', async () => {
  const content = await queryContent(`/blog/${route.params.slug}`).findOne()
  
  // Complex data processing that you don't want in the client bundle
  const processed = await processMarkdown(content)
  const related = await findRelatedPosts(content.tags)
  
  return {
    ...processed,
    related
  }
})
</script>
```

For static/prerendered sites, enable it in your config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    extractAsyncDataHandlers: true
  }
})
```

The extracted handlers are then tree-shaken from your client bundle when prerendering, as the data is already available in the payload. This results in significantly smaller JavaScript files shipped to your users.

## 🔧 Experimental TypeScript Plugin Support

We're introducing experimental support for enhanced TypeScript developer experience through the [`@dxup/nuxt`](https://github.com/KazariEX/dxup) module.

This module adds a number of TypeScript plugins that aim to improve your experience when using Nuxt-specific features:

- **Smart component renaming**: Automatically updates all references when you rename auto-imported component files
- **Go to definition for dynamic imports**: Navigate directly to files when using glob patterns like `import(`~/assets/${name}.webp`)`
- **Nitro route navigation**: Jump to server route handlers from data fetching functions (`$fetch`, `useFetch`, `useLazyFetch`)
- **Runtime config navigation**: Go to definition works seamlessly with runtime config properties
- **Enhanced auto-import support**: Includes the [`@dxup/unimport`](https://github.com/KazariEX/dxup/tree/main/packages/unimport) plugin for better navigation with auto-imported composables and utilities

<note to="/docs/guide/going-further/experimental-features#typescriptplugin">

Read more in **the documentation**.

</note>

To enable this feature, set `experimental.typescriptPlugin` to `true` in your Nuxt configuration:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  experimental: {
    typescriptPlugin: true
  }
})
```

Once enabled, the module will be automatically installed and configured by Nuxt.

<warning>

This feature also requires selecting the workspace TypeScript version in VS Code. Run the "TypeScript: Select TypeScript Version" command and choose "Use Workspace Version".

</warning>

## 🎁 Other Improvements

- **Component declarationPath** – You can now specify a custom declaration path for components ([#33419](https://github.com/nuxt/nuxt/pull/33419))
- **Module resolution extensions** – Kit's `resolveModule` now accepts an `extensions` option ([#33328](https://github.com/nuxt/nuxt/pull/33328))
- **Global head utility** – New `setGlobalHead` utility in kit for easier head management ([#33512](https://github.com/nuxt/nuxt/pull/33512))

## 🩹 Important Fixes

- Route hash is now preserved when redirecting based on `routeRules` ([#33222](https://github.com/nuxt/nuxt/pull/33222))
- Fixed concurrent calls to `loadNuxtConfig` with proper cleanup ([#33420](https://github.com/nuxt/nuxt/pull/33420))
- Object-format `href` now works correctly in `<NuxtLink>` ([c69e4c30d](https://github.com/nuxt/nuxt/commit/c69e4c30d))
- Component auto-imports now work as arguments to Vue's `h()` function ([#33509](https://github.com/nuxt/nuxt/pull/33509))
- Fixed app config array handling during HMR ([#33555](https://github.com/nuxt/nuxt/pull/33555))

## ✅ Upgrading

Our recommendation for upgrading is to run:

```sh
npx nuxt upgrade --dedupe
```

This will refresh your lockfile and pull in all the latest dependencies that Nuxt relies on, especially from the unjs ecosystem.

## 👉 Full Release Notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v4.2.0">

Read the full release notes of Nuxt `v4.2.0`.

</read-more>

Thank you for reading this far! We hope you enjoy the new release. Please do let us know if you have any feedback or issues.

**Happy Nuxting ✨**

---

# Source: https://nuxt.com/raw/blog/v4-3.md

# Nuxt 4.3

> Nuxt 4.3 is out – route rule layouts, ISR payload extraction, draggable error overlay, and more!

Nuxt 4.3 brings powerful new features for layouts, caching, and developer experience – plus significant performance improvements under the hood.

## 📣 Some News

### Extended v3 Support

Early this month, I [opened a discussion](https://github.com/nuxt/nuxt/discussions/33918) to find out how the upgrade had gone from v3 to v4. I was really pleased to hear how well it had gone for most people.

Having said that, we're committed to making sure no one gets left behind. And so we will **continue to provide security updates and critical bug fix releases** beyond the previously announced end-of-life date of January 31, 2026, meaning Nuxt v3 will meet its end-of-life on July 31, 2026.

<tip>

As usual, today also brings a minor release for v3, with many of the same improvements backported from v4.3.

</tip>

### Preparing for Nuxt 5

We're closer than ever to the releases of Nuxt v5 and Nitro v3. In the coming weeks, the `main` branch of the Nuxt repository will begin receiving initial commits for Nuxt 5. However, it's still **business as usual**.

- Continue making pull requests to the `main` branch
- We'll backport changes to the `4.x` and `3.x` branches

Keep an eye out on the [Upgrade Guide](/docs/4.x/getting-started/upgrade) – we'll be adding details about how you can already start migrating your projects to prepare for Nuxt v4 with `future.compatibilityVersion: 5`.

## 🗂️ Route Rule Layouts

But that's enough about the future. We have a lot of good things for you today!

First, you can now set layouts directly in route rules using the new `appLayout` property ([#31092](https://github.com/nuxt/nuxt/pull/31092)). This provides a centralized, declarative way to manage layouts across your application without scattering `definePageMeta` calls throughout your pages.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/admin/**': { appLayout: 'admin' },
    '/dashboard/**': { appLayout: 'dashboard' },
    '/auth/**': { appLayout: 'minimal' }
  }
})
```

This might be useful for:

- Admin panels with a shared layout across many routes
- Marketing pages that need a different layout from the app

<tip>

Plus, you can pass props to layouts now! See [the `setPageLayout` improvements below](#layout-props-with-setpagelayout).

</tip>

## 📦 ISR/SWR Payload Extraction

Payload extraction now works with ISR (incremental static regeneration), SWR (stale-while-revalidate) and cache `routeRules` ([#33467](https://github.com/nuxt/nuxt/pull/33467)). Previously, only pre-rendered pages could generate `_payload.json` files.

This means:

- Client-side navigation to ISR/SWR pages can use cached payloads
- CDNs (Vercel, Netlify, Cloudflare) can cache payload files alongside HTML
- Fewer API calls during navigation – data can be prefetched and served from the cached payload

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  routeRules: {
    '/products/**': { 
      isr: 3600, // Revalidate every hour
    }
  }
})
```

## 🧹 Dev Mode Payload Extraction

Related to the above, payload extraction now also works in development mode ([#30784](https://github.com/nuxt/nuxt/pull/30784)). This makes it easier to test and debug payload behavior without needing to run a production build.

<important>

Payload extraction works in dev mode with `nitro.static` set to `true`, or for individual pages which have `isr`, `swr`, `prerender` or `cache` route rules.

</important>

## 🚫 Disable Modules from Layers

When extending Nuxt layers, you can now disable specific modules that you don't need ([#33883](https://github.com/nuxt/nuxt/pull/33883)). Just pass `false` to the module's options:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['../shared-layer'],
  // disable @nuxt/image from layer
  image: false,
})
```

## 🏷️ Route Groups in Page Meta

[Route groups](/docs/4.x/directory-structure/app/pages#route-groups) (folders wrapped in parentheses like `(protected)/`) are now exposed in page meta ([#33460](https://github.com/nuxt/nuxt/pull/33460)). This makes it easy to check which groups a route belongs to in middleware or anywhere you have access to the route.

```vue [pages/(protected)/dashboard.vue]
<script setup lang="ts">
// This page's meta will include: { groups: ['protected'] }
useRoute().meta.groups
</script>
```

```ts [middleware/auth.ts]
export default defineNuxtRouteMiddleware((to) => {
  if (to.meta.groups?.includes('protected') && !isAuthenticated()) {
    return navigateTo('/login')
  }
})
```

This provides a clean, convention-based approach to route-level authorization without needing to add `definePageMeta` to every protected page.

## 🎨 Layout Props with `setPageLayout`

The `setPageLayout` composable now accepts a second parameter to pass props to your layout ([#33805](https://github.com/nuxt/nuxt/pull/33805)):

```ts [middleware/admin.ts]
export default defineNuxtRouteMiddleware((to) => {
  setPageLayout('admin', {
    sidebar: true,
    theme: 'dark'
  })
})
```

```vue [layouts/admin.vue]
<script setup lang="ts">
defineProps<{
  sidebar?: boolean
  theme?: 'light' | 'dark'
}>()
</script>
```

## 🔧 `#server` Alias

A new `#server` alias provides clean imports within your server directory ([#33870](https://github.com/nuxt/nuxt/pull/33870)), similar to how `#shared` works:

```ts [server/api/users/[id]/profile.ts]
// Before: relative path hell
import { helper } from '../../../../utils/helper'

// After: clean and predictable
import { helper } from '#server/utils/helper'
```

The alias includes import protection – you can't accidentally import `#server` code from client or shared contexts.

## 🪟 Draggable Error Overlay

The development error overlay introduced in Nuxt 4.2 is now draggable and can be minimized ([#33695](https://github.com/nuxt/nuxt/pull/33695)). You can:

- Drag it to any corner of the screen (it snaps to edges)
- Minimize it to a small pill button when you want to keep working
- Your position and minimized state persist across page reloads

This is a quality-of-life improvement when you're iterating on fixes and don't want the overlay blocking your view.

<video :controls="true" className="rounded,dark:border,dark:border-gray-700" controls="true" poster="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.jpg">
<source src="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.webm" type="video/webm" />

<source src="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.mp4" type="video/mp4" />

<source src="https://res.cloudinary.com/dchoja2nb/video/upload/v1769103044/nuxt_4-3_error_caqkhk.ogg" type="video/ogg" />
</video>

## ⚙️ Async Plugin Constructors

Module authors can now use async functions when adding build plugins ([#33619](https://github.com/nuxt/nuxt/pull/33619)):

```ts [modules/my-module.ts]
export default defineNuxtModule({
  async setup() {
    // Lazy load only when actually needed
    addVitePlugin(() => import('my-cool-plugin').then(r => r.default()))
    
    // No need to load webpack plugin if using Vite
    addWebpackPlugin(() => import('my-cool-plugin/webpack').then(r => r.default()))
  }
})
```

This enables true lazy loading of build plugins, avoiding unnecessary code loading when plugins aren't needed.

## 🚀 Performance Improvements

This release includes several performance optimizations for faster builds:

- **Hook filters** - Internal plugins now use filters to avoid running hooks unnecessarily ([#33898](https://github.com/nuxt/nuxt/pull/33898))
- **SSR styles optimization** - The `nuxt:ssr-styles` plugin is now significantly faster ([#33862](https://github.com/nuxt/nuxt/pull/33862), [#33865](https://github.com/nuxt/nuxt/pull/33865))
- **Layer alias transform** - Skipped when using Vite (it handles this natively) ([#33864](https://github.com/nuxt/nuxt/pull/33864))
- **Route rules compilation** - Route rules are now compiled into a client chunk using `rou3`, removing the need for `radix3` in the client bundle and eliminating app manifest fetches ([#33920](https://github.com/nuxt/nuxt/pull/33920))

## 🎨 Inline Styles for Webpack/Rspack

The `inlineStyles` feature now works with webpack and rspack builders ([#33966](https://github.com/nuxt/nuxt/pull/33966)), not just Vite. This enables critical CSS inlining for better Core Web Vitals regardless of your bundler choice.

## ⚠️ Deprecations

### `statusCode` → `status`, `statusMessage` → `statusText`

In preparation for Nitro v3 and H3 v2, we're moving to use Web API naming conventions ([#33912](https://github.com/nuxt/nuxt/pull/33912)). The old properties still work but are deprecated in advance of v5:

```diff
- throw createError({ statusCode: 404, statusMessage: 'Not Found' })
+ throw createError({ status: 404, statusText: 'Not Found' })
```

## 🐛 Bug Fixes

Notable fixes in this release:

- Fixed head component deduplication using `key` attribute ([#33958](https://github.com/nuxt/nuxt/pull/33958), [#33963](https://github.com/nuxt/nuxt/pull/33963))
- Fixed async data properties not being reactive in Options API ([#34119](https://github.com/nuxt/nuxt/pull/34119))
- Fixed `useCookie` unsafe number parsing during decode ([#34007](https://github.com/nuxt/nuxt/pull/34007))
- Fixed `NuxtPage` not re-rendering when nested `NuxtLayout` has layouts disabled ([#34078](https://github.com/nuxt/nuxt/pull/34078))
- Fixed client-side pathname decoding for non-ASCII route aliases ([#34043](https://github.com/nuxt/nuxt/pull/34043))
- Fixed suspense remounting when navigating after pending state ([#33991](https://github.com/nuxt/nuxt/pull/33991))
- Fixed clipboard copy in error overlay ([#33873](https://github.com/nuxt/nuxt/pull/33873))
- Enabled `allowArbitraryExtensions` by default in TypeScript config ([#34084](https://github.com/nuxt/nuxt/pull/34084))
- Added `noUncheckedIndexedAccess` to server tsconfig for safer typing ([#33985](https://github.com/nuxt/nuxt/pull/33985))

<important>

Enabling `noUncheckedIndexedAccess` in the Nitro server TypeScript config improves type safety but may surface new type errors in your server code. This change was necessary because Nuxt's app context performs type checks on server routes ([learn more](https://nuxt.com/docs/4.x/guide/modules/recipes-advanced#known-limitations)).

While we recommend keeping this enabled for better type safety, you can disable it if needed:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  nitro: {
    typescript: {
      tsConfig: {
        compilerOptions: {
          noUncheckedIndexedAccess: false
        }
      }
    }
  }
})
```

Note that disabling this may allow type errors to slip through that could cause runtime issues with indexed access.

</important>

## 📚 Documentation

- Improved module author guides with clearer structure ([#33803](https://github.com/nuxt/nuxt/pull/33803))
- Added MCP setup instructions for Claude Desktop ([#33914](https://github.com/nuxt/nuxt/pull/33914))
- Added layers directory documentation ([#33967](https://github.com/nuxt/nuxt/pull/33967))
- Added Deno package manager examples ([#34070](https://github.com/nuxt/nuxt/pull/34070))
- Clarified type-checking context limitations for server routes ([#33964](https://github.com/nuxt/nuxt/pull/33964))

## 🎉 Nuxt 3.21.0

Alongside v4.3.0, we're releasing **Nuxt v3.21.0** with many of the same improvements backported to the 3.x branch. This release includes:

- **All the same features**: Route rule layouts, ISR payload extraction, layout props with `setPageLayout`, `#server` alias, draggable error overlay, and more
- **All performance improvements**: SSR styles optimization, hook filters, and route rules compilation
- **Module disabling**: Disable layer modules by setting options to `false`
- **Critical bug fixes**: Async data reactivity in Options API, `useCookie` number parsing, head component deduplication, and more

## ✅ Upgrading

Our recommendation for upgrading is to run:

```sh
npx nuxt upgrade --dedupe

# or, if you are upgrading to v3.21
npx nuxt@latest upgrade --dedupe --channel=v3
```

This will deduplicate your lockfile and help ensure you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

<tip>

Check out our [upgrade guide](/docs/getting-started/upgrade) if upgrading from an older version.

</tip>

## 👉 Full Release Notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v4.3.0">

Read the full release notes of Nuxt `v4.3.0`.

</read-more>

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v3.21.0">

Read the full release notes of Nuxt `v3.21.0`.

</read-more>

Thank you to all of the many contributors to this release! 💚

---

# Source: https://nuxt.com/raw/blog/v4.md

# Announcing Nuxt 4.0

> Nuxt 4.0 is here! A thoughtful evolution focused on developer experience, with better project organization, smarter data fetching, and improved type safety.

**Nuxt 4.0 is here!** 🎉

After a year of real-world testing, we're excited to announce the official release of Nuxt 4. This is a stability-focused major release, introducing a few thoughtful breaking changes in order to improve development experience.

If you've been following along, you'll recognize many of these features and changes — and if you're new to them, we hope you'll welcome them.

## 🔥 What's new?

Nuxt 4 is all about making your development experience smoother:

- **Cleaner project organization** with the new `app/` directory structure
- **Smarter data fetching** - we've taken the opportunity to address some inconsistencies and improve performance with the data layer
- **Better TypeScript support** with project-based separation between the different contexts in your project - app code, server code, `shared/` folder, and configuration
- **Faster CLI and development** with adoption of internal sockets and a faster CLI

Why these features in particular? Mostly because these kind of improvements have required making changes that are technically breaking.

In general, we aim for a hype-free approach to releases. Rather than save up features for a big release, we've been shipping improvements in Nuxt 3 minor releases.

We've also spent a lot of time figuring out how to implement these changes in a backwards-compatible way, and I hope that means that most Nuxt 3 projects can upgrade with a minimum of effort.

I'd advise reading through the [upgrade guide](/docs/4.x/getting-started/upgrade) before you start, to understand what areas of your app might be affected.

### 🗂️ New project structure

The biggest visible change is how projects are organized. Your application code now lives in an `app/` directory by default:

```bash
my-nuxt-app/
├─ app/
│  ├─ assets/
│  ├─ components/
│  ├─ composables/
│  ├─ layouts/
│  ├─ middleware/
│  ├─ pages/
│  ├─ plugins/
│  ├─ utils/
│  ├─ app.vue
│  ├─ app.config.ts
│  └─ error.vue
├─ content/
├─ public/
├─ shared/
├─ server/
└─ nuxt.config.ts
```

This helps keep your code separate from `node_modules/` and `.git/`, which makes file watchers faster (especially on Windows and Linux). It also gives your IDE better context about whether you're working with client or server code.

<tip>

**Don't want to migrate?** That's totally fine! Nuxt will detect your existing structure and keep working exactly as before.

</tip>

#### 🎨 Updated UI templates

Nuxt’s starter templates have an all new look, with improved accessibility, default titles, and template polish ([#27843](https://github.com/nuxt/nuxt/pull/27843)).

### 🔄 Smarter data fetching

We've made `useAsyncData` and `useFetch` work better. Multiple components using the same key now share their data automatically. There's also automatic cleanup when components unmount, and you can use reactive keys to refetch data when needed. Plus, we've given you more control over when cached data gets used.

Some of these features have already been made available in Nuxt v3 minor releases, because we've been rolling this out gradually. Nuxt v4 brings different defaults, and we expect to continue to work on this data layer in the days to come.

### 🔧 Better TypeScript experience

Nuxt now creates separate TypeScript projects for your app code, server code, `shared/` folder, and builder code. This should mean better autocompletion, more accurate type inference and fewer confusing errors when you're working in different contexts.

<tip>

With Nuxt 4, you will only need one `tsconfig.json` file in your project root!

</tip>

This is probably the single issue that is most likely to cause surprises when upgrading, but it should also make your TypeScript experience much smoother in the long run. Please report any issues you encounter. 🙏

### ⚡ Faster CLI and development

In parallel with the release of v4, we've been working on speeding up `@nuxt/cli`.

- **Faster cold starts** - Development server startup is noticeably faster
- **Node.js compile cache** - Automatic reuse of the v8 compile cache
- **Native file watching** - Uses `fs.watch` APIs for fewer system resources
- **Socket-based communication** - The CLI and Vite dev server now communicate via internal sockets instead of network ports, reducing overhead — particularly on Windows

These improvements combined can make a really noticeable difference in your day-to-day development experience, and we have more planned.

## 🚀 How to upgrade

Although any major release brings breaking changes, one of our main aims for this release is to ensure that the upgrade path is as smooth as possible. Most of the breaking changes have been testable with a compatibility flag for over a year.

Most projects should upgrade smoothly, but there are a few things to be aware of:

- Nuxt 2 compatibility has been removed from `@nuxt/kit`. (This will particularly affect module authors.)
- Some legacy utilities and deprecated features have been cleaned up.
- The new TypeScript setup might surface some type issues that were hidden before.
- A few modules might need further updates for full Nuxt 4 compatibility.

Don't worry though — for most breaking changes, there are configuration options to revert to the old behavior while you adjust.

### 1. Update Nuxt

Our recommendation for upgrading is to run:

```sh
npx nuxt upgrade --dedupe
```

This will deduplicate your lockfile as well, and help ensure that you pull in updates from other dependencies that Nuxt relies on, particularly in the unjs ecosystem.

### 2. Optional: use migration tools

We’ve also partnered with [Codemod](https://github.com/codemod-com/codemod) to automate many, though not all, migration steps:

<code-group>

```bash [npm]
npx codemod@latest nuxt/4/migration-recipe
```

```bash [yarn]
yarn dlx codemod@latest nuxt/4/migration-recipe
```

```bash [pnpm]
pnpm dlx codemod@latest nuxt/4/migration-recipe
```

```bash [bun]
bun x codemod@latest nuxt/4/migration-recipe
```

</code-group>

### 3. Test and adjust

Run your tests, check that everything builds correctly, and fix any issues that come up. The [upgrade guide](/docs/4.x/getting-started/upgrade) has detailed migration steps for specific scenarios.

We'd recommend reading through it in full before starting your upgrade, to understand what areas of your app might be affected.

## 🗺️ What's next?

We're planning quick patch releases to address any issues that come up. Nuxt 3 will continue to receive maintenance updates (both bug fixes and backports of features from Nuxt 4) until the end of January 2026, so there's no rush if you need time to migrate.

Looking ahead, we plan to release Nuxt 5 on the sooner side, which will bring Nitro v3 and h3 v2 for even better performance, as well as adopting the Vite Environment API for an improved (and faster!) development experience. And there's a lot more in the works too!

And, quite apart from major releases, we have a lot of exciting features planned to make their way into Nuxt 3.x and 4.x release branches, including support for SSR streaming ([#4753](https://github.com/nuxt/nuxt/issues/4753)), a first-party accessibility module ([#23255](https://github.com/nuxt/nuxt/issues/23255)), built-in fetch caching strategies ([#26017](https://github.com/nuxt/nuxt/issues/26017)), more strongly typed fetch calls (landing in Nitro v3), dynamic route discovery ([#32196](https://github.com/nuxt/nuxt/issues/32196)), multi-app support ([#21635](https://github.com/nuxt/nuxt/issues/21635)) and more.

## ❤️ Thank you

This release is credit to so many people, particularly those who have been testing v4 compatibility mode over the past year. I'm really grateful — thank you for all your help!

Happy coding with Nuxt 4! 🚀

## 📑 Full release notes

<read-more icon="i-simple-icons-github" target="_blank" to="https://github.com/nuxt/nuxt/releases/tag/v4.0.0">

Read the full release notes of Nuxt `v4.0.0`.

</read-more>

A huge thank you to everyone who's been a part of this release. ❤️

---

# Source: https://nuxt.com/raw/deploy/vercel.md

# Vercel

> Deploy your Nuxt Application to Vercel infrastructure.

<tip>

**Zero Configuration ✨**

<br />

Integration with Vercel is possible with zero configuration, [learn more](https://nitro.unjs.io/deploy#zero-config-providers).

</tip>

## Deploy using Git

1. Push your code to your git repository (GitHub, GitLab, Bitbucket).
2. [Import your project](https://vercel.com/new) into Vercel.
3. Vercel will detect that you are using Nitro and will enable the correct settings for your deployment.
4. Your application is deployed!

After your project has been imported and deployed, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/deployments/environments#preview-environment-pre-production), and all changes made to the Production Branch (commonly “main”) will result in a [Production Deployment](https://vercel.com/docs/deployments/environments#production-environment).

Learn more about Vercel’s [Git Integration](https://vercel.com/docs/git).

## Custom Build Output Configuration

You can provide additional [build output configuration](https://vercel.com/docs/build-output-api) using `nitro.vercel.config` key inside `nuxt.config.ts`. It will be merged with built-in auto generated config.

## Templates

<card-group>
<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Nuxt Vercel ISR" to="https://github.com/danielroe/nuxt-vercel-isr">

Example of a Nuxt application with hybrid rendering deployed on Vercel.

</card>

<card :ui="{"icon":{"base":"text-black dark:text-white"}}" icon="i-simple-icons-github" target="_blank" title="Nuxt on the Edge on Vercel" to="https://github.com/pi0/nuxt-on-the-edge">

Example of a Nuxt application running on Vercel Edge Functions.

</card>
</card-group>

## Learn More

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/vercel">

Head over **Nitro documentation** to learn more about On-Demand Incremental Static Regeneration or more advanced options.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/getting-started/views.md

# Source: https://nuxt.com/raw/docs/4.x/getting-started/views.md

# Views

> Nuxt provides several component layers to implement the user interface of your application.

## `app.vue`

![The app.vue file is the entry point of your application](/assets/docs/getting-started/views/app.svg)

By default, Nuxt will treat this file as the **entrypoint** and render its content for every route of the application.

```vue [app/app.vue]
<template>
  <div>
    <h1>Welcome to the homepage</h1>
  </div>
</template>
```

<tip>

If you are familiar with Vue, you might wonder where `main.js` is (the file that normally creates a Vue app). Nuxt does this behind the scene.

</tip>

## Components

![Components are reusable pieces of UI](/assets/docs/getting-started/views/components.svg)

Most components are reusable pieces of the user interface, like buttons and menus. In Nuxt, you can create these components in the [`app/components/`](/docs/4.x/directory-structure/app/components) directory, and they will be automatically available across your application without having to explicitly import them.

<code-group>

```vue [app/app.vue]
<template>
  <div>
    <h1>Welcome to the homepage</h1>
    <AppAlert>
      This is an auto-imported component.
    </AppAlert>
  </div>
</template>
```

```vue [app/components/AppAlert.vue]
<template>
  <span>
    <slot />
  </span>
</template>
```

</code-group>

## Pages

![Pages are views tied to a specific route](/assets/docs/getting-started/views/pages.svg)

Pages represent views for each specific route pattern. Every file in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory represents a different route displaying its content.

To use pages, create an `app/pages/index.vue` file and add `<NuxtPage />` component to the [`app/app.vue`](/docs/4.x/directory-structure/app/app) (or remove `app/app.vue` for default entry). You can now create more pages and their corresponding routes by adding new files in the [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory.

<code-group>

```vue [app/pages/index.vue]
<template>
  <div>
    <h1>Welcome to the homepage</h1>
    <AppAlert>
      This is an auto-imported component
    </AppAlert>
  </div>
</template>
```

```vue [app/pages/about.vue]
<template>
  <section>
    <p>This page will be displayed at the /about route.</p>
  </section>
</template>
```

</code-group>

<read-more to="/docs/4.x/getting-started/routing" title="Routing Section">



</read-more>

## Layouts

![Layouts are wrapper around pages](/assets/docs/getting-started/views/layouts.svg)

Layouts are wrappers around pages that contain a common User Interface for several pages, such as header and footer displays. Layouts are Vue files using `<slot />` components to display the **page** content. The `app/layouts/default.vue` file will be used by default. Custom layouts can be set as part of your page metadata.

<note>

If you only have a single layout in your application, we recommend using [`app/app.vue`](/docs/4.x/directory-structure/app/app) with [`<NuxtPage />`](/docs/4.x/api/components/nuxt-page) instead.

</note>

<code-group>

```vue [app/app.vue]
<template>
  <div>
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
  </div>
</template>
```

```vue [app/layouts/default.vue]
<template>
  <div>
    <AppHeader />
    <slot />
    <AppFooter />
  </div>
</template>
```

```vue [app/pages/index.vue]
<template>
  <div>
    <h1>Welcome to the homepage</h1>
    <AppAlert>
      This is an auto-imported component
    </AppAlert>
  </div>
</template>
```

```vue [app/pages/about.vue]
<template>
  <section>
    <p>This page will be displayed at the /about route.</p>
  </section>
</template>
```

</code-group>

If you want to create more layouts and learn how to use them in your pages, find more information in the [Layouts section](/docs/4.x/directory-structure/app/layouts).

## Advanced: Extending the HTML Template

<note>

If you only need to modify the `<head>`, you can refer to the [SEO and meta section](/docs/4.x/getting-started/seo-meta).

</note>

You can have full control over the HTML template by adding a Nitro plugin that registers a hook.
The callback function of the `render:html` hook allows you to mutate the HTML before it is sent to the client.

```ts [server/plugins/extend-html.ts]
export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('render:html', (html, { event }) => {
    // This will be an object representation of the html template.
    console.log(html)
    html.head.push(`<meta name="description" content="My custom description" />`)
  })
  // You can also intercept the response here.
  nitroApp.hooks.hook('render:response', (response, { event }) => { console.log(response) })
})
```

<read-more to="/docs/4.x/guide/going-further/hooks">



</read-more>

---

# Source: https://nuxt.com/raw/blog/vision-2023.md

# Nuxt: A vision for 2023

This past year has been an exciting one. Looking into the new year, there is a lot we have planned as a team and we'd love to share it with you. ✨

This past year has been an exciting one, with the release of Nuxt 3 and Nitro and the launch of the new [nuxt.com](http://nuxt.com/) website. It's been the culmination of years of work, and has not only resulted in a new major version of Nuxt, but a new Nuxt architecture, a full-stack server framework ([Nitro](https://nitro.unjs.io/)), and a new GitHub organisation and ecosystem ([UnJS](https://github.com/unjs/)).

Throughout that whole time, [Pooya Parsa](https://github.com/pi0) has led the Nuxt team, putting in countless hours of work and thought into building Nuxt 3.

Now, at the start of 2023, he's handing over the helm of the Nuxt open-source work to me ([Daniel Roe](https://github.com/danielroe)). Pooya will continue to be actively contributing to the Nuxt project and of course driving the development of UnJS ecosystem and Nitro project.

This is a real honour and I'm hugely pleased to be able to work with the rest of the team and the community to continue to drive Nuxt forward to be the intuitive way to build a web application using Vue. 😊

Looking into the new year, there is a lot we have planned as a team and we'd love to share it with you.

## Unifying Nuxt

One important change will be unifying Nuxt into a single repository.

As a complete rewrite of Nuxt 2, Nuxt 3 has been developed in a separate repository: `nuxt/framework`. Nuxt 3 even has its own documentation on [nuxt.com](http://nuxt.com/), versus the Nuxt 2 documentation on [v2.nuxt.com](https://v2.nuxt.com). In development, this helped us move faster but meant less attention on issues for Nuxt 2. It's also a bit confusing.

So in the coming days, we'll be unifying the Nuxt repos into a single repository, `nuxt/nuxt`. We'll transfer all issues and discussions across, of course, clearly labeling them as to which version of Nuxt they affect. This will also provide us an opportunity to close out issues and RFCs that we've resolved or implemented in Nuxt 3.

## New Website

This last year brought us the launch of [nuxt.com](http://nuxt.com/) and the unveiling of Nuxt's [new logo](/design-kit).

![Nuxt Website 2023](/assets/blog/website/new-website-2023.png)

We'd like to make this website the central place for everything Nuxt. That includes:

- migrating Nuxt 2 documentation so there's a single website to check (with a version switcher)
- documentation for community modules (using multi-source to pull them from their own repositories)
- revamped [examples](/docs/examples/hello-world) that show off more real use cases, including authentication, monorepos and more

We have some other exciting plans for the website, but I don't want to reveal too much, other than to say that we'll also (of course!) be open-sourcing the website soon.

## Key Modules

The modules ecosystem is an incredibly powerful one, and we are grateful to all the module authors who extend Nuxt with so many features. Today we have more than 60 modules compatible with Nuxt 3. Our goal is to continue to empower module development as well as make sure that the most used modules in Nuxt 2 are updated or have a straightforward migration path.

The main priorities at the start of the year are `nuxt/image`, PWA and `nuxt/auth`.

We're also developing RFCs for `nuxt/font` and `nuxt/script` in conjunction with the Google Aurora team, which will make it much easier to apply best performance practices to your Nuxt apps. Watch this space!

## DX and Performance

We particularly care a lot about making Nuxt a joy to use, and we'd like to keep pushing the boundary of great developer experience, which we believe results in the best experience for users of the apps we write too.

In the coming months, there will be a continued focus on developer experience and performance. Expect to see Nuxt DevTools and CLI improvements for scaffolding - and more. On the performance side, Nuxt 3 + Nitro is a game-changer for speed, performance, and customisability, and we’ll be building on top of that to enable some amazing features. 🚀

## A New Release Cycle

It's important to know what's coming, and we're going to be spending some time making sure we communicate clearly about what's happening with Nuxt through regular updates like this one.

On top of that, we're planning a consistent release cycle, following [semver](https://semver.org/). We'll aim for major framework releases every year, with an expectation of patch releases every week or so and minor releases every month or so. They should never contain breaking changes except within options clearly marked as `experimental`.

One comment: We don't want there to be as big a gap (either in time or in breaking changes) between 3 -> 4 as there was between 2 -> 3, so, when the time comes for Nuxt 4, expect a much more gentle upgrade!

In the upcoming 3.1.0 release, you can already find a host of bug fixes as well as:

- experimental server-only components and a component island renderer
- Nitro 2, Vite 4 and Rollup 3 support

## Migrating to Nuxt 3

On December 31st, 2023, Vue 2 will reach End of Life (EOL), and with it Nuxt 2. Both Vue and Nuxt will continue being available and working for many people, but at the same time, many companies and users will want to transition to Nuxt 3 (and we'd encourage this!).

Part of our focus this year therefore will be supporting everyone who wants to migrate their apps to Nuxt 3. We'll also be working to backport key bug fixes and security fixes to Nuxt 2.

In addition, there is Nuxt Bridge. It was built as a module to bring features and bug fixes from Nuxt 3 back to Nuxt 2, although it has not yet been released in a stable version. We plan to stabilise and release it in the next month or so, but our main focus over the course of the year will be on helping people transition to Nuxt 3.

---

It’s a privilege to be part of this community, and we wish you a very Happy New Year! 💚

Daniel (on behalf of the whole Nuxt team)

---

# Source: https://nuxt.com/raw/docs/3.x/guide/recipes/vite-plugin.md

# Source: https://nuxt.com/raw/docs/4.x/guide/recipes/vite-plugin.md

# Using Vite Plugins in Nuxt

> Learn how to integrate Vite plugins into your Nuxt project.

While Nuxt modules offer extensive functionality, sometimes a specific Vite plugin might meet your needs more directly.

First, we need to install the Vite plugin, for our example, we'll use `@rollup/plugin-yaml`:

<code-group sync="pm">

```bash [npm]
npm install @rollup/plugin-yaml
```

```bash [yarn]
yarn add @rollup/plugin-yaml
```

```bash [pnpm]
pnpm add @rollup/plugin-yaml
```

```bash [bun]
bun add @rollup/plugin-yaml
```

```bash [deno]
deno add npm:@rollup/plugin-yaml
```

</code-group>

Next, we need to import and add it to our [`nuxt.config.ts`](/docs/4.x/directory-structure/nuxt-config) file:

```ts [nuxt.config.ts]
import yaml from '@rollup/plugin-yaml'

export default defineNuxtConfig({
  vite: {
    plugins: [
      yaml(),
    ],
  },
})
```

Now we installed and configured our Vite plugin, we can start using YAML files directly in our project.

For example, we can have a `config.yaml` that stores configuration data and import this data in our Nuxt components:

<code-group>

```yaml [data/hello.yaml]
greeting: "Hello, Nuxt with Vite!"
```

```vue [app/components/Hello.vue]
<script setup>
import config from '~/data/hello.yaml'
</script>

<template>
  <h1>{{ config.greeting }}</h1>
</template>
```

</code-group>

## Using Vite Plugins in Nuxt Modules

If you're developing a Nuxt module and need to add Vite plugins, you should use the [`addVitePlugin`](/docs/4.x/api/kit/builder#addviteplugin) utility:

```ts [modules/my-module.ts]
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'
import yaml from '@rollup/plugin-yaml'

export default defineNuxtModule({
  setup () {
    addVitePlugin(yaml())
  },
})
```

For environment-specific plugins in Nuxt 5+, use the `applyToEnvironment()` method:

```ts [modules/my-module.ts]
import { addVitePlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addVitePlugin(() => ({
      name: 'my-client-plugin',
      applyToEnvironment (environment) {
        return environment.name === 'client'
      },
      // Plugin configuration
    }))
  },
})
```

<important>

If you're writing code that needs to access resolved Vite configuration, you should use the `config` and `configResolved` hooks *within* your Vite plugin, rather than using Nuxt's `vite:extend`, `vite:extendConfig` and `vite:configResolved`.

</important>

<read-more to="/docs/4.x/api/kit/builder#addviteplugin">

Read more about `addVitePlugin` in the Nuxt Kit documentation.

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/bridge/vite.md

# Source: https://nuxt.com/raw/docs/4.x/bridge/vite.md

# Vite

> Activate Vite to your Nuxt 2 application with Nuxt Bridge.

<warning>

When using `vite`, [nitro](/docs/4.x/bridge/nitro) must have been configured.

</warning>

## Remove Modules

- Remove `nuxt-vite`: Bridge enables same functionality

## Update Config

```ts [nuxt.config.ts]
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  bridge: {
    vite: true,
    nitro: true,
  },
})
```

## Configuration

```ts [nuxt.config.ts]
import { defineNuxtConfig } from '@nuxt/bridge'

export default defineNuxtConfig({
  vite: {
    // Config for Vite
  },
})
```

---

# Source: https://nuxt.com/raw/docs/3.x/guide/concepts/vuejs-development.md

# Source: https://nuxt.com/raw/docs/4.x/guide/concepts/vuejs-development.md

# Vue.js Development

> Nuxt uses Vue.js and adds features such as component auto-imports, file-based routing and composables for an SSR-friendly usage.

Nuxt integrates Vue 3, the new major release of Vue that enables new patterns for Nuxt users.

<note>

While an in-depth knowledge of Vue is not required to use Nuxt, we recommend that you read the documentation and go through some of the examples on [vuejs.org](https://vuejs.org).

</note>

Nuxt has always used Vue as a frontend framework.

We chose to build Nuxt on top of Vue for these reasons:

- The reactivity model of Vue, where a change in data automatically triggers a change in the interface.
- The component-based templating, while keeping HTML as the common language of the web, enables intuitive patterns to keep your interface consistent, yet powerful.
- From small projects to large web applications, Vue keeps performing well at scale to ensure that your application keeps delivering value to your users.

## Vue with Nuxt

### Single File Components

[Vue’s single-file components](https://vuejs.org/guide/scaling-up/sfc) (SFC or `*.vue` files) encapsulate the markup (`<template>`), logic (`<script>`) and styling (`<style>`) of a Vue component. Nuxt provides a zero-config experience for SFCs with [Hot Module Replacement](https://vite.dev/guide/features#hot-module-replacement) that offers a seamless developer experience.

### Auto-imports

Every Vue component created in the [`app/components/`](/docs/4.x/directory-structure/app/components) directory of a Nuxt project will be available in your project without having to import it. If a component is not used anywhere, your production’s code will not include it.

<read-more to="/docs/4.x/guide/concepts/auto-imports">



</read-more>

### Vue Router

Most applications need multiple pages and a way to navigate between them. This is called **routing**. Nuxt uses an [`app/pages/`](/docs/4.x/directory-structure/app/pages) directory and naming conventions to directly create routes mapped to your files using the official [Vue Router library](https://router.vuejs.org).

<read-more to="/docs/4.x/getting-started/routing">



</read-more>

<link-example to="/docs/4.x/examples/features/auto-imports">



</link-example>

## Differences with Nuxt 2 / Vue 2

Nuxt 3+ is based on Vue 3. The new major Vue version introduces several changes that Nuxt takes advantage of:

- Better performance
- Composition API
- TypeScript support

### Faster Rendering

The Vue Virtual DOM (VDOM) has been rewritten from the ground up and allows for better rendering performance. On top of that, when working with compiled Single-File Components, the Vue compiler can further optimize them at build time by separating static and dynamic markup.

This results in faster first rendering (component creation) and updates, and less memory usage. In Nuxt 3, it enables faster server-side rendering as well.

### Smaller Bundle

With Vue 3 and Nuxt 3, a focus has been put on bundle size reduction. With version 3, most of Vue’s functionality, including template directives and built-in components, is tree-shakable. Your production bundle will not include them if you don’t use them.

This way, a minimal Vue 3 application can be reduced to 12 kb gzipped.

### Composition API

The only way to provide data and logic to components in Vue 2 was through the Options API, which allows you to return data and methods to a template with pre-defined properties like `data` and `methods`:

```vuetwoslash
<script>
export default {
  data () {
    return {
      count: 0,
    }
  },
  methods: {
    increment () {
      this.count++
    },
  },
}
</script>
```

The [Composition API](https://vuejs.org/guide/extras/composition-api-faq) introduced in Vue 3 is not a replacement of the Options API, but it enables better logic reuse throughout an application, and is a more natural way to group code by concern in complex components.

Used with the `setup` keyword in the `<script>` definition, here is the above component rewritten with Composition API and Nuxt 3’s auto-imported Reactivity APIs:

```vue [components/Counter.vue]twoslash
<script setup lang="ts">
const count = ref(0)
const increment = () => count.value++
</script>
```

The goal of Nuxt is to provide a great developer experience around the Composition API.

- Use auto-imported [Reactivity functions](https://vuejs.org/api/reactivity-core) from Vue and Nuxt [built-in composables](/docs/4.x/api/composables/use-async-data).
- Write your own auto-imported reusable functions in the [`app/composables/` directory](/docs/4.x/directory-structure/app/composables).

### TypeScript Support

Both Vue 3 and Nuxt 3+ are written in TypeScript. A fully typed codebase prevents mistakes and documents APIs usage. This doesn’t mean that you have to write your application in TypeScript to take advantage of it. With Nuxt 3, you can opt-in by renaming your file from `.js` to `.ts` , or add `<script setup lang="ts">` in a component.

<read-more to="/docs/4.x/guide/concepts/typescript">

Read the details about TypeScript in Nuxt

</read-more>

---

# Source: https://nuxt.com/raw/docs/3.x/examples/experimental/wasm.md

# Source: https://nuxt.com/raw/docs/4.x/examples/experimental/wasm.md

# WASM

> This example demonstrates the server-side support of WebAssembly in Nuxt.

<sandbox branch="main" dir="examples/experimental/wasm" file="app.vue" repo="nuxt/examples">



</sandbox>

---

# Source: https://nuxt.com/raw/deploy/zeabur.md

# Zeabur

> Deploy your Nuxt Application to Zeabur.

Nuxt supports deploying on [Zeabur](https://zeabur.com) with minimal configuration.

## Setup

1. Create a new Zeabur app for Nuxt following the [guide](https://zeabur.com/docs/guides/nodejs/nuxt).
2. During the deployment process, you can configure environment variables in Zeabur dashboard. In your service page, open the variables tab set the following [environment variable](https://zeabur.com/docs/deploy/variables):```bash
SERVER_PRESET=zeabur
```

## Learn more

<read-more target="_blank" to="https://nitro.unjs.io/deploy/providers/zeabur">

Head over **Nitro documentation** to learn more about the Zeabur deployment preset.

</read-more>

---

# Source: https://nuxt.com/raw/deploy/zerops.md

# Zerops

> Deploy your Nuxt Application to Zerops infrastructure.

**Nodejs Preset**: `SERVER_PRESET: zerops`**Static Preset**: `SERVER_PRESET: zerops-static`

<read-more title="Zerops" to="https://zerops.io">



</read-more>

<tip>

**Nuxt x Zerops Quickrun ✨**

<br />

Want to test running Nuxt on Zerops without installing or setting up anything? Using repositories [Zerops x Nuxt - Static](https://github.com/zeropsio/recipe-nuxt-static) or [Zerops x Nuxt - SSR on Node.js](https://github.com/zeropsio/recipe-nuxt-nodejs) you can deploy example Nuxt app with a single click.

</tip>

Zerops supports deploying both static and server-side rendered apps with a simple configuration file in your project root.

## Static

Projects and services can be added either through a [Project add wizard](https://app.zerops.io/dashboard/project-add) or imported using a YAML structure:

### Creating a Project

```yml [zerops-project-import.yml]
project:
  name: recipe-nuxt

services:
  - hostname: app
    type: static
```

This will create a project called `recipe-nuxt` with a Zerops Static service called `app`.

### Setting up Zerops YAML

To tell Zerops how to build and run your app, add a `zerops.yml` to your root:

```yml [zerops.yml]
zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - yarn
        - yarn nuxi generate
      deployFiles:
        - .output/public/~
    run:
      base: static
```

Now you can trigger the [build & deploy pipeline using the Zerops CLI](#building-deploying-your-app) or by connecting the app service with your [GitHub](https://docs.zerops.io/references/github-integration/) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository from inside the service detail.

## SSR Node.js

Projects and services can be added either through a [Project add wizard](https://app.zerops.io/dashboard/project-add) or imported using a YAML structure:

```yml [zerops-project-import.yml]
project:
  name: recipe-nuxt

services:
  - hostname: app
    type: nodejs@20
```

This will create a project called `recipe-nuxt` with a Zerops Node.js service called `app`.

### Setting up Zerops YAML

To tell Zerops how to build and run your app, add a `zerops.yml` to your root:

```yml [zerops.yml]
zerops:
  - setup: nuxt
    build:
      base: nodejs@20
      buildCommands:
        - yarn
        - yarn build
      deployFiles:
        - .output/~
    run:
      base: nodejs@20
      ports:
        - port: 3000
          httpSupport: true
      start: node server/index.mjs
```

Now you can trigger the [build & deploy pipeline using the Zerops CLI](#building-deploying-your-app) or by connecting the app service with your [GitHub](https://docs.zerops.io/references/github-integration/) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository from inside the service detail.

## Building & Deploying your App

- Install the [Zerops CLI](https://github.com/zeropsio/zcli).

```sh
npm i -g @zerops/zcli
```

- Open [Settings > Access Token Management](https://app.zerops.io/settings/token-management) in the Zerops app and generate a new access token.
- Log in using your access token with the following command:

```sh
zcli login <token>
```

- Navigate to the root of your app (where `zerops.yml` is located) and run the following command to trigger the deploy:

```sh
zcli push
```

Your code can be deployed automatically on each commit or a new tag by connecting the service with your [GitHub](https://docs.zerops.io/references/gitlab-integration) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository. This connection can be set up in the service detail.

<read-more title="Zerops Documentation" to="https://docs.zerops.io/">



</read-more>