0
# Nuxt Vite Builder
1

2
The Nuxt Vite Builder is the official bundling solution for Nuxt applications, providing seamless integration between Nuxt's full-stack framework and Vite's fast development server and optimized production builds. It handles both client-side and server-side rendering, CSS processing, asset management, and complex plugin orchestration for modern Vue.js applications.
3

4
## Package Information
5

6
- **Package Name**: @nuxt/vite-builder
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: Automatically included with Nuxt 3+, no manual installation required
10

11
## Core Imports
12

13
```typescript
14
import { bundle, type ViteBuildContext } from "@nuxt/vite-builder";
15
```
16

17
For CommonJS environments:
18

19
```javascript
20
const { bundle } = require("@nuxt/vite-builder");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import type { Nuxt } from "@nuxt/schema";
27
import { bundle } from "@nuxt/vite-builder";
28

29
// Bundle a Nuxt application
30
await bundle(nuxt);
31
```
32

33
## Architecture
34

35
The Nuxt Vite Builder is organized around several key systems:
36

37
- **Dual Build System**: Separate client and server build pipelines optimized for their respective environments
38
- **Plugin Ecosystem**: Extensive Vite plugin integration for Vue SFC compilation, CSS processing, and asset handling
39
- **Development Server**: Hot module replacement and fast refresh during development
40
- **Production Optimization**: Code splitting, minification, and manifest generation for optimal performance
41
- **SSR Integration**: Server-side rendering support with seamless client hydration
42
- **CSS Pipeline**: PostCSS integration with plugin support and style extraction/inlining
43

44
## Capabilities
45

46
### Main Bundling
47

48
Core bundling functionality that orchestrates the entire build process for both client and server targets.
49

50
```typescript { .api }
51
/**
52
 * Main bundling function for Nuxt applications using Vite
53
 * @param nuxt - Nuxt instance containing configuration and build context
54
 */
55
function bundle(nuxt: Nuxt): Promise<void>;
56

57
interface ViteBuildContext {
58
  /** Nuxt application instance */
59
  nuxt: Nuxt;
60
  /** Vite configuration object */
61
  config: ViteConfig;
62
  /** Application entry point file path */
63
  entry: string;
64
  /** Optional Vite development server for client builds */
65
  clientServer?: ViteDevServer;
66
  /** Optional Vite development server for SSR builds */
67
  ssrServer?: ViteDevServer;
68
}
69
```
70

71
[Main Bundling](./main-bundling.md)
72

73
### Client Building
74

75
Client-side build pipeline handling browser-optimized bundles, CSS processing, and development server setup.
76

77
```typescript { .api }
78
/**
79
 * Build client-side assets with Vite
80
 * @param nuxt - Nuxt instance
81
 * @param ctx - Vite build context
82
 */
83
function buildClient(nuxt: Nuxt, ctx: ViteBuildContext): Promise<void>;
84
```
85

86
[Client Building](./client-building.md)
87

88
### Server Building
89

90
Server-side build pipeline for SSR support, optimized for Node.js runtime with external dependency handling.
91

92
```typescript { .api }
93
/**
94
 * Build server-side assets for SSR
95
 * @param nuxt - Nuxt instance  
96
 * @param ctx - Vite build context
97
 */
98
function buildServer(nuxt: Nuxt, ctx: ViteBuildContext): Promise<void>;
99
```
100

101
[Server Building](./server-building.md)
102

103
### CSS Processing
104

105
PostCSS integration and CSS handling for both development and production builds.
106

107
```typescript { .api }
108
/**
109
 * Resolve CSS processing options including PostCSS plugins
110
 * @param nuxt - Nuxt instance with PostCSS configuration
111
 * @returns Vite CSS configuration object
112
 */
113
function resolveCSSOptions(nuxt: Nuxt): Promise<ViteConfig['css']>;
114
```
115

116
[CSS Processing](./css-processing.md)
117

118
### Plugin System
119

120
Comprehensive Vite plugin system providing specialized functionality for Nuxt applications.
121

122
```typescript { .api }
123
/**
124
 * SSR styles plugin for CSS extraction and inlining
125
 * @param options - Plugin configuration options
126
 * @returns Vite plugin instance
127
 */
128
function SSRStylesPlugin(options: SSRStylesPluginOptions): Plugin;
129

130
/**
131
 * Public directories plugin for asset resolution
132
 * @param options - Plugin configuration options
133
 * @returns Array of Vite plugin instances
134
 */
135
function PublicDirsPlugin(options: VitePublicDirsPluginOptions): Plugin[];
136
```
137

138
[Plugin System](./plugin-system.md)
139

140
### Development Server
141

142
Development server integration with hot module replacement, file watching, and CORS handling.
143

144
```typescript { .api }
145
/**
146
 * Vite-node plugin for SSR development
147
 * @param nuxt - Nuxt instance
148
 * @returns Vite plugin instance
149
 */
150
function ViteNodePlugin(nuxt: Nuxt): Plugin;
151

152
/**
153
 * Write development server configuration
154
 * @param nuxt - Nuxt instance
155
 */
156
function writeDevServer(nuxt: Nuxt): Promise<void>;
157
```
158

159
[Development Server](./development-server.md)
160

161
### Manifest Generation
162

163
Client and server manifest generation for optimal asset loading and bundle resolution.
164

165
```typescript { .api }
166
/**
167
 * Write client and server manifests for bundle resolution
168
 * @param ctx - Vite build context
169
 */
170
function writeManifest(ctx: ViteBuildContext): Promise<void>;
171
```
172

173
[Manifest Generation](./manifest-generation.md)
174

175
## Core Types
176

177
```typescript { .api }
178
interface ViteBuildContext {
179
  /** Nuxt application instance */
180
  nuxt: Nuxt;
181
  /** Vite configuration object */
182
  config: ViteConfig;
183
  /** Application entry point file path */
184
  entry: string;
185
  /** Optional Vite development server for client builds */
186
  clientServer?: ViteDevServer;
187
  /** Optional Vite development server for SSR builds */
188
  ssrServer?: ViteDevServer;
189
}
190

191
interface SSRStylesPluginOptions {
192
  /** Source directory path */
193
  srcDir: string;
194
  /** Set of chunk IDs with inlined CSS */
195
  chunksWithInlinedCSS: Set<string>;
196
  /** Function or boolean determining if styles should be inlined */
197
  shouldInline?: ((id?: string) => boolean) | boolean;
198
  /** Array of Nuxt component definitions */
199
  components: Component[];
200
  /** Mapping of CSS files to chunks */
201
  clientCSSMap: Record<string, Set<string>>;
202
  /** Application entry point */
203
  entry: string;
204
  /** Global CSS file paths */
205
  globalCSS: string[];
206
  /** Build mode: server or client */
207
  mode: 'server' | 'client';
208
}
209

210
interface VitePublicDirsPluginOptions {
211
  /** Development mode flag */
212
  dev?: boolean;
213
  /** Base URL for public assets */
214
  baseURL?: string;
215
}
216
```