Creating a Vue 3 Project with Nuxt.js

In modern frontend development, Nuxt.js has emerged as an ideal choice for building SSR (Server-Side Rendering) and SSG (Static Site Generation) applications, thanks to its full-stack capabilities, automatic static asset generation, and robust component system. With the release of Vue 3.0 and its new Composition API features, Nuxt 3 offers a lighter and more efficient development experience. This article provides a detailed guide on how to create a new Nuxt.js project based on Vue 3 from scratch, analyzing key configuration steps.

Environment Preparation and Scaffold Commands

Before starting a new project, ensure that your system has Node.js installed (recommended version is LTS 18.x or higher) and the npm package manager. Nuxt provides convenient command-line tools to automate the initialization process, which not only generates a standard project structure but also automatically configures necessary dependencies and build scripts.

Open your terminal, navigate to the directory where you wish to store the project, and then execute the following command:

npx nuxi@latest init my-nuxt-app --vue --typescript

This instruction will automatically complete the following steps:

  • Create skeleton files for the project (such as package.json, tsconfig.json).
  • Install core dependency libraries.
  • Initialize a Git repository and add .gitignore rules to exclude sensitive or meaningless files like node_modules and .nux.

Key Configuration Files Analysis and Build Strategy

Upon completion, several crucial configuration files will be generated in the root directory of your project. Understanding the structure of these files is central to mastering Nuxt 3.

package.json

This is the core for dependency management. In a Vue 3 + Nuxt 3 project, you will find the following key packages listed under devDependencies:

  • nuxi: A tool used for project initialization and some CLI tasks.
  • @vue/cli-service: While primarily used for starting local development servers (e.g., npm run dev), it is sometimes retained to maintain compatibility with Vue CLI build logic; however, Nuxt 3 primarily relies on its own nuxi command for compilation and bundling.

nuxt.config.ts

This is the most important configuration file for defining project behavior. Nuxt allows you to configure options at multiple levels (such as server, app, runtimeConfig), but usually, focusing on top-level configurations will satisfy most requirements:

// nuxt.config.ts
export default defineNuxtConfig({
  compatibilityDate: '2024-01-01', // Ensure compatibility with Vue 3.5+ features
  
  devtools: { enabled: true },    // Enable development tools to assist in debugging components and performance monitoring

  app: {
    head: {
      title: 'My Nuxt App',        // Set the page title
      meta: [
        { name: 'description', content: 'A Vue 3 + Nuxt 3 project' }
      ]
    }
  },

  ssr: false                     // Optional: Set to true to enable Server-Side Rendering, default is true
  
})

It is worth noting that the compatibilityDate field is used for backward compatibility with older browser and framework features. For users of Vue 3.5+, it is recommended to set this to the current date or an earlier release date to activate new APIs (such as <script setup>).

tsconfig.json & vite.config.ts

Since Nuxt 3 uses Vite as its build tool by default instead of Webpack, you need to pay attention to vite.config.ts. This file allows you to customize optimization strategies, plugin loading order, and resource processing logic. For example, you can configure aliases for specific files or add additional loader rules here:

// vite.config.ts (partial example)
import { defineConfig } from 'vite'

export default defineConfig({
  resolve: {
    alias: {
      '@': '/src', // Map @ paths to the src directory for easier component imports
    },
  },
})

Development Mode vs. Production Build Differences

When iterating quickly locally, you typically run npm run dev. This command starts the Vite server and provides Hot Module Replacement (HMR), allowing developers to see code changes in real-time. However, before deploying to a production environment, you must perform a build operation to generate optimized static files:

npx nuxi build

This process reads configurations from vite.config.ts and nuxt.config.ts, compresses resources, merges CSS, optimizes images, and so on, finally outputting the results to the .output directory (located in the root by default). This step is crucial for improving first-paint loading speed and reducing bundle size.

Summary and Best Practice Recommendations

Through the process outlined above, you have successfully set up a foundational architecture for a Nuxt.js project compliant with Vue 3 standards. In actual development, we recommend always adhering to the following habits:

  1. Unified Type Definitions: Leverage TypeScript's powerful static analysis capabilities to reduce runtime errors and improve code maintainability.
  2. Modular Component Design: Fully utilize built-in components like Nuxt's <NuxtLink> and <NuxtPage> to simplify routing and navigation logic.
  3. Continuous Integration Preparation: Configure CI/CD-related scripts (such as lint, test) in package.json to lay the groundwork for automated deployment.

Mastering these core concepts and operational steps will provide a solid foundation for delving deeper into advanced Nuxt.js features (such as API Routes, Middleware, Store).