Build Output & Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Nuxt's build system manages the transformation of source files into a production-ready application bundle. This process involves resolving the application structure (layouts, middleware, plugins), compiling dynamic templates into the Virtual File System (VFS), and configuring asset paths for various deployment environments. The final output is optimized for high performance and compatibility with major hosting providers.
The build process is orchestrated by the generateApp function, which coordinates template compilation and file persistence to the build directory (usually .nuxt). Configuration options such as baseURL and cdnURL allow the generated assets to be served from different locations, facilitating static site generation (SSG) and server-side rendering (SSR) deployment strategies.
Application Structure Resolution
Before assets are bundled, Nuxt must resolve the project's structure across all layers. This includes scanning for layouts, middleware, plugins, and app configurations.
Resolution Logic
The resolveApp function scans configured layer directories to identify the main components and middleware. It prioritizes user-defined files over base framework defaults.
The system uses an "App Structure Version" counter, which is incremented whenever a file is added or removed from watched directories. This prevents redundant re-globbing during development.
Sources: packages/nuxt/src/core/app.ts:33-54, packages/nuxt/src/core/app.ts:200-264
Template Generation & Compilation
Nuxt generates several internal files required for the application to function. These templates bridge the gap between user source code and the framework's runtime logic.
Compilation Pipeline
The generateApp function handles the lifecycle of these templates:
- Normalization: Templates are mapped to their destination paths in the build directory.
- Filtering: Templates are categorized into
preandpost(e.g., plugins declaration) for ordered compilation. - VFS Integration: Compiled contents are first stored in
nuxt.vfsbefore being written to disk. - Sync Write: To avoid cascading Hot Module Replacement (HMR) overhead, all modified templates are written to disk in a single synchronous step.
Sources: packages/nuxt/src/core/app.ts:56-115, packages/nuxt/src/core/app.ts:140-150
Key Build Templates
| Template File | Purpose |
|---|---|
app-component.mjs | Exports the main entry component (e.g., app.vue). |
plugins.client.mjs | Aggregates and sorts all client-side plugins. |
plugins.server.mjs | Aggregates and sorts all server-side plugins. |
paths.mjs | Generates utilities for baseURL and buildAssetsURL. |
components.d.ts | Global TypeScript declarations for all auto-imported components. |
Sources: packages/nuxt/src/core/templates.ts:38-100, packages/nuxt/src/core/templates.ts:504-530
Asset Paths & Deployment Configuration
Nuxt provides granular control over how assets are addressed in production. This is critical for deployments involving Content Delivery Networks (CDNs) or applications hosted under sub-paths.
Path Configuration Options
| Option | Environment Variable | Description |
|---|---|---|
app.baseURL | NUXT_APP_BASE_URL | The base path of the application (e.g., /prefix/). |
app.buildAssetsDir | NUXT_APP_BUILD_ASSETS_DIR | Folder name for built assets, relative to baseURL. |
app.cdnURL | NUXT_APP_CDN_URL | Absolute URL to serve the public folder from. |
Sources: packages/schema/src/types/schema.ts:254-320
Dynamic Path Resolution
During the build, Nuxt generates a paths.mjs template that provides the publicAssetsURL and buildAssetsURL functions. This allows the application to resolve assets correctly even if the environment variables change between build time and runtime.
Sources: packages/nuxt/src/core/templates.ts:504-530, test/dynamic-paths.test.ts:74-120
Bundler Diagnostics
The build system includes specific diagnostics to handle bundler-related failures (Vite, Webpack, or Rspack). These are prefixed with NUXT_B7xxx.
| Code | Reason | Fix |
|---|---|---|
NUXT_B7003 | Server bundle produced multiple entry files. | Avoid using splitChunks in server config. |
NUXT_B7005 | No client entry found in rollup options. | Set vite.build.rollupOptions.input. |
NUXT_B7015 | Payload extraction is disabled. | Set experimental.payloadExtraction to true. |
NUXT_B7020 | Client build manifest is disabled. | Remove build.manifest: false overrides. |
Sources: packages/kit/src/diagnostics/bundler.ts:15-104
Monorepo Release Management
For deployment of the framework itself, Nuxt utilizes a specialized release script that manages package publishing across the monorepo.
Automated Release Flow
The release process utilizes GitHub Actions OIDC tokens to authenticate with the npm registry without long-lived secrets.
Conclusion
Build Output & Deployment in Nuxt is a multi-stage process that prioritizes stability through a robust template compilation pipeline and flexibility via dynamic path configuration. By resolving application structures early and providing clear diagnostics for bundler failures, Nuxt ensures that the final build is optimized for a wide variety of production environments, from standard Node.js servers to CDN-backed static deployments.