Built-in Vue Components
Relevant source files
The following files were used as context for generating this wiki page:
Nuxt provides a set of built-in Vue components that handle essential framework functionalities such as routing, layout management, hydration control, and server-side rendering (SSR) optimizations. These components are automatically registered during the Nuxt initialization process and are available globally within the application.
The core purpose of these components is to abstract complex logic—such as conditional client-side rendering or asynchronous component loading—into simple declarative tags. This architecture ensures consistency across Nuxt applications and provides optimized defaults for common web development patterns.
Sources: packages/nuxt/src/core/nuxt.ts:600-750, packages/schema/src/types/schema.ts:1300-1350
Core Framework Components
Nuxt registers several fundamental components during the initNuxt phase. These components form the skeleton of a Nuxt application, managing everything from the primary view to error handling.
Primary Layout and Page Components
<NuxtPage>: Renders the current page component based on the active route. It integrates withvue-routerto display the appropriate content from thepages/directory.<NuxtLayout>: Renders the selected layout around pages or error content. It allows for dynamic layout switching using page metadata.<NuxtLink>: An optimized replacement for the standard<a>tag andRouterLink. It supports smart prefetching of routes to improve navigation speed.
Utility and Feedback Components
<NuxtLoadingIndicator>: Displays a progress bar during page navigation to provide visual feedback to users.<NuxtWelcome>: The default splash screen shown when a new project is created without a customapp.vue.<NuxtErrorBoundary>: Catches client-side errors within its component tree, allowing developers to display fallback UI instead of crashing the entire application.
Sources: packages/nuxt/src/core/nuxt.ts:610-680, packages/nuxt/src/pages/module.ts:600-610, packages/nuxt/test/components-templates.test.ts:100-120
Hydration and Rendering Control
Nuxt provides specialized components to control how and when Vue components are rendered and hydrated, which is critical for performance and SEO.
<ClientOnly> and <DevOnly>
The <ClientOnly> component ensures that its children are only rendered on the client side. This is essential for components that rely on browser-only APIs (like window or document). Conversely, <DevOnly> renders content only during development, stripping it entirely from production builds for better performance.
<NuxtIsland>
Used for "Component Islands" (Server Components). It allows rendering specific components exclusively on the server and fetching their static HTML, reducing the JavaScript bundle size on the client.
<NuxtClientFallback>
An experimental component that provides a fallback UI on the client if a component fails to render during SSR.
Sources: packages/nuxt/src/core/nuxt.ts:630-650, packages/nuxt/src/core/nuxt.ts:740-750, packages/schema/src/types/schema.ts:1330-1345
Component Registration Architecture
The following diagram illustrates how Nuxt discovers, processes, and registers these built-in components into the Vue application instance.
Registration flow of built-in components during the Nuxt lifecycle.
Sources: packages/nuxt/src/core/nuxt.ts:50-100, packages/nuxt/src/components/templates.ts:40-60
Component Metadata and Type Generation
Nuxt generates TypeScript definitions and metadata for all components to provide IDE support and runtime optimizations.
Metadata Structure
Each built-in component is associated with ComponentMeta, which includes descriptions and documentation URLs used for JSDoc and hover tooltips in editors.
| Component | Description | Mode |
|---|---|---|
NuxtLink | Optimized navigation between routes. | All |
NuxtPage | Displays the current page based on route. | All |
ClientOnly | Renders content only on the client. | Client |
NuxtIsland | Renders a server-only component island. | Server |
NuxtTime | Renders a formatted time element. | All |
Lazy Loading
Nuxt automatically generates "Lazy" versions of components (e.g., <LazyMyComponent>). These utilize hydration strategies like hydrateOnVisible or hydrateOnIdle to defer loading until necessary.
Sources: packages/nuxt/test/components-templates.test.ts:100-115, packages/nuxt/src/components/templates.ts:170-190, packages/schema/src/types/schema.ts:1530-1550
Implementation Details
The registration of these components is handled via the addComponent helper within the core Nuxt module.
// Example of how built-in components are added in core
addComponent({
name: 'NuxtLink',
priority: 10,
filePath: resolve(nuxt.options.appDir, 'components/nuxt-link'),
meta: getBuiltinComponentMeta('NuxtLink')
})
Sources: packages/nuxt/src/core/nuxt.ts:655-660
Virtual File System (VFS)
The componentsPluginTemplate generates a virtual plugin (components.plugin.mjs) that loops through all discovered components and registers them with the Vue application instance using nuxtApp.vueApp.component(name, component).
Sources: packages/nuxt/src/components/templates.ts:50-70
Summary
Built-in Vue components in Nuxt are the primary interface through which developers interact with framework-level logic. By standardizing components like <NuxtLink> and <NuxtPage>, Nuxt ensures that optimizations like code-splitting and prefetching are applied automatically. Specialized rendering components like <ClientOnly> and <NuxtIsland> provide fine-grained control over the hydration process, allowing for highly performant full-stack Vue applications.