Skip to main content
Nuxt auto-imports components, composables, and Vue.js APIs to use across your application without explicitly importing them. This feature improves developer experience while maintaining type safety and tree-shaking.

​
What Gets Auto-Imported?

Nuxt automatically imports:
  • Components from app/components/
  • Composables from app/composables/
  • Utilities from app/utils/
  • Vue APIs like ref, computed, watch, etc.
  • Nuxt composables like useFetch, useRoute, useState, etc.
app/app.vue
<script setup lang="ts">
const count = ref(1) // ref is auto-imported
</script>
Thanks to Nuxt’s opinionated directory structure, it can auto-import your code from specific directories.
In the docs, every function that is not explicitly imported is auto-imported by Nuxt and can be used as-is in your code.

​
Benefits of Auto-Imports

  • Less boilerplate - No need to write import statements
  • Type safety - Full TypeScript support and IntelliSense
  • Tree-shaking - Only includes what’s used in production
  • Better DX - Focus on building features, not managing imports
Contrary to a classic global declaration, Nuxt preserves typings, IDE completions and hints, and only includes what is used in your production code.

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

​
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

​
Components Auto-Import

Components in app/components/ are automatically imported and available throughout your application:
app/components/AppButton.vue
<template>
  <button class="app-button">
    <slot />
  </button>
</template>
app/app.vue
<template>
  <!-- AppButton is auto-imported, no import needed -->
  <AppButton>Click me</AppButton>
</template>

​
Composables Auto-Import

Composables in app/composables/ are automatically available:
app/composables/useCounter.ts
export const useCounter = () => {
  const count = useState('counter', () => 0)
  const increment = () => count.value++
  
  return {
    count,
    increment,
  }
}
app/app.vue
<script setup lang="ts">
// useCounter is auto-imported
const { count, increment } = useCounter()
</script>

​
Utils Auto-Import

Utility functions in app/utils/ are automatically available:
app/utils/format.ts
export const formatCurrency = (value: number) => {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD',
  }).format(value)
}
app/app.vue
<script setup lang="ts">
// formatCurrency is auto-imported
const price = formatCurrency(99.99)
</script>

​
Context Awareness

When using built-in Composition API composables provided by Vue and Nuxt, be aware that many 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 to avoid cross-request state pollution. You must use composables synchronously - you cannot use await before calling a composable, except within:
  • <script setup> blocks
  • setup() function of components declared with defineNuxtComponent
  • defineNuxtPlugin
  • defineNuxtRouteMiddleware
Example of breaking code:
composables/example.ts
// ❌ Wrong: trying to access runtime config outside a composable
const config = useRuntimeConfig()

export const useMyComposable = () => {
  // accessing runtime config here
}
Example of working code:
composables/example.ts
// ✅ Correct: accessing runtime config inside the composable
export const useMyComposable = () => {
  const config = useRuntimeConfig()
  // ...
}

​
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>
This can be useful when:
  • You need to be explicit for clarity
  • You want to avoid naming conflicts
  • You’re working with tools that don’t understand auto-imports

​
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.
nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: false,
  },
})
This will disable auto-imports completely, but you can still 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, you can set imports.scan to false:
nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    scan: false,
  },
})
With this configuration:
  • Framework functions like ref, computed, or watch will still work without manual imports
  • Custom composables and utilities need to be manually imported

​
Auto-Importing from Third-Party Packages

Nuxt allows auto-importing from third-party packages. For example, you could enable auto-import of the useI18n composable from the vue-i18n package:
nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    presets: [
      {
        from: 'vue-i18n',
        imports: ['useI18n'],
      },
    ],
  },
})
If you’re using the Nuxt module for a package, it likely has already configured auto-imports for you.

​
Best Practices

  • Use auto-imports - They’re optimized and type-safe
  • Organize by directory - Put files in the correct directory for auto-import
  • Name exports carefully - Avoid naming conflicts
  • Use TypeScript - Get full type safety and IntelliSense
  • Be aware of context - Understand when and where composables can be called
Auto-imports make Nuxt development faster and more enjoyable while maintaining code quality and performance.