Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 32 ยท Components and styling

Components and composables in Nuxt

How Nuxt finds your components and composables, the component naming rules, lazy components, .client and .server files, the ClientOnly wrapper and islands.

A Nuxt project is mostly components and composables. Components are the visible pieces of the interface; composables are functions that hold logic you want to share, such as useCart() or useTheme(). Nuxt makes both easy to use: you put a file in the right folder and you can use it everywhere without writing an import line.

That convenience comes with rules about names and folders, and with one new question that plain Vue does not have: where does this component run? A Nuxt page renders on the server and then again in the browser, and some components only make sense in one of those places. This lesson covers the naming rules, the tools for choosing where a component runs, and how composables are found.

The real Nuxt code is read-only, since the sandbox has no Nuxt build. The runnable examples are plain JavaScript stand-ins that model the rules, and each one says what is real and what is the model. If auto-imports are new to you, read Auto-imports first; the plain Vue side is in Components and Composables.

Where does a component run?

Both The default. Server HTML, then hydration.
Client only .client.vue or ClientOnly. Needs the browser.
Server only .server.vue. Experimental. No JS shipped.

Choose the smallest place that works.

1 / 2

The components folder

Any .vue file in components/ (inside app/ in the current project layout) can be used in a template without an import:

TEXT
app/components/
  AppHeader.vue          -> <AppHeader />
  base/
    Button.vue           -> <BaseButton />
    Card.vue             -> <BaseCard />
  product/
    ProductCard.vue      -> <ProductCard />
    Gallery/
      Thumb.vue          -> <ProductGalleryThumb />

The name of a component is made of the folder path plus the file name, in PascalCase. If the file name already begins with the folder name, the repeated part is dropped, which is why product/ProductCard.vue is <ProductCard> and not <ProductProductCard>. Many teams use that style on purpose: the file name stays unique when you search the project, and the tag name stays short.

Lazy components

Put the prefix Lazy in front of any auto-imported component name and Nuxt loads its code only when it is first rendered:

VUE
<template>
  <LazyProductGallery v-if="showGallery" />
</template>

Use this for heavy components that are not visible at first (a modal, a chart, an editor). The component is still a normal component once it loads. Using Lazy on something that is always visible does not make the page faster; it just moves the request.

Client and server variants

Name a file with a suffix and Nuxt restricts where it runs:

  • Chart.client.vue renders only in the browser. The server renders nothing for it (or the content you place around it).
  • Banner.server.vue renders only on the server. This is a server component, an experimental feature that ships its HTML but no component JavaScript to the browser. Check the current Nuxt documentation for how to enable it and what it supports before depending on it.

If a component needs window, document, localStorage or a library that touches the DOM when it loads, give it the .client.vue suffix, or wrap it in <ClientOnly>.

ClientOnly

<ClientOnly> renders its content only in the browser, after the page has been hydrated. A #fallback slot shows something in the meantime. The server HTML contains the fallback, and so does the browser's first render, so hydration matches (see Hydration and SSR pitfalls). When the page is mounted, the real content replaces it.

VUE
<template>
  <ClientOnly>
    <MapWidget :lat="48.85" :lng="2.35" />
    <template #fallback>
      <p>Loading map...</p>
    </template>
  </ClientOnly>
</template>

Reserve space for the fallback (a fixed height, for example), or the layout will jump when the real content appears. That jump is part of what the Core Web Vitals measure as layout shift (see Performance and Core Web Vitals).

The stand-in below follows the same sequence with strings instead of a real DOM. Real parts: the three moments (server HTML, the browser's first render, after mount) and the rule that the first two must match. Model parts: the render function and the side parameter. It also shows the broken alternative: content that depends on window renders differently on the server and in the browser.

JS Server HTML, first render and after mount

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

No output.

Composables

A composable is a function whose name starts with use and that uses Vue's reactivity or lifecycle features. In Nuxt, composables in the composables/ folder are auto-imported, so any component, page, plugin or other composable can call them:

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

Nuxt scans only top-level files and the index file of each subfolder in composables/. A file nested more deeply is not scanned. So composables/cart/index.ts is found, but composables/cart/helpers.ts is not, unless index.ts re-exports it (or you add the folder to the imports.dirs option in nuxt.config.ts). The same scan covers utils/.

Three habits keep composables healthy:

  • Use state through useState, not module variables. A ref created outside the function is shared by every visitor on the server. See State with useState and Pinia.
  • Call them where Nuxt can find its context: setup, plugins, route middleware, or inside another composable that is itself called there. Composables like useFetch and useState need that context, and fail with an error such as "Nuxt instance is unavailable" when called later, for example inside a setTimeout.
  • Guard browser-only code. A composable runs on the server too. Put window access inside onMounted, or check import.meta.client.

The second stand-in reads a list of file paths and shows what Nuxt would register: component tag names and which composables are scanned. It is a model of the documented rules, not Nuxt's own resolver, which handles more cases.

JS From file paths to tags and composables

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

No output.

Islands in one paragraph

Server components are built on an idea called an island: a piece of the page that the server renders to HTML on demand, so the browser gets the markup without the component's code. Nuxt's <NuxtIsland name="..."> renders a named component this way and returns its HTML, which Nuxt then inserts into the page. It is useful for heavy, mostly static fragments (rendered Markdown, a big syntax-highlighted block). It is also experimental, interactive behavior inside an island is limited, and each island costs a server round trip when rendered on the client, so treat it as an optimization for later, not a starting point.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A file components/base/Button.vue exists. Which tag renders it?

    Nuxt joins the folder path and the file name in PascalCase: base + Button gives BaseButton.
  2. 2. What does the Lazy prefix, as in <LazyChart v-if="open" />, do?

    Lazy components are dynamically imported, which helps for heavy parts that are not visible at first.
  3. 3. A component calls window.innerWidth while rendering and causes a hydration warning. What is a sound fix?

    The server has no window. ClientOnly or a .client.vue file makes the server and the browser's first render agree.
  4. 4. Which file in composables/ will Nuxt NOT auto-import by default?

    Only top-level files and index files of subfolders are scanned. Re-export helpers from index.ts or add the folder to imports.dirs.
  5. 5. Why should you avoid a module-level ref inside a composable file?

    Module-level state outlives each request on the server and leaks between visitors.

Summary

  • Files in components/ are auto-imported; the folder path becomes part of the PascalCase tag name, and a repeated prefix is dropped.
  • Lazy loads a component's code on first render; .client.vue and <ClientOnly> keep browser-only code off the server; .server.vue and <NuxtIsland> are experimental server-rendered islands.
  • Give <ClientOnly> a sized fallback so the layout does not jump.
  • composables/ and utils/ scan top-level files and subfolder index files; use useState for shared state and call context-dependent composables during setup.

Next: Head, SEO and assets