| | |

Nuxt 01 ๐Ÿ’š Introduction & Setup โ€” Creating a Nuxt project, CLI (nuxi), and understanding full-stack Vue architecture

โฑ๏ธ Estimated read: 12 min | |

Nuxt is a powerful, open-source framework built on top of Vue.js designed to make web development intuitive and performant. While Vue provides the library for building user interfaces, Nuxt provides the structural framework, conventions, and server-side capabilities necessary to build production-grade applications. It acts as a “meta-framework,” meaning it handles the complex configurations of build tools, routing, and server-side rendering so developers can focus on writing code.

At its core, Nuxt is built on the philosophy of “Convention over Configuration.” This means that by simply following a specific directory structure, Nuxt automatically configures the application routing, component discovery, and state management. Whether you are building a static landing page, a complex e-commerce site, or a real-time dashboard, Nuxt provides the flexibility to choose between various rendering modes, including Server-Side Rendering (SSR), Static Site Generation (SSG), and Client-Side Rendering (CSR).

This chapter introduces the fundamental architecture of Nuxt, specifically Nuxt 3, which introduced the Nitro server engine. Nitro is what makes Nuxt “full-stack,” allowing it to run server-side logic, API routes, and middleware in a highly portable way across different environments like Node.js, Vercel, or Cloudflare Workers. We will also explore the Nuxt CLI tool, nuxi, which is the primary interface for creating and managing Nuxt projects.

Finally, we will walk through the initial setup process and the directory structure. Understanding how the folders are organized is crucial because Nuxt uses these folders to generate the internal workings of the app. By the end of this chapter, you will have a running Nuxt application and a solid grasp of how Vue and the Nitro server engine collaborate to deliver a high-performance, full-stack experience.

Key point: Nuxt is a full-stack meta-framework for Vue.js that automates routing, performance optimization, and server-side logic through a convention-based directory structure and the Nitro server engine.


Why Nuxt exists

The SEO and Indexing problem

Standard Single Page Applications (SPAs) built with Vue often suffer from poor SEO because the content is rendered on the client side via JavaScript. Search engine crawlers may see an empty HTML shell before the JavaScript executes. Nuxt solves this by offering Server-Side Rendering (SSR), where the server generates the full HTML for a page before sending it to the browser, ensuring crawlers see the content immediately.

The Configuration Fatigue problem

Setting up a modern Vue project with Vite, Vue Router, Pinia, and specialized build optimizations requires significant manual configuration. Nuxt exists to eliminate this “boilerplate” work. It provides an “opinionated” setup where features like file-based routing and auto-imports are enabled by default, saving developers hours of setup time for every new project.

The Performance and Initial Load trade-off

Large Vue applications can become slow to load as the JavaScript bundle grows. Nuxt addresses this through automatic code-splitting. It breaks the application into smaller chunks, loading only the JavaScript necessary for the current page. Additionally, its “Hydration” process ensures that the transition from a static server-rendered page to an interactive Vue app is seamless and fast.

The Full-Stack gap

Traditionally, Vue developers needed a separate backend (like Express or Go) to handle server-side tasks like API proxying or secure data fetching. Nuxt includes the Nitro engine, which allows developers to write server-side code (API routes) directly within the Nuxt project. This creates a unified full-stack environment where the frontend and backend share the same deployment lifecycle.

The Developer Experience (DX) problem

Managing imports for every component or Vue composable can lead to cluttered code. Nuxt’s auto-import feature recognizes components, composables, and Vue APIs based on where they are placed in the directory structure. This reduces imports, makes the code cleaner, and speeds up the development process by removing the need for manual registration.

The Deployment complexity trade-off

Deploying a Vue app to different environments (Static hosting vs. Edge functions vs. Node servers) often requires different build configurations. Nuxt provides a unified “Universal” build system. With a single command, Nuxt can prepare the application for various providers, handling the nuances of different server environments automatically through Nitro presets.


a. The Nuxt Full-Stack Architecture

Nuxt 3 is not just a frontend library; it is a full-stack engine. It consists of three primary layers that work in harmony. The first layer is Vue 3, which handles the user interface and reactive state. The second layer is Vite (or Webpack), which acts as the build tool to bundle assets and provide Hot Module Replacement (HMR). The third and most innovative layer is Nitro, the server engine.

Nitro is what sets Nuxt apart from other Vue frameworks. It allows Nuxt to run on any JavaScript environment. Nitro handles the server-side rendering logic and provides a server/ directory where you can write API endpoints. When a request comes in, Nitro decides whether to serve a cached static page, render a fresh SSR page, or execute an API route. This makes Nuxt “serverless-ready” and extremely lightweight.

# Conceptual flow of a request in Nuxt
Browser Request -> Nitro Server (Middleware/API) -> Vue SSR (Rendering) -> HTML Response

Because of Nitro, Nuxt is capable of “Hybrid Rendering.” You can define some routes to be static (built at compile time) and others to be dynamic (rendered on every request). This flexibility is controlled via routeRules in the configuration, allowing developers to optimize performance at a per-page level rather than for the whole app.


b. Creating a project with nuxi

nuxi is the official Nuxt CLI. It is a lightweight wrapper that provides commands for initializing projects, generating files, and building the application. To start a new project, you use the nuxi init command. This command fetches the latest Nuxt starter template and sets up the basic environment.

# Initialize a new project
npx nuxi@latest init my-nuxt-app

# Navigate into the folder
cd my-nuxt-app

# Install dependencies
npm install

Once the project is initialized, the development server is started with npx nuxi dev. This starts the Vite-powered dev server, which is incredibly fast due to its native ESM approach. During development, nuxi also generates a .nuxt directory. This directory contains the “virtual” files that Nuxt uses to handle auto-imports and routing. You should never modify files inside .nuxt manually, as they are overwritten every time the dev server restarts.

The nuxi CLI also includes a powerful generator tool. Instead of creating files manually, you can run npx nuxi add page about to create a new page with the correct boilerplate, or npx nuxi add component Header to create a new component. This ensures you follow the Nuxt conventions correctly from the start.


c. The Nuxt Directory Structure

Understanding the directory structure is the most important part of learning Nuxt. Because Nuxt uses file-based conventions, the name of a folder dictates its functionality. If you place a file in the pages/ folder, it automatically becomes a route. If you place a file in components/, it becomes an auto-imported Vue component.

Key directories in a fresh Nuxt 3 project include:

  • app.vue: The main entry point of your application.
  • pages/: Used for file-based routing (optional; if missing, Nuxt defaults to a single-page app via app.vue).
  • components/: For your Vue components.
  • server/: For API routes, middleware, and server utilities.
  • public/: For static assets like robots.txt or icons that shouldn’t be processed by Vite.
  • assets/: For styles, images, or fonts that Vite should process.
// Example of app.vue
<template>
  <div>
    <NuxtRouteAnnouncer /> <!-- Built-in accessibility feature -->
    <NuxtWelcome />        <!-- The default welcome component -->
  </div>
</template>

In Nuxt 3, app.vue is the primary component. If you are building a simple landing page, you might only ever use app.vue. However, as soon as you create a pages/ directory, you must add the <NuxtPage /> component to app.vue to tell Nuxt where to render the routed content. This separation allows you to create global layouts or wrappers (like a navigation bar or footer) that persist across all page transitions.


Complete Example Session

# ============================================
# PART 1: PROJECT INITIALIZATION
# ============================================
# Run the init command to pull the latest Nuxt template
npx nuxi@latest init green-energy-portal

# ============================================
# PART 2: INSTALLATION
# ============================================
cd green-energy-portal
npm install

# ============================================
# PART 3: EXPLORING app.vue (Entry Point)
# ============================================
# Open app.vue and replace the content with a basic structure
# This file serves as the main wrapper for the entire site
<!-- app.vue -->
<template>
  <div class="layout">
    <header><h1>Green Energy</h1></header>
    <NuxtPage /> <!-- This is where content from the pages/ folder appears -->
  </div>
</template>
# ============================================
# PART 4: ENABLING ROUTING
# ============================================
# Create the pages directory to enable file-based routing
mkdir pages

# ============================================
# PART 5: CREATING THE INDEX PAGE
# ============================================
# Create index.vue inside the pages folder
<!-- pages/index.vue -->
<template>
  <main>
    <h2>Welcome to the Portal</h2>
    <p>This page was automatically routed by Nuxt!</p>
  </main>
</template>
# ============================================
# PART 6: ADDING A COMPONENT
# ============================================
# Create the components directory
mkdir components

# Create a component - it will be auto-imported!
<!-- components/AppAlert.vue -->
<template>
  <div class="alert">
    <slot />
  </div>
</template>
# ============================================
# PART 7: STARTING DEVELOPMENT
# ============================================
npm run dev -- -o # Starts dev server and opens browser

# ============================================
# PART 8: ADDING A NEW PAGE VIA CLI
# ============================================
npx nuxi add page contact

# ============================================
# PART 9: BUILDING FOR PRODUCTION
# ============================================
# This command invokes Nitro to bundle the app for Node.js by default
npm run build

# ============================================
# PART 10: PREVIEWING THE PRODUCTION BUILD
# ============================================
node .output/server/index.mjs

The steps above covered initializing a project, setting up the entry point, creating the first routed page, adding an auto-imported component, and building the application for production.


Quick Reference

Nuxi CLI Commands

CommandDescription
npx nuxi init <dir>Creates a new Nuxt project from template
npx nuxi devStarts development server with HMR
npx nuxi buildBuilds the app for production (Nitro)
npx nuxi generateBuilds the app as a static site (SSG)
npx nuxi add <type> <name>Scaffolds a page, component, or composable

Directory Responsibilities

DirectoryRoleBehavior
pages/RoutingFiles here generate URL paths
components/UI ComponentsFiles here are auto-imported in templates
server/Backend LogicAPI routes, server middleware
assets/Compiled AssetsStyles/Images processed by Vite
public/Static AssetsServed exactly as-is at the root URL

Rendering Modes

ModeShort NameDescription
Server-Side RenderingSSRHTML generated on the server for every request
Static Site GenerationSSGHTML generated at build time (best for SEO)
Client-Side RenderingCSROnly JavaScript is sent; browser builds the UI

Best Practices

โœ… Do This:

# Use Node.js LTS (v18.0.0 or higher) for Nuxt 3 projects      # โœ…
# Use nuxi add to scaffold files to ensure correct naming      # โœ…
# Keep shared UI elements (Header/Footer) in app.vue           # โœ…
# Put simple logic in app.vue and complex routing in pages/    # โœ…
# Use the components/ folder for all reusable Vue files        # โœ…

โŒ Don’t Do This:

# Don't modify files inside the .nuxt/ directory              # โŒ
# Don't use manual imports for files in components/ folder     # โŒ
# Don't put large images in assets/ if they don't need Vite    # โŒ
# Don't use window or document directly in SSR (server-side)   # โŒ
# Don't ignore the terminal warnings from Nuxi                 # โŒ

Common Pitfalls

PitfallWhy It HappensFix
NuxtPage not renderingPages folder exists but NuxtPage component is missing in app.vue.Add <NuxtPage /> to your app.vue template.
Hydration MismatchHTML rendered on server differs from client (e.g. using new Date()).Wrap client-only code in <ClientOnly> tags.
Auto-import failingComponent is deeply nested or uses an invalid name.Check folder structure; Nuxt scans components/ by default.
Node Version ErrorNuxt 3 requires Node 18+, but environment is older.Update Node.js using nvm or your package manager.
CLI not foundTrying to run nuxi without npx or local install.Use npx nuxi or check package.json scripts.

Real-World Examples

1. Creating a project

npx nuxi@latest init my-company-website

2. Adding an About page

npx nuxi add page about

3. Defining a custom API route

// server/api/hello.ts
export default defineEventHandler(() => ({ message: 'Hello Nuxt' }))

4. Using an auto-imported component

<template><BaseButton>Click me</BaseButton></template>

5. Building for a Node server

NITRO_PRESET=node_server npm run build

6. Building for static hosting (Netlify/Vercel)

npm run generate

7. Accessing public assets

<img src="/logo.png" /> <!-- Points to public/logo.png -->

8. Using local styles in assets

<style src="~/assets/css/main.css"></style>

9. Scaffolding a composable

npx nuxi add composable useAuth

10. Previewing build locally

npx nuxi preview

Visual

The Nuxt 3 Tech Stack

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  USER INTERFACE (Vue 3)                                     โ”‚
โ”‚  Components, Composables, Reactivity                        โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  BUILD ENGINE (Vite / Webpack)                              โ”‚
โ”‚  Fast HMR, Bundling, Asset Optimization                     โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚  SERVER ENGINE (Nitro)                                      โ”‚
โ”‚  SSR, API Routes, Edge-Ready, Hybrid Rendering              โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Directory Relationship

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”       โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”       โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚   pages/    โ”‚ โ”€โ”€โ”€โ–บ  โ”‚   app.vue   โ”‚ โ—„โ”€โ”€โ”€  โ”‚ components/ โ”‚
โ”‚ (URL Paths) โ”‚       โ”‚ (The Frame) โ”‚       โ”‚ (UI Logic)  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜       โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜       โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                             โ”‚
                             โ–ผ
                      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                      โ”‚   Nitro     โ”‚
                      โ”‚ (Execution) โ”‚
                      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Initialization Lifecycle

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ npx nuxi init    โ”‚ โ”€โ”€โ”€โ–บ โ”‚ npm install      โ”‚ โ”€โ”€โ”€โ–บ โ”‚ npm run dev      โ”‚
โ”‚ (Pull Template)  โ”‚      โ”‚ (Get Deps)       โ”‚      โ”‚ (Start Vite)     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Framework BaseVue 3
Server EngineNitro
Build ToolVite (Default)
CLI Toolnuxi
Core PhilosophyConvention over Configuration
Primary FeaturesAuto-imports, File-based Routing, SSR/SSG
Key Fileapp.vue
Node Requirementv18.0.0+

Key takeaways:

  • Nuxt is a meta-framework. It builds on Vue 3 to provide structure, routing, and server-side capabilities that Vue alone doesn’t handle out of the box.
  • Nitro is the magic. This engine allows your app to run on almost any platform, providing server-side logic and extremely fast performance.
  • Convention defines function. Your directory structure tells Nuxt how to build your app. pages/ becomes routes, and components/ become globally available tags.
  • Auto-imports simplify code. You no longer need to manually import Vue functions or your own components; Nuxt handles the “wiring” for you.
  • app.vue is your home base. It is the top-level component that wraps your entire application, acting as the bridge between global layouts and specific pages.
  • nuxi is your primary interface. Whether initializing, generating, or building, the Nuxt CLI is the tool that orchestrates the entire developer experience.

Remember: Nuxt is designed to scale with you. You can start with a single app.vue file like a standard Vue app and gradually introduce folders like pages/, server/, and middleware/ only when your application’s complexity requires them.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!