Nuxt/docs/2.guide/2.directory-structure/1.composables.md

115 lines
2.9 KiB
Markdown
Raw Normal View History

---
navigation.icon: IconDirectory
title: 'composables'
head.title: 'composables/'
description: Use the composables/ directory to auto-import your Vue composables into your application.
---
# Composables Directory
Nuxt 3 uses the `composables/` directory to automatically import your Vue composables into your application using [auto-imports](/docs/guide/concepts/auto-imports)!
Under the hood, Nuxt auto generates the file `.nuxt/imports.d.ts` to declare the types.
Be aware that you have to run `nuxi prepare`, `nuxi dev` or `nuxi build` in order to let Nuxt generate the types. If you create a composable without having the dev server running, TypeScript will throw an error, such as `Cannot find name 'useBar'.`
## Usage
**Method 1:** Using named export
```js [composables/useFoo.ts]
export const useFoo = () => {
return useState('foo', () => 'bar')
}
```
**Method 2:** Using default export
```js [composables/use-foo.ts or composables/useFoo.ts]
2022-01-18 16:36:29 +00:00
// It will be available as useFoo() (camelCase of file name without extension)
export default function () {
2021-12-20 10:36:25 +00:00
return useState('foo', () => 'bar')
}
```
**Usage:** You can now use auto imported composable in `.js`, `.ts` and `.vue` files
```vue [app.vue]
<template>
<div>
{{ foo }}
</div>
</template>
<script setup>
const foo = useFoo()
</script>
```
2022-04-09 09:25:13 +00:00
2023-06-27 11:27:11 +00:00
::LinkExample{link="/docs/examples/features/auto-imports"}
::
## Examples
### Nested Composables
You can use a composable within another composable using auto imports:
```js [composables/test.ts]
export const useFoo = () => {
const nuxtApp = useNuxtApp()
const bar = useBar()
}
```
### Access plugin injections
You can access [plugin injections](/docs/guide/directory-structure/plugins#automatically-providing-helpers) from composables:
```js [composables/test.ts]
export const useHello = () => {
const nuxtApp = useNuxtApp()
return nuxtApp.$hello
}
```
## How Files Are Scanned
Nuxt only scans files at the top level of the `composables/` directory, e.g.:
```bash
composables
| - index.ts // scanned
| - useFoo.ts // scanned
| - nested
| --- utils.ts // not scanned
```
Only `composables/index.ts` and `composables/useFoo.ts` would be searched for imports.
To get auto imports working for nested modules, you could either re-export them (recommended) or configure the scanner to include nested directories:
**Example:** Re-export the composables you need from the `composables/index.ts` file:
```ts [composables/index.ts]
// Enables auto import for this export
export { utils } from './nested/utils.ts'
```
**Example:** Scan nested directories inside the `composables/` folder:
```ts [nuxt.config.ts]
export default defineNuxtConfig({
imports: {
dirs: [
// Scan top-level modules
'composables',
// ... or scan modules nested one level deep with a specific name and file extension
'composables/*/index.{ts,js,mjs,mts}',
// ... or scan all modules within given directory
'composables/**'
]
}
})
```