mirror of
https://github.com/nuxt/nuxt.git
synced 2025-01-19 09:55:53 +00:00
210 lines
8.3 KiB
Markdown
210 lines
8.3 KiB
Markdown
---
|
||
title: Auto-imports
|
||
description: "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 twoslash [app.vue]
|
||
<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/`](/docs/guide/directory-structure/components), [`composables/`](/docs/guide/directory-structure/composables) and [`utils/`](/docs/guide/directory-structure/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/api).
|
||
::
|
||
|
||
::note
|
||
In the [`server`](/docs/guide/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/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/getting-started/data-fetching), get access to the [app context](/docs/api/composables/use-nuxt-app) and [runtime config](/docs/guide/going-further/runtime-config), manage [state](/docs/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 3 exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hooks and helpers that are auto-imported by Nuxt.
|
||
|
||
```vue twoslash
|
||
<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
|
||
|
||
<!-- 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 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.
|
||
|
||
::tip{icon="i-ph-video" to="https://www.youtube.com/watch?v=ofuKRZLtOdY" target="_blank"}
|
||
Watch a video from Alexander Lichter about handling async code in composables and fixing `Nuxt instance is unavailable` in your app.
|
||
::
|
||
|
||
::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/guide/going-further/experimental-features#asynccontext" icon="i-ph-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
|
||
}
|
||
```
|
||
|
||
**Example of working code:**
|
||
|
||
```ts twoslash [composables/example.ts]
|
||
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](/docs/guide/directory-structure/components).
|
||
- `composables/` for [Vue composables](/docs/guide/directory-structure/composables).
|
||
- `utils/` for helper functions and other utilities.
|
||
|
||
:link-example{to="/docs/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.html#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 { 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.
|
||
|
||
```ts twoslash [nuxt.config.ts]
|
||
export default defineNuxtConfig({
|
||
imports: {
|
||
autoImport: false
|
||
}
|
||
})
|
||
```
|
||
|
||
This will disable auto-imports completely but it's still possible to use [explicit 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.
|
||
::
|
||
|
||
## 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/guide/directory-structure/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).
|
||
|
||
```ts twoslash [nuxt.config.ts]
|
||
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:
|
||
|
||
```ts twoslash [nuxt.config.ts]
|
||
export default defineNuxtConfig({
|
||
imports: {
|
||
presets: [
|
||
{
|
||
from: 'vue-i18n',
|
||
imports: ['useI18n']
|
||
}
|
||
]
|
||
}
|
||
})
|
||
```
|
||
|
||
::tip{icon="i-ph-video" to="https://www.youtube.com/watch?v=FT2LQJ2NvVI" target="_blank"}
|
||
Watch a video from Alexander Lichter on how to easily set up custom auto imports.
|
||
::
|