Monorepo Packages Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Nuxt project is structured as a monorepo containing several specialized packages that together form the framework. This architecture allows for a modular separation of concerns, distinguishing between the core logic, bundler-specific implementations, schema definitions, and developer toolkits. The monorepo uses pnpm for workspace management and dependency handling.
Sources: CONTRIBUTING.md:19-27, README.md:10-30
Core Packages Architecture
The Nuxt monorepo distributes its functionality across several key packages. Each package serves a specific role in the build or runtime lifecycle of a Nuxt application.
Package Responsibilities
| Package | Description | Reference |
|---|---|---|
packages/nuxt | The core framework logic and runtime. | @nuxt/nuxt |
packages/kit | A toolkit for authoring Nuxt modules. | @nuxt/kit |
packages/schema | Cross-version Nuxt type definitions and default configurations. | @nuxt/schema |
packages/vite | The Vite bundler integration for Nuxt. | @nuxt/vite-builder |
packages/webpack | The Webpack bundler integration for Nuxt. | @nuxt/webpack-builder |
packages/rspack | The Rspack bundler integration for Nuxt. | @nuxt/rspack-builder |
Sources: CONTRIBUTING.md:21-27
Dependency Flow
The following diagram illustrates the relationship between the core packages and their typical interaction during the development and build process.
Diagram showing the internal package hierarchy where builders depend on the core nuxt package and its foundational schema and kit.
Sources: CONTRIBUTING.md:21-27, packages/vite/package.json:28-30
Build and Release Systems
The monorepo employs centralized scripts to manage the lifecycle of all packages, ensuring consistent versioning and publishing across the workspace.
Release Process
The release process handles git restoration, version bumping (including nightly releases), README URL normalization for NPM, and trusted publishing via GitHub Actions OIDC.
Sequence diagram of the automated release workflow for monorepo packages.
Sources: scripts/release.ts:114-188
Package Synchronization
Certain packages, like @nuxt/ui-templates, generate assets that are manually copied or baked into other packages (like packages/nuxt or packages/schema) to ensure compatibility without relying solely on symbolic links, particularly for better Windows support.
Sources: packages/ui-templates/lib/render.ts:241-255
Development Workflow
Contributors interact with the monorepo through standardized commands defined at the root and within individual package package.json files.
Common Commands
pnpm dev:prepare: Prepares the development environment and generates necessary types.pnpm dev: Runs the framework in playground mode.pnpm build: Triggers the build process for specific packages (e.g., in@nuxt/vite-builder).pnpm test: Executes the test suite across the monorepo.
Sources: CONTRIBUTING.md:14-15, CONTRIBUTING.md:46-51, packages/vite/package.json:21-22
Bundler Integration: @nuxt/vite-builder
The @nuxt/vite-builder package provides the integration for Vite. It relies on @nuxt/kit and @nuxt/schema while providing exports for vite-node runners and internal source map preservation.
Sources: packages/vite/package.json:11-19, packages/vite/package.json:30-55
Summary
The Nuxt monorepo is a modular ecosystem where packages/nuxt serves as the engine, supported by packages/schema for types and packages/kit for extensibility. Specialized builder packages (vite, webpack, rspack) allow Nuxt to remain bundler-agnostic while providing optimized integrations for each environment. The unified release and script system ensures that these disparate components are synchronized and versioned as a cohesive framework.