Nuxt Auto-imports — Automatic Imports of Composables, Components, and Utilities

In this tutorial, you will learn about Nuxt Auto. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Nuxt 3 auto-import system: how composables, components, and Vue APIs are automatically imported without manual imports for cleaner code.

In this lesson, you'll understand what's auto-imported in Nuxt 3, how to configure auto-imports, and how to handle naming conflicts.

What You'll Learn

What gets auto-imported (Vue APIs, Nuxt composables, components, composables), how to configure auto-imports, and how to disable or override them.

Why It Matters

Auto-imports eliminate repetitive import statements. Your code becomes cleaner and more readable without import { ref, computed } from 'vue' on every page.

flowchart LR
    A[Nuxt Auto-imports] --> B[Vue APIs]
    A --> C[Nuxt Composables]
    A --> D[Components]
    A --> E[Custom Composables]
    B --> F[ref, computed, watch...]
    C --> G[useFetch, useState...]
    D --> H[From components/]
    E --> I[From composables/]
    style A fill:#00dc82,color:#fff

Auto-imported Vue APIs

All Vue 3 Composition API functions are auto-imported:

<script setup>
// No imports needed for these:
const count = ref(0);
const doubled = computed(() => count.value * 2);
watch(count, (newVal) => console.log(newVal));
onMounted(() => console.log('Mounted'));
</script>

Nuxt auto-imports: ref, reactive, computed, watch, watchEffect, onMounted, onUnmounted, nextTick, defineProps, defineEmits, and more.

Auto-imported Nuxt Composables

Nuxt-specific composables are also auto-imported:

<script setup>
const route = useRoute();
const router = useRouter();
const head = useHead({ title: 'Home' });
const { data } = await useFetch('/api/posts');
const counter = useState('counter', () => 0);
const { $formatDate } = useNuxtApp();
</script>

Nuxt auto-imports: useState, useFetch, useAsyncData, useHead, useRoute, useRouter, useCookie, useRuntimeConfig, useNuxtApp, and more.

Custom Composable Auto-imports

Files in composables/ are auto-imported:

// composables/useCounter.ts
export const useCounter = (initial = 0) => {
  const count = ref(initial);
  const increment = () => count.value++;
  return { count, increment };
};

<!-- pages/index.vue — no import needed -->
<script setup>
const { count, increment } = useCounter();
</script>

Output: The composable is available everywhere. Nuxt scans composables/ and registers exports for auto-import.

Configuring Auto-imports

Control what gets auto-imported:

// nuxt.config.ts
export default defineNuxtConfig({
  imports: {
    autoImport: true,
    dirs: [
      'composables/**',
      '~/utils/formatters.ts'
    ]
  },

  // Disable auto-import for specific modules
  vite: {
    optimizeDeps: {
      include: []
    }
  }
});

Overriding Auto-imports

Override an auto-import with your own version:

// composables/useFetch.ts — overrides Nuxt's useFetch
export const useFetch = (url: string) => {
  return customFetchImplementation(url);
};

Nuxt uses the first match found. Your custom composable in composables/ takes precedence over built-in ones.

Disabling Auto-imports

For specific files or globally:

// nuxt.config.ts
export default defineNuxtConfig({
  // Disable all auto-imports
  imports: { autoImport: false },

  // Or disable per file type
  components: { dirs: [] }
});

When auto-imports are disabled, you must import everything manually.

Common Mistakes

1. Relying on implicit auto-imports in non-Nuxt files: Auto-imports only work in Nuxt's pages/, components/, composables/, layouts/, and middleware/ directories.
2. Creating composables without the use prefix: Files must export functions with names like useXxx to be auto-imported.
3. Naming conflicts with built-in composables: If your composables/useFetch.ts has a different signature than Nuxt's, confusion follows.
4. Forgetting that auto-imports work at build time: Auto-imports are compiled, not runtime. An import error means the file isn't in a scanned directory.
5. Not using TypeScript for type safety: Auto-imported composables work with TypeScript. Use .ts files for type-safe composables.

Practice Questions

1. What Vue APIs are auto-imported in Nuxt 3? Answer: All Composition API functions: ref, reactive, computed, watch, onMounted, onUnmounted, nextTick, defineProps, defineEmits, etc.

2. Where should you place custom composables for auto-import? Answer: In the composables/ directory. Files must export functions starting with use.

3. How do you override a built-in Nuxt auto-import? Answer: Create a composable with the same name in composables/. Your version takes precedence.

4. How do you disable auto-imports globally? Answer: Set imports: { autoImport: false } in nuxt.config.ts.

Challenge

Create a custom auto-imported composable that wraps localStorage with SSR-safe defaults. Then create a second composable that uses the first one. Verify both are auto-imported.

Mini Project

Build a utility library with 5 auto-imported composables in composables/: useLocalStorage, useDebounce, useClipboard, useMediaQuery, and useOnline. Use them across multiple pages without any imports.

FAQ

What's Next

Learn about Nuxt Modules and Plugins to extend Nuxt 3 with modules and plugins for additional functionality.