0
# Client Building
1

2
Client-side build pipeline handling browser-optimized bundles, CSS processing, and development server setup for Nuxt applications.
3

4
## Capabilities
5

6
### Build Client Function
7

8
Creates browser-optimized builds with development server integration for client-side assets.
9

10
```typescript { .api }
11
/**
12
 * Build client-side assets with Vite
13
 * Handles browser-specific configuration, development server setup, and production optimization
14
 * @param nuxt - Nuxt instance with client configuration
15
 * @param ctx - Vite build context containing entry and config
16
 */
17
function buildClient(nuxt: Nuxt, ctx: ViteBuildContext): Promise<void>;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { buildClient } from "@nuxt/vite-builder/client";
24
import type { ViteBuildContext } from "@nuxt/vite-builder";
25

26
// Called internally by bundle(), but can be used directly
27
const ctx: ViteBuildContext = {
28
  nuxt,
29
  config: viteConfig,
30
  entry: './app/entry.client.ts'
31
};
32

33
await buildClient(nuxt, ctx);
34
```
35

36
### Client Configuration
37

38
The buildClient function applies browser-specific Vite configuration.
39

40
**Key Configuration Areas:**
41

42
```typescript
43
// Client-specific configuration applied
44
const clientConfig = {
45
  define: {
46
    'process.server': false,
47
    'process.client': true,
48
    'process.browser': true,
49
    'import.meta.server': false,
50
    'import.meta.client': true,
51
    'import.meta.browser': true,
52
  },
53
  optimizeDeps: {
54
    entries: [ctx.entry],
55
    exclude: [
56
      // Vue ecosystem packages excluded from optimization
57
      'vue', '@vue/runtime-core', '@vue/runtime-dom',
58
      'vue-router', 'nuxt', 'nuxt/app',
59
      // Nuxt dependencies
60
      '@unhead/vue', 'consola', 'defu', 'h3', 'ofetch'
61
    ]
62
  },
63
  build: {
64
    sourcemap: nuxt.options.sourcemap.client,
65
    manifest: 'manifest.json',
66
    outDir: resolve(nuxt.options.buildDir, 'dist/client'),
67
    rollupOptions: {
68
      input: { entry: ctx.entry }
69
    }
70
  }
71
};
72
```
73

74
### Development Server
75

76
In development mode, buildClient creates and configures a Vite development server.
77

78
```typescript { .api }
79
/**
80
 * Vite development server created for client builds
81
 * Provides HMR, file watching, and middleware integration
82
 */
83
interface ViteDevServer {
84
  /** Middleware stack for handling requests */
85
  middlewares: Connect.Server;
86
  /** Module graph for dependency tracking */
87
  moduleGraph: ModuleGraph;
88
  /** Close the development server */
89
  close(): Promise<void>;
90
}
91
```
92

93
**Development Server Features:**
94

95
- **Hot Module Replacement**: Instant updates without full page reload
96
- **File Watching**: Automatic rebuild on source changes  
97
- **Middleware Mode**: Integration with Nuxt's server middleware
98
- **CORS Handling**: Configurable cross-origin request support
99
- **Static Asset Serving**: Automatic serving of public assets
100

101
**Development Server Example:**
102

103
```typescript
104
// Development server is automatically created and configured
105
// Access via build context after buildClient() completes
106
if (nuxt.options.dev && ctx.clientServer) {
107
  // Server is available for middleware integration
108
  const viteMiddleware = defineEventHandler(async (event) => {
109
    // Vite handles the request through its middleware stack
110
    await new Promise((resolve, reject) => {
111
      ctx.clientServer!.middlewares.handle(event.node.req, event.node.res, (err) => {
112
        err ? reject(err) : resolve(null);
113
      });
114
    });
115
  });
116
}
117
```
118

119
### Production Build
120

121
In production mode, buildClient generates optimized static assets.
122

123
**Production Features:**
124

125
- **Code Splitting**: Automatic chunk optimization for better caching
126
- **Asset Optimization**: Minification, compression, and fingerprinting
127
- **Manifest Generation**: Asset manifest for efficient loading
128
- **Sourcemap Generation**: Optional sourcemaps for debugging
129

130
```typescript
131
// Production build output structure
132
// .nuxt/dist/client/
133
//   ├── manifest.json          // Asset manifest
134
//   ├── [hash].js             // Entry chunks
135
//   ├── assets/[hash].css     // Extracted CSS
136
//   └── assets/[hash].[ext]   // Static assets
137
```
138

139
### Client-Specific Plugins
140

141
The buildClient function registers several client-specific Vite plugins.
142

143
```typescript { .api }
144
/**
145
 * Development style SSR plugin for client builds
146
 * @param options - Plugin configuration for style handling
147
 * @returns Vite plugin instance
148
 */
149
function DevStyleSSRPlugin(options: {
150
  srcDir: string;
151
  buildAssetsURL: string;
152
}): Plugin;
153

154
/**
155
 * Runtime paths plugin for asset URL resolution
156
 * @returns Vite plugin instance  
157
 */
158
function RuntimePathsPlugin(): Plugin;
159

160
/**
161
 * Module preload polyfill for older browsers
162
 * @returns Vite plugin instance
163
 */
164
function ModulePreloadPolyfillPlugin(): Plugin;
165

166
/**
167
 * Stable entry plugin for consistent chunk hashing
168
 * @param nuxt - Nuxt instance
169
 * @returns Vite plugin instance
170
 */
171
function StableEntryPlugin(nuxt: Nuxt): Plugin;
172
```
173

174
### Asset Handling
175

176
Client builds handle various asset types with specific processing.
177

178
**Asset Types Processed:**
179

180
- **Vue Components**: SFC compilation with scoped styles
181
- **CSS/SCSS/PostCSS**: Style processing and extraction  
182
- **TypeScript**: Compilation with type checking
183
- **Static Assets**: Copying with fingerprinting
184
- **Images**: Optimization and format conversion (via plugins)
185

186
**Asset Configuration:**
187

188
```typescript
189
// Asset file naming patterns
190
const assetConfig = {
191
  chunkFileNames: nuxt.options.dev ? undefined : '[hash].js',
192
  entryFileNames: nuxt.options.dev ? 'entry.js' : '[hash].js',
193
  assetFileNames: chunk => 
194
    withoutLeadingSlash(join(nuxt.options.app.buildAssetsDir, 
195
      `${sanitizeFilePath(filename(chunk.names[0]!))}.[hash].[ext]`))
196
};
197
```
198

199
### HMR Configuration
200

201
Hot Module Replacement is configured for optimal development experience.
202

203
```typescript { .api }
204
interface HMRConfig {
205
  /** Protocol for HMR connection (ws/wss) */
206
  protocol?: 'ws' | 'wss';
207
  /** Port for HMR server */
208
  port?: number;
209
  /** Custom HMR server instance */
210
  server?: Server;
211
}
212
```
213

214
**HMR Features:**
215

216
- **Vue SFC Updates**: Instant component updates with state preservation
217
- **CSS Updates**: Style updates without page reload
218
- **Asset Updates**: Dynamic asset replacement
219
- **Error Overlay**: Development error display
220

221
### Bundle Analysis
222

223
Optional bundle analysis integration for production builds.
224

225
```typescript { .api }
226
/**
227
 * Analyze plugin for bundle visualization
228
 * @param nuxt - Nuxt instance with analysis configuration
229
 * @returns Promise resolving to array of Vite plugins
230
 */
231
function AnalyzePlugin(nuxt: Nuxt): Promise<Plugin[]>;
232
```
233

234
**Analysis Configuration:**
235

236
```typescript
237
// Enable in nuxt.config.ts
238
export default defineNuxtConfig({
239
  build: {
240
    analyze: true, // or { enabled: true, ... }
241
  }
242
});
243
```