Auto-imports

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
In the [`server`](/docs/4.x/directory-structure/server) directory, Nuxt auto-imports exported functions and variables from `server/utils/`.
::

::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.
::

## 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.

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

### Vue and Nuxt Composables

<!-- TODO: move to separate page with https://github.com/nuxt/nuxt/issues/14723 and add more information -->

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" videoId="ofuKRZLtOdY"}

::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`
::

::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{to="https://github.com/nuxt/nuxt/issues/14269#issuecomment-1397352832" target="_blank"}
See the full explanation in this GitHub comment.
::

**Example of breaking code:**

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

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

## 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"}

::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).
::

### Explicit Imports

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

<!-- TODO:twoslash: Twoslash does not support tsconfig paths yet -->

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

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

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,
  },
})

## 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.
::

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

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