Getting Started & Setup

Relevant source files

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

• README.md
• CONTRIBUTING.md
• packages/schema/src/types/schema.ts
• packages/nuxt/src/core/app.ts
• packages/nuxt/src/core/templates.ts
• packages/nuxt/test/app.test.ts
• packages/nuxt/src/pages/module.ts

Nuxt is an open-source framework designed to provide an intuitive and extendable environment for creating type-safe, performant, and production-grade full-stack web applications using Vue.js. It automates repetitive development tasks such as routing, component registration, and configuration, allowing developers to focus on application logic.

Sources: README.md:15-20

Project Initialization

To create a new Nuxt starter project, the framework provides a CLI-based initialization command. This process generates the necessary file structure and dependency mappings required for a functional application.

npm create nuxt@latest <my-project>

Alternatively, developers can use nuxt.new to open starters in online environments like CodeSandbox or StackBlitz for rapid prototyping.

Sources: README.md:43-49

Developer Environment Setup (Framework Contribution)

For contributors working directly on the Nuxt framework codebase, a specific sequence of commands is required to prepare the monorepo environment:

1. Node.js & Corepack: Ensure the latest Node.js version is installed and enable Corepack using corepack enable.
2. Install Dependencies: Run pnpm install --frozen-lockfile to ensure consistent dependency versions across the monorepo.
3. Prepare Environment: Execute pnpm dev:prepare to generate necessary build artifacts and types required for local development.

Sources: CONTRIBUTING.md:9-15

Core Architecture & Directory Structure

Nuxt operates on a convention-over-configuration basis, where the file system structure dictates the application behavior. The root of the application is defined by rootDir, while the actual source files reside in srcDir.

Directory Mapping

The following table summarizes the primary directories utilized during the setup and execution of a Nuxt application:

Directory	Configuration Key	Purpose
app/	dir.app	Contains the main application logic, including app.vue and app.config.ts.
assets/	dir.assets	Stores uncompiled assets like styles and images (aliased as ~assets).
components/	components	Automated registration of Vue components.
layouts/	dir.layouts	Templates for page structures, automatically registered.
middleware/	dir.middleware	Navigation guards for page routing.
pages/	dir.pages	Defines application routes based on file structure.
plugins/	dir.plugins	JavaScript/TypeScript files for extending Nuxt functionality.
server/	serverDir	Nitro server routes, middleware, and backend logic.
public/	dir.public	Static files accessible directly via the server.

Sources: packages/schema/src/types/schema.ts:600-660, packages/nuxt/src/core/app.ts:25-30

Component Resolution Flow

During the setup phase, Nuxt runs a resolution pipeline to identify and register key application components. The resolveApp function scans layers and the local directory to populate the NuxtApp object.

The resolution order respects layer priority, where extended layers are processed before the base layer, allowing for component and middleware overrides.

Sources: packages/nuxt/src/core/app.ts:200-250, packages/nuxt/test/app.test.ts:100-150

Configuration Management

The nuxt.config.ts file is the central point for managing application behavior. It allows for the definition of runtime configurations, build-time optimizations, and module integration.

Key Configuration Elements

• Runtime Config: Used to pass environment variables. Private keys are kept on the server, while keys under the public property are exposed to the client.
• App Config: Manages reactive state that is available both on the server and client.
• SSR: A boolean flag (defaulting to true) that determines whether the application should use server-side rendering or operate in SPA mode.

Sources: packages/schema/src/types/schema.ts:500-550, packages/nuxt/src/core/templates.ts:500-530

Build & Template Generation

Nuxt generates internal templates within a Virtual File System (VFS) to bridge the gap between configuration and runtime execution.

Template Filename	Source Function	Description
app-component.mjs	appComponentTemplate	Exports the resolved app.vue.
plugins.client.mjs	clientPluginTemplate	Compiles and sorts client-side plugins.
plugins.server.mjs	serverPluginTemplate	Compiles and sorts server-side plugins.
routes.mjs	addTemplate (in pages module)	Generates the route map from the pages/ directory.

Sources: packages/nuxt/src/core/templates.ts:40-100, packages/nuxt/src/pages/module.ts:550-570

Routing Setup

The pages system is enabled by default if a pages/ directory exists. Nuxt utilizes vue-router and Nitro to manage both client-side and server-side navigation.

If the pages module is disabled or no pages/ directory is found, Nuxt defaults to a universal router that serves the app.vue component at the root path.

Sources: packages/nuxt/src/pages/module.ts:70-120, packages/schema/src/types/schema.ts:60-75

Conclusion

Setting up a Nuxt project involves a combination of CLI-driven initialization and adherence to a predefined directory structure. The framework's core resolution engine automatically wires together components, layouts, and middleware based on their location in the srcDir, while the configuration schema provides granular control over the build and runtime environments.

Sources: README.md:15-20, packages/nuxt/src/core/app.ts:200-210