Default UI Templates

Relevant source files

The following files were used as context for generating this wiki page:

• packages/ui-templates/lib/render.ts
• packages/ui-templates/templates/welcome/index.html
• packages/nuxt/src/app/components/welcome.vue
• packages/nuxt/src/app/components/error-404.vue
• packages/nuxt/src/app/components/error-500.vue
• packages/nuxt/src/core/app.ts
• packages/ui-templates/test/templates.spec.ts

The Default UI Templates system in Nuxt provides a set of pre-defined, visually consistent components for common application states, such as the initial welcome screen, 404 Not Found errors, and 500 Internal Server errors. These templates are designed to provide a professional user experience out-of-the-box before developers implement custom views.

The system relies on a build-time transformation process that converts static HTML templates into functional Vue components and TypeScript functions. This ensures that the templates are performant, type-safe, and easily distributable across different environments within the Nuxt monorepo.
Sources: packages/ui-templates/lib/render.ts:18-25, packages/nuxt/src/core/app.ts:210-215

Template Processing Architecture

The RenderPlugin is a specialized Vite plugin responsible for transforming source HTML files into production-ready Vue and TypeScript modules. It performs several critical optimizations, including inlining CSS, processing SVGs, and minifying the resulting markup.

Processing Pipeline

The transformation logic follows a specific sequence to ensure all assets are correctly embedded and optimized:

1. Style Inlining: Uses Beasties (formerly Critters) to process and inline CSS directly into the HTML.
2. Asset Embedding: SVGs and scripts are read from the output directory and converted into Base64 data URIs or inline blocks.
3. Minification: htmlnano is utilized for aggressive whitespace collapse and HTML optimization.
4. Component Generation: The processed HTML is used to generate two distinct outputs:
   • A .vue SFC (Single File Component) for use within Nuxt applications.
   • A .ts functional template for use in environments like Nitro server runtimes.

The diagram above illustrates the build-time flow where static templates are converted into reactive Vue components and server-side TypeScript functions.
Sources: packages/ui-templates/lib/render.ts:33-140

Core UI Components

Nuxt provides three primary default templates that serve as fallbacks or entry points for applications.

Welcome Template

The Welcome template (welcome.vue) is the default landing page for new Nuxt projects. It includes links to documentation, modules, and deployment guides. If no app.vue or custom index page is found during the resolution phase, Nuxt defaults to this component.
Sources: packages/nuxt/src/core/app.ts:210-212, packages/ui-templates/templates/welcome/index.html

Error Templates

Nuxt defines standard templates for handling request failures:

• Error 404: Rendered when a route cannot be matched. It features a "Go back home" link and tabular numeric styling for the status code.
• Error 500: Rendered when an internal server error occurs. It provides a simplified interface for production environments to hide sensitive stack traces.

Sources: packages/nuxt/src/app/components/error-404.vue:64-70, packages/nuxt/src/app/components/error-500.vue:56-60

Component Metadata and Props

Every template component is generated with a standard set of props to allow customization of messages and status information.

Prop	Type	Default (404)	Default (500)
appName	String	"Nuxt"	"Nuxt"
status	Number	404	500
statusText	String	"Page not found"	"Internal server error"
description	String	"Sorry, the page..."	"This page is temporarily..."

Sources: packages/nuxt/src/app/components/error-404.vue:12-38, packages/nuxt/src/app/components/error-500.vue:12-32

Component Resolution and Rendering

During the application generation phase, the resolveApp function determines which components to use. If a developer has not provided custom implementations for the main entry point or error pages, Nuxt uses the default UI templates located in the @nuxt/ui-templates package.

The sequence diagram shows the logic used by Nuxt to prioritize user-defined components over the default UI templates.
Sources: packages/nuxt/src/core/app.ts:205-218

Implementation Details

The generated Vue components utilize the useHead composable from #imports to manage document metadata dynamically. This allows the components to set the <title> and inject global styles even when served as a standalone error page.

// Example of generated useHead usage in error-404.vue
useHead({
  title: `${ props.status } - ${ props.statusText } | ${ props.appName }`,
  script: [
    {
      innerHTML: `!function(){ /* modulepreload polyfill */ }();`
    }
  ],
  style: [
    {
      innerHTML: `*,:after,:before{box-sizing:border-box; ... }`
    }
  ]
})

Sources: packages/nuxt/src/app/components/error-404.vue:40-61

Functional TS Templates

For server-side contexts where a full Vue environment might not be necessary (e.g., initial Nitro entry points), the system generates a functional template function. This function takes a messages object and returns a raw HTML string.

export type DefaultMessages = Record<"title" | "description" | "refresh", string | boolean | number >
const _messages = { "title": "Internal Server Error", ... }

export const template = (messages: Partial<DefaultMessages>): string => {
  messages = { ..._messages, ...messages }
  return "<html>..." + escapeHtml(messages.title) + "...</html>"
}

Sources: packages/ui-templates/lib/render.ts:120-135

Summary

The Default UI Templates system provides a robust fallback mechanism for Nuxt applications. By automating the conversion of standard HTML into optimized Vue and TypeScript modules, Nuxt ensures that developers have a polished experience immediately upon project creation, while maintaining the flexibility to override these defaults during the app:resolve hook.
Sources: packages/nuxt/src/core/app.ts:205-260, packages/ui-templates/lib/render.ts:180-195