This document provides an architectural overview of the Nuxt framework repository located at https It introduces the repository structure, core packages, build pipeline, and runtime architecture. For detailed information about the monorepo organization, see Monorepo Structure. For setup instructions, see Getting Started. For contribution guidelines, see Contributing.
The Nuxt repository is a pnpm-managed monorepo that implements a Vue.js meta-framework for building server-side rendered, static, and hybrid web applications. The repository contains the core framework (nuxt), module authoring toolkit (@nuxt/kit), type definitions (@nuxt/schema), and three pluggable build systems (Vite, Webpack, Rspack).
Sources: package.json1-151 README.md1-120
The Nuxt repository is structured as a monorepo containing multiple interdependent packages published to npm. The workspace is managed by pnpm and defined in the root package.json.
Package Responsibilities:
| Package | Directory | Purpose | Key Exports |
|---|---|---|---|
nuxt | packages/nuxt | Core framework runtime and build orchestration | defineNuxtConfig, createNuxt, built-in modules |
@nuxt/kit | packages/kit | Module authoring utilities | defineNuxtModule, addComponent, addTemplate |
@nuxt/schema | packages/schema | TypeScript definitions and configuration schema | Type definitions, default config values |
@nuxt/nitro-server | packages/nitro-server | SSR rendering engine | Server rendering utilities, payload serialization |
@nuxt/vite-builder | packages/vite | Vite bundler integration | Vite build configuration and plugins |
@nuxt/webpack-builder | packages/webpack | Webpack bundler integration | Webpack build configuration and loaders |
@nuxt/rspack-builder | packages/rspack | Rspack bundler integration | Rspack build configuration |
Sources: package.json1-151 packages/nuxt/package.json1-142 packages/kit/package.json1-64 packages/schema/package.json1-80 docs/5.community/5.framework-contribution.md10-16
The Nuxt framework follows a distinct lifecycle from configuration loading to production deployment:
Sources: packages/nuxt/package.json55-112
The build process transforms source code into optimized client and server bundles. The bundler selection is configurable and defaults to Vite.
Build Command Flow:
Key Build Directories:
| Directory | Purpose | Generated By |
|---|---|---|
.nuxt/ | Build-time virtual file system | addTemplate(), core modules |
.nuxt/types/ | TypeScript declarations | Type generation system |
.output/public/ | Static client assets | Bundler (Vite/Webpack/Rspack) |
.output/server/ | Server-side code | Nitro build |
Sources: package.json11-24 packages/nuxt/package.json50-53 packages/vite/package.json1-83 packages/webpack/package.json1-94
Nuxt applications execute in two contexts: server-side during SSR and client-side after hydration.
Core Runtime Composables:
| Composable | File Location | Purpose |
|---|---|---|
useAsyncData() | packages/nuxt/src/app/composables/asyncData.ts | SSR-safe data fetching |
useFetch() | packages/nuxt/src/app/composables/fetch.ts | Wrapper around useAsyncData with $fetch |
useState() | packages/nuxt/src/app/composables/state.ts | Shared reactive state |
useCookie() | packages/nuxt/src/app/composables/cookie.ts | SSR/client cookie management |
useRouter() | packages/nuxt/src/app/composables/router.ts | Vue Router access |
useNuxtApp() | packages/nuxt/src/app/nuxt.ts | Access to NuxtApp instance |
Sources: packages/nuxt/package.json34-38 packages/nitro-server/package.json1-95
Nuxt's extensibility is powered by the module system, which allows third-party packages to integrate with the framework lifecycle.
Module Installation Configuration:
Sources: packages/kit/package.json1-64 packages/nuxt/package.json55-112
Nuxt includes several built-in modules that implement framework features:
| Module | Location | Functionality |
|---|---|---|
nuxt:pages | packages/nuxt/src/pages/ | File-based routing, route generation |
nuxt:components | packages/nuxt/src/components/ | Auto-discovery and registration |
nuxt:imports | packages/nuxt/src/imports/ | Auto-imports for composables |
nuxt:app | packages/nuxt/src/app/ | Core runtime and entry points |
nuxt:router | packages/nuxt/src/pages/ | Vue Router integration |
For detailed information on the pages module, see Pages Module. For components, see Component Discovery and Registration. For the plugin system, see Plugin System.
Sources: packages/nuxt/package.json1-142
The framework supports three bundlers through a pluggable architecture:
Bundler Feature Matrix:
| Feature | Vite | Webpack | Rspack |
|---|---|---|---|
| Default bundler | ✓ | ✗ | ✗ |
| HMR speed | Fast | Medium | Fast |
| Dev server | Vite | webpack-dev-middleware | webpack-dev-middleware |
| Production build | Rollup | Webpack | Rspack |
| Type checking | vite-plugin-checker | fork-ts-checker-webpack-plugin | ts-checker-rspack-plugin |
For detailed build system information, see Build System and Bundler Integration.
Sources: packages/vite/package.json1-83 packages/webpack/package.json1-94 packages/rspack/package.json1-92
Nuxt generates TypeScript declarations during the prepare phase to provide IDE autocomplete and type checking.
Generated Type Files:
| File | Purpose | Generated From |
|---|---|---|
.nuxt/components.d.ts | Global component types | Component scanning |
.nuxt/imports.d.ts | Auto-import declarations | Composables/utils scanning |
.nuxt/types/typed-router.d.ts | Type-safe routing | Pages directory structure |
.nuxt/types/middleware.d.ts | Middleware types | Middleware directory |
.nuxt/nuxt.d.ts | Core Nuxt types | Schema definitions |
For detailed type generation information, see Type Generation.
Sources: package.json14 packages/nuxt/package.json50-53
The repository provides several npm scripts for development, testing, and building:
| Command | Purpose | Implementation |
|---|---|---|
pnpm dev | Start playground dev server | package.json21 |
pnpm dev:prepare | Build packages in stub mode | package.json14 |
pnpm build | Build all packages | package.json11 |
pnpm test | Run full test suite | package.json25 |
pnpm lint | Lint codebase | package.json16 |
pnpm typecheck | TypeScript validation | package.json39 |
Test Suite Structure:
For CI/CD information, see CI/CD Workflows. For local development setup, see Getting Started.
Sources: package.json10-41 test/bundle.test.ts1-174 .github/workflows/ci.yml1-463
The Nuxt framework is built on top of several key technologies:
Core Dependencies:
| Technology | Purpose | Usage in Nuxt |
|---|---|---|
| Vue 3 | UI framework | Component system, reactivity |
| Vue Router | Client-side routing | Navigation, route matching |
| h3 | HTTP server | Request handling, middleware |
| Nitro | Server engine | SSR, API routes, prerendering |
| unimport | Auto-imports | Composable auto-detection |
| unplugin | Build plugins | Cross-bundler transformations |
| c12 | Configuration | Config loading and merging |
| hookable | Event system | Lifecycle hooks |
| devalue | Serialization | Payload serialization |
Build Tools:
Sources: packages/nuxt/package.json55-112 pnpm-lock.yaml1-40
A built Nuxt application produces the following directory structure:
.output/
├── public/ # Static client assets
│ ├── _nuxt/ # Hashed JS/CSS bundles
│ └── ... # Public assets
└── server/ # Server-side code
├── index.mjs # Nitro entry point
├── chunks/ # Server bundle chunks
└── node_modules/ # Production dependencies
Deployment Targets:
The .output/ directory can be deployed to various platforms through Nitro presets:
For deployment configuration, see Configuration System. For SSR architecture details, see Server-Side Rendering.
Sources: test/bundle.test.ts8-154
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.