Auto-imports

Nuxt auto-imports components, composables and Vue.js APIs to use across your application without explicitly importing them.

<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/, app/composables/ and 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. ::

::note In the 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 section of your nuxt.config file. ::

Built-in Auto-imports

Nuxt auto-imports functions and composables to perform data fetching, get access to the app context and runtime config, manage state or define components and plugins.

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

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

// trying to access runtime config outside a composable
const config = useRuntimeConfig()

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

Example of working code:

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.
• app/composables/ for Vue 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. ::

Explicit Imports

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

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

export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})

This will disable auto-imports completely but it's still possible to use 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:

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

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

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

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

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

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