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 components/, composables/ and utils/.
Contrary to a classic global declaration, Nuxt preserves typings, IDEs completions and hints, and only includes what is used in your production code.
server directory, Nuxt auto-imports exported functions and variables from server/utils/.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 3 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 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.
Nuxt instance is unavailable in your app.defineNuxtComponent instead of defineComponentExample 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:
components/for Vue components.composables/for Vue composables.utils/for helper functions and other utilities.
ref and computed won't be unwrapped in a component <template>.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 { ref, computed } 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.
Auto-imported Components
Nuxt also automatically imports components from your ~/components directory, although this is configured separately from auto-importing composables and utility functions.
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.
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']
}
]
}
})