1---
2name: composables-auto-imports
3description: Auto-imported Vue APIs, Nuxt composables, and custom utilities
4---
5 
6# Composables Auto-imports
7 
8Nuxt automatically imports Vue APIs, Nuxt composables, and your custom composables/utilities.
9 
10## Built-in Auto-imports
11 
12### Vue APIs
13 
14```vue
15<script setup lang="ts">
16// No imports needed - all auto-imported
17const count = ref(0)
18const doubled = computed(() => count.value * 2)
19 
20watch(count, (newVal) => {
21  console.log('Count changed:', newVal)
22})
23 
24onMounted(() => {
25  console.log('Component mounted')
26})
27 
28// Lifecycle hooks
29onBeforeMount(() => {})
30onUnmounted(() => {})
31onBeforeUnmount(() => {})
32 
33// Reactivity
34const state = reactive({ name: 'John' })
35const shallow = shallowRef({ deep: 'object' })
36</script>
37```
38 
39### Nuxt Composables
40 
41```vue
42<script setup lang="ts">
43// All auto-imported
44const route = useRoute()
45const router = useRouter()
46const config = useRuntimeConfig()
47const appConfig = useAppConfig()
48const nuxtApp = useNuxtApp()
49 
50// Data fetching
51const { data } = await useFetch('/api/data')
52const { data: asyncData } = await useAsyncData('key', () => fetchData())
53 
54// State
55const state = useState('key', () => 'initial')
56const cookie = useCookie('token')
57 
58// Head/SEO
59useHead({ title: 'My Page' })
60useSeoMeta({ description: 'Page description' })
61 
62// Request helpers (SSR)
63const headers = useRequestHeaders()
64const event = useRequestEvent()
65const url = useRequestURL()
66</script>
67```
68 
69## Custom Composables (`app/composables/`)
70 
71### Creating Composables
72 
73```ts
74// composables/useCounter.ts
75export function useCounter(initial = 0) {
76  const count = ref(initial)
77  const increment = () => count.value++
78  const decrement = () => count.value--
79  return { count, increment, decrement }
80}
81```
82 
83```ts
84// composables/useAuth.ts
85export function useAuth() {
86  const user = useState<User | null>('user', () => null)
87  const isLoggedIn = computed(() => !!user.value)
88 
89  async function login(credentials: Credentials) {
90    user.value = await $fetch('/api/auth/login', {
91      method: 'POST',
92      body: credentials,
93    })
94  }
95 
96  async function logout() {
97    await $fetch('/api/auth/logout', { method: 'POST' })
98    user.value = null
99  }
100 
101  return { user, isLoggedIn, login, logout }
102}
103```
104 
105### Using Composables
106 
107```vue
108<script setup lang="ts">
109// Auto-imported - no import statement needed
110const { count, increment } = useCounter(10)
111const { user, isLoggedIn, login } = useAuth()
112</script>
113```
114 
115### File Scanning Rules
116 
117Only top-level files are scanned:
118 
119```
120composables/
121├── useAuth.ts         → useAuth() ✓
122├── useCounter.ts      → useCounter() ✓
123├── index.ts           → exports ✓
124└── nested/
125    └── helper.ts      → NOT auto-imported ✗
126```
127 
128Re-export nested composables:
129 
130```ts
131// composables/index.ts
132export { useHelper } from './nested/helper'
133```
134 
135Or configure scanning:
136 
137```ts
138// nuxt.config.ts
139export default defineNuxtConfig({
140  imports: {
141    dirs: [
142      'composables',
143      'composables/**', // Scan all nested
144    ],
145  },
146})
147```
148 
149## Utilities (`app/utils/`)
150 
151```ts
152// utils/format.ts
153export function formatDate(date: Date) {
154  return date.toLocaleDateString()
155}
156 
157export function formatCurrency(amount: number) {
158  return new Intl.NumberFormat('en-US', {
159    style: 'currency',
160    currency: 'USD',
161  }).format(amount)
162}
163```
164 
165```vue
166<script setup lang="ts">
167// Auto-imported
168const date = formatDate(new Date())
169const price = formatCurrency(99.99)
170</script>
171```
172 
173## Server Utils (`server/utils/`)
174 
175```ts
176// server/utils/db.ts
177export function useDb() {
178  return createDbConnection()
179}
180 
181// server/utils/auth.ts
182export function verifyToken(token: string) {
183  return jwt.verify(token, process.env.JWT_SECRET)
184}
185```
186 
187```ts
188// server/api/users.ts
189export default defineEventHandler(() => {
190  const db = useDb() // Auto-imported
191  return db.query('SELECT * FROM users')
192})
193```
194 
195## Third-party Package Imports
196 
197```ts
198// nuxt.config.ts
199export default defineNuxtConfig({
200  imports: {
201    presets: [
202      {
203        from: 'vue-i18n',
204        imports: ['useI18n'],
205      },
206      {
207        from: 'date-fns',
208        imports: ['format', 'parseISO', 'differenceInDays'],
209      },
210      {
211        from: '@vueuse/core',
212        imports: ['useMouse', 'useWindowSize'],
213      },
214    ],
215  },
216})
217```
218 
219## Explicit Imports
220 
221Use `#imports` alias when needed:
222 
223```vue
224<script setup lang="ts">
225import { ref, computed, useFetch } from '#imports'
226</script>
227```
228 
229## Composable Context Rules
230 
231Nuxt composables must be called in valid context:
232 
233```ts
234// ❌ Wrong - module level
235const config = useRuntimeConfig()
236 
237export function useMyComposable() {}
238```
239 
240```ts
241// ✅ Correct - inside function
242export function useMyComposable() {
243  const config = useRuntimeConfig()
244  return { apiBase: config.public.apiBase }
245}
246```
247 
248**Valid contexts:**
249- `<script setup>` block
250- `setup()` function
251- `defineNuxtPlugin()` callback
252- `defineNuxtRouteMiddleware()` callback
253 
254## Disabling Auto-imports
255 
256```ts
257// nuxt.config.ts
258export default defineNuxtConfig({
259  // Disable all auto-imports
260  imports: {
261    autoImport: false,
262  },
263 
264  // Or disable only directory scanning (keep Vue/Nuxt imports)
265  imports: {
266    scan: false,
267  },
268})
269```
270 
271<!-- 
272Source references:
273- https://nuxt.com/docs/guide/concepts/auto-imports
274- https://nuxt.com/docs/directory-structure/app/composables
275- https://nuxt.com/docs/directory-structure/app/utils
276-->
277