Nuxt Tutorial 1 - First Steps

In this first article of a planned tutorial series about the Nuxt framework, I'll show you how easily you can get a working project up and running.

Nuxt Simple

nuxt-simple @ GitHub

At the above link, you'll find the source code for a simple starter project for Nuxt (currently version 4). It's based on the Nuxt Starter on the StackBlitz cloud platform, which you can run and try directly in your browser.

To run Nuxt locally, you'll need to:

• Install the Node.js runtime environment (current LTS version recommended, at least 18.*)
• Download the project using the Git version control tool
• Open it in the VS Code development environment
• Switch to the nuxt-simple folder
• Run pnpm install in the terminal
• Start the application with pnpm dev
• Open http://localhost:3000 in your browser

You'll see a simple page that doesn't do much on its own, but it proves Nuxt is running. We can start building from there. First, let's go through the individual components:

• app/app.vue - the main entry point with a simple template inside <template> (since Nuxt v4, it's located in the /app folder rather than directly in the project root). Unlike the official nuxt-starter, I replaced their <NuxtWelcome> component with custom HTML code, which you'll see rendered on the page when you launch the project.
• public/favicon.ico - an optional image file that adds an icon to the browser tab. The application works without it, but looks better havinh one. It also demonstrates how simple Nuxt can be - just copy your image to this path and you're done, no additional configuration needed.
• README.md - a description file that presents basic information about the project when viewing the GitHub repository. While not required, it's common practice to include this to inform visitors and potential users about your code.
• eslint.config.mjs - this configuration file for the @nuxt/eslint module controls the behavior of ESLint, a tool I added to the project (though it's not in the official nuxt-starter) to monitor syntax rules and help keep your source code clean. It requires some environment setup, which will be covered in a future article. Until configured, it won't cause any issues, but you won't benefit from its code quality assistance either.
• nuxt.config.ts - the main configuration file for Nuxt. By default, it can be completely "empty" - all settings are placed inside the object parameter of the built-in defineNuxtConfig method (which is automatically imported). Currently, it contains the configuration for the @nuxt/eslint module, which works together with eslint.config.mjs to implement ESLint rules.
  • pnpm-lock.yaml - automatically generated by the pnpm package manager during pnpm install, this file maintains an exhaustive definition of all project dependencies. You may encounter opinions that lock files can be omitted from Git since they change frequently and developers generate them locally anyway. However, I follow the recommendation to include them in the repository, as they help ensure consistent builds across all environments. Without it, you might encounter weird errors from developers having slightly different package versions.
• package.json - a key file that primarily defines dependencies on external packages. In our case, this includes nuxt, the ESLint module @nuxt/eslint, and typescript. It also contains project metadata and command definitions in the script section, which can be invoked as pnpm *. These script definitions aren't required, but they make operations more convenient.
• tsconfig.json - allows customization of TypeScript compiler settings that would otherwise be auto-generated. More on this in a future article.

Nuxt Starter

If you want to start your own small Nuxt project, you can find the above setup in a standalone GitHub repository for easier cloning:

nuxt-v4-starter @ GitHub

Nuxt Minimal

nuxt-minimal @ GitHub

This sub-project demonstrates that Nuxt can actually be launched with even less. While not recommended for real projects, the website will run with just these two files:

• app.vue - the basic entry point with a simple template inside <template>
• package.json - in which the dependency on the nuxt package will be declared in devDependencies

Instead of pnpm dev (which would require additional package.json configuration), the application is launched using npx nuxi dev command. Here, npx is an npm tool that runs packages without installing them locally into project, and nuxi is the CLI tool from the Nuxt framework creators.

The remaining two files in the repository - README.md and pnpm-lock.yaml - have already been described above and are technically not required in the repository.

WARNING: This is meant only as a demonstration of minimalism. The absence of standard system components would likely cause problems in real-world use. Stick with the nuxt-simple variant for actual projects.

In the second part of the tutorial, we'll explore the basic building blocks of Nuxt applications: components and pages.