Overview

Relevant source files

• .github/logo-light.svg
• .github/logo.svg
• .github/workflows/ci.yml
• .github/workflows/scorecards.yml
• LICENSE
• README.md
• docs/5.community/5.framework-contribution.md
• docs/package.json
• package.json
• packages/kit/package.json
• packages/nuxt/package.json
• packages/rspack/package.json
• packages/schema/package.json
• packages/ui-templates/package.json
• packages/vite/package.json
• packages/webpack/package.json
• pnpm-lock.yaml
• test/bundle.test.ts

Purpose and Scope

This document provides a high-level introduction to the Nuxt framework repository structure, architecture, and core systems. Nuxt is a full-stack web framework built on Vue.js that provides server-side rendering (SSR), static site generation (SSG), file-based routing, auto-imports, and a pluggable module ecosystem.

This page covers the monorepo organization, package relationships, and fundamental architectural patterns. For detailed information about specific subsystems, refer to:

• Configuration and lifecycle: Configuration System, Application Lifecycle
• Build and development: Build System, Development Server
• Routing and pages: Routing and Pages
• Module development: Modules and Extensibility
• Contributing: Contributing

Sources: README.md1-120 packages/nuxt/package.json1-144 docs/5.community/5.framework-contribution.md1-143

Monorepo Structure

The Nuxt repository is organized as a pnpm workspace monorepo containing seven primary packages:

Package	NPM Name	Purpose	Key Exports
packages/nuxt	nuxt	Core framework providing application runtime, modules, and CLI	dist/index.mjs, dist/app/index.js
packages/kit	@nuxt/kit	Toolkit for authoring modules with utilities like defineNuxtModule, addComponent	dist/index.mjs
packages/schema	@nuxt/schema	TypeScript types and configuration defaults shared across packages	dist/index.mjs
packages/vite	@nuxt/vite-builder	Vite bundler integration for development and production builds	dist/index.mjs
packages/webpack	@nuxt/webpack-builder	Webpack 5 bundler integration	dist/index.mjs
packages/rspack	@nuxt/rspack-builder	Rspack bundler integration for faster builds	dist/index.mjs
packages/nitro-server	@nuxt/nitro-server	Server runtime for SSR rendering, API routes, and middleware	dist/index.mjs

Package Dependency Graph

Sources: package.json1-133 pnpm-lock.yaml1-243 packages/nuxt/package.json56-112 packages/kit/package.json26-47 packages/schema/package.json70-76 packages/vite/package.json40-69 packages/webpack/package.json31-75 packages/rspack/package.json31-74

Core Architecture

Framework Layers

Nuxt's architecture consists of four distinct layers:

Sources: packages/nuxt/package.json14-39 packages/kit/package.json1-64 packages/schema/package.json1-80

Request-Response Lifecycle

The following diagram shows how HTTP requests flow through Nuxt's server-side rendering pipeline, mapping to actual code constructs:

Sources: packages/nitro-server/package.json344-425 packages/nuxt/package.json34-39

Core Systems Overview

1. Configuration System

Nuxt uses a layered configuration system with type safety provided by @nuxt/schema:

• nuxt.config.ts: Main configuration file defining modules, build settings, and runtime config
• app.config.ts: Reactive application configuration exposed to both client and server
• Layer merging: Extends configurations via the extends property using c12 package

Sources: packages/schema/package.json70-76 packages/nuxt/package.json67

2. Build System

Nuxt provides three pluggable bundler options:

• Vite (default): Uses vite@^7.3.1 with Environment API for parallel client/server builds
• Webpack: Uses webpack@^5.105.4 with vue-loader@^17.4.2
• Rspack: Uses @rspack/core@^1.7.7 for faster compilation

All builders share common plugins for transformations: TreeShakeComposablesPlugin, UnctxTransformPlugin, DevOnlyPlugin, LayerAliasingPlugin.

Sources: packages/vite/package.json65 packages/webpack/package.json70 packages/rspack/package.json34 pnpm-lock.yaml50-55

3. File-Based Systems

Nuxt automatically discovers and registers application code:

Directory	Purpose	Scanner	Output
pages/	File-based routing	resolvePagesRoutes	routes.mjs via unrouting
components/	Component auto-registration	scanComponents	components.d.ts
composables/	Auto-imports	unimport scanner	imports.d.ts, #imports
plugins/	Plugin registration	resolvePaths	plugins.mjs
middleware/	Route middleware	scanMiddleware	Route guards
layouts/	Layout components	scanLayouts	Layout system

Sources: packages/nuxt/package.json94-111

4. Module System

Nuxt's extensibility is powered by @nuxt/kit, which provides:

• defineNuxtModule: Type-safe module definition with metadata and setup hooks
• Template generation: addTemplate, addTypeTemplate for virtual files
• Component registration: addComponent, addComponentsDir
• Auto-imports: addImports, addImportsDir
• Build plugins: addBuildPlugin, addVitePlugin, addWebpackPlugin
• Server integration: addServerHandler, addServerImports

Sources: packages/kit/package.json26-47

5. Server Runtime

The @nuxt/nitro-server package provides:

• SSR rendering: defineRenderHandler creates the HTML response
• API routes: Server endpoints in server/api/
• Middleware: Server middleware in server/middleware/
• Payload system: Serialization via devalue@^5.6.3 and @nuxt/devalue@^2.0.2
• Vue SSR: Integration with vue-bundle-renderer@^2.2.0

Sources: packages/nitro-server/package.json344-425

Technology Stack

Core Dependencies

Technology	Version	Purpose
Vue.js	3.5.29	UI framework (pinned via resolutions)
Vue Router	^5.0.3	Client-side routing
Vite	^7.3.1	Default bundler
Webpack	^5.105.4	Alternative bundler
Rspack	^1.7.7	Fast bundler alternative
Nitropack	^2.13.1	Server engine
unimport	^6.0.1	Auto-imports implementation
oxc-parser	^0.116.0	Fast AST parsing for metadata
h3	^1.15.5	HTTP server framework
unhead	^2.1.10	Head management

Sources: package.json43-56 pnpm-lock.yaml7-19 packages/nuxt/package.json56-112

Development Tools

The repository uses a comprehensive CI/CD pipeline:

CI Configuration:

• Test matrix: ubuntu-24.04-arm and windows-latest across multiple configurations
• Builders tested: vite, vite-env-api, webpack, rspack
• Test environments: dev (development) and built (production)
• Additional matrices: async/default context, manifest-on/manifest-off, json/js payload

Sources: .github/workflows/ci.yml1-490 test/bundle.test.ts1-178

Package Management

• Workspace: pnpm workspace with pnpm@10.30.3
• Build tool: obuild@0.4.31 for package building
• Type checking: vue-tsc@3.2.5 with strict TypeScript
• Testing: vitest@4.0.18 for unit tests, @playwright/test@1.58.2 for E2E

Sources: package.json130 pnpm-lock.yaml1-243

Development Workflow

Local Setup

1. Install dependencies: pnpm install --frozen-lockfile
2. Build packages: pnpm dev:prepare (generates types and stubs packages)
3. Development: pnpm dev (runs playground with HMR)
4. Testing: pnpm test (runs all test suites)
5. Type checking: pnpm typecheck (Vue TSC validation)

Key Scripts

Script	Command	Purpose
dev:prepare	pnpm --filter './packages/**' build:stub && nuxt prepare	Stub packages and generate types
build	pnpm --filter './packages/**' prepack	Build all packages
test:fixtures	vitest run --project fixtures	Run fixture tests
test:e2e	playwright test	Run end-to-end tests
test:types	pnpm --filter './test/fixtures/**' test:types	Type check fixtures

Sources: package.json10-42 docs/5.community/5.framework-contribution.md18-96

Application Entry Points

CLI Entry

The nuxi CLI is the primary interface for developers:

Sources: packages/nuxt/package.json14-17

Application Runtime

The #app alias provides the client-side runtime:

• #app/nuxt: Core NuxtApp instance and composables
• #app/composables: Built-in composables like useFetch, useRoute, useState
• dist/app/index.js: Main application bundle export

Sources: packages/nuxt/package.json34-39

Module Ecosystem

Nuxt supports 300+ community modules for extending functionality. Modules use the @nuxt/kit APIs to:

• Register components: addComponent({ name: 'MyComponent', filePath: './component.vue' })
• Add composables: addImports({ name: 'useMyComposable', from: './composable' })
• Generate types: addTypeTemplate({ filename: 'types/my-module.d.ts', getContents: () => '...' })
• Extend pages: extendPages((pages) => { /* modify routes */ })
• Add build plugins: addVitePlugin(() => myPlugin())

Sources: README.md26 packages/kit/package.json1-64

License and Community

• License: MIT License (Copyright 2016-present Nuxt Team)
• Repository: https://github.com/nuxt/nuxt
• Documentation: https://nuxt.com/docs
• Security: OpenSSF Scorecard monitored via GitHub Actions

Sources: LICENSE1-22 README.md1-120 .github/workflows/scorecards.yml1-75