Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 32 ยท First steps

Auto-imports

How Nuxt imports components, composables, utils and Vue APIs for you, the naming rules for nested components, the Lazy prefix, explicit imports and pitfalls.

In a plain Vue project every file starts with a block of import lines: Vue APIs, your components, your helper functions. A Nuxt page often has none. ref, computed, useFetch, <ProductCard> and your own useCart() simply work. That is auto-importing, and understanding how it works removes most of the mystery (and most of the surprises).

The key fact: auto-imports are not magic globals. At build time Nuxt scans your folders, builds a table of names and where they come from, and adds the import lines to your code for you. The final code is ordinary ES modules, so tree shaking still works and unused code is not shipped.

What is auto-imported

Vue APIs ref, computed, watch, onMounted.
Nuxt composables useFetch, useRoute, useState.
Your components Everything in components/.
Your functions composables/ and utils/.
1 / 2

Components

Every .vue file in components/ becomes available in templates. The name comes from the path, joined in PascalCase:

TEXT
components/
  ProductCard.vue          ->  <ProductCard />
  base/
    Button.vue             ->  <BaseButton />
  form/
    FormInput.vue          ->  <FormInput />
  ui/
    modal/
      Header.vue           ->  <UiModalHeader />

Two rules to remember:

  1. Folders become a prefix. base/Button.vue is <BaseButton>, which keeps a big components folder tidy and makes names unique.
  2. Repeated words are merged. form/FormInput.vue is <FormInput>, not <FormFormInput>. A simple habit avoids confusion: name the file with the full name (BaseButton.vue), and the folder is only for your own organization.
VUE
<!-- app/pages/index.vue (read-only) -->
<template>
  <BaseButton @click="save">Save</BaseButton>
  <FormInput v-model="email" />
</template>

You can switch off the folder prefix for a directory with the components option in nuxt.config.ts (pathPrefix: false), but the default is what most projects and examples assume.

The Lazy prefix

Add Lazy before any component name in a template and Nuxt loads that component's code only when it is first rendered:

VUE
<template>
  <LazyHeavyChart v-if="showChart" :data="rows" />
</template>

The chart's code is split into its own file and downloaded when showChart becomes true. This is a cheap way to keep the first page load small (Performance and Core Web Vitals).

Composables and utils

Functions follow the same idea. Files directly inside composables/ are scanned, and their exports become available everywhere in the app:

TypeScript
// app/composables/useCounter.ts (read-only)
export function useCounter(start = 0) {
  const count = ref(start)
  const increment = () => count.value++
  return { count, increment }
}
VUE
<script setup lang="ts">
const { count, increment } = useCounter(10)
</script>

Both named exports and a default export are picked up. For a default export the name is the file name in camelCase, so composables/useTheme.ts with export default function () {...} is available as useTheme.

The utils/ folder works the same way for plain helper functions that are not composables, such as formatPrice(). The difference is only a convention: composables use reactive state and start with use, utils do not.

There is one important limit: only the top level of those folders is scanned. A file in composables/cart/useCart.ts is not imported unless it is re-exported from composables/cart/index.ts or you add the folder to the imports.dirs option:

TypeScript
// nuxt.config.ts (read-only)
export default defineNuxtConfig({
  imports: {
    dirs: ['composables/**'],   // also scan nested folders
  },
})

The server/ folder has its own auto-import rules: files in server/utils/ are available to server routes, and server/ code does not see app/composables/ (Server middleware, plugins and utils).

What the build does with it

The first stand-in is a simplified version of the scan. It takes a list of component paths and applies the naming rules from above, including the repeated-word merge. The real algorithm in Nuxt has more cases, so treat this as a model of the idea.

JS Component paths to tag names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second stand-in goes one step further and mimics the rewrite. It scans a fake composables folder for export function and export const, builds an import map, then looks at a piece of code that uses a few names and adds exactly the imports it needs. Note that unused functions are not imported.

JS Build an import map and add imports

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that useCart and useTheme are in the map but are not imported into the page, because the page does not use them. This is why auto-importing does not bloat your bundle.

Explicit imports and aliases

Sometimes you want to see the import, or the auto-import cannot reach your code. Everything can be imported by hand:

TypeScript
// read-only
import { ref, computed } from 'vue'
import { useFetch } from '#imports'          // Nuxt's virtual module of all auto-imports
import { ProductCard } from '#components'    // all auto-imported components
import { formatPrice } from '~/utils/formatPrice'

#imports and #components are virtual modules that Nuxt generates, and ~/ points to the app folder. Explicit imports always win, so they are also the way out of a name clash.

You also need #components (or a component's real path) when you pick a component by name at runtime:

VUE
<script setup lang="ts">
import { LazyAdminPanel, LazyUserPanel } from '#components'
const panel = computed(() => (isAdmin.value ? LazyAdminPanel : LazyUserPanel))
</script>

<template>
  <component :is="panel" />
</template>

Writing <component is="AdminPanel"> with a plain string would not work, because the build only rewrites names it can see in your code.

Pitfalls

  • Name clashes. If two files export the same name, Nuxt warns and one wins. Rename one or import explicitly.
  • Nested composables folder. As shown above, only the top level is scanned.
  • Auto-imports exist only in code Nuxt compiles. A helper inside a package from node_modules cannot call useFetch() without importing it.
  • Auto-imports are not globals. window.useFetch is undefined, and code run from a string or the browser console cannot use them.
  • A component with a folder prefix is easy to misname. If <Button> shows up as an unknown element, check whether the file lives in a folder and therefore has a prefix.
  • The editor looks stale. Auto-import types come from .nuxt/. Run npx nuxt prepare if the editor reports a missing name that you know exists.

If you want fewer surprises, configure your team's preference once: either rely on auto-imports everywhere or import explicitly in shared libraries. Mixing both inside one file is legal but confusing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the tag name of components/base/Button.vue with default settings?

    The folder name becomes a PascalCase prefix, so base/Button.vue is available as BaseButton.
  2. 2. How do auto-imports work at runtime?

    Auto-imports are a build-time transform that produces ordinary ES imports, so tree shaking still removes unused code.
  3. 3. You create app/composables/cart/useCart.ts. Why might useCart be undefined?

    Add the folder to imports.dirs, re-export it from an index file or move it to the top level.
  4. 4. What does the Lazy prefix do in <LazyHeavyChart />?

    Lazy splits the component into its own chunk, downloaded when the component first appears.

Summary

  • Auto-imports are a build-time feature: Nuxt scans folders and adds regular imports to your code.
  • Component names come from the path in PascalCase, with folder prefixes and merged repeated words.
  • Lazy before a component name loads it on demand.
  • composables/ and utils/ export functions, but only top-level files are scanned unless configured.
  • Use #imports, #components and ~/ when you need explicit imports, for example for dynamic components.
  • Watch for clashes, nested folders and stale editor types.

Next, File-based routing turns the pages/ folder into real routes.