0
# Development Server
1

2
Development server integration with hot module replacement, file watching, CORS handling, and seamless SSR development support.
3

4
## Capabilities
5

6
### Vite-Node Plugin
7

8
Integrates vite-node for seamless SSR development with hot module replacement and server-side transformations.
9

10
```typescript { .api }
11
/**
12
 * Vite-node plugin for SSR development
13
 * Provides seamless SSR development with hot module replacement for server code
14
 * @param nuxt - Nuxt instance with development configuration
15
 * @returns Vite plugin instance for vite-node integration
16
 */
17
function ViteNodePlugin(nuxt: Nuxt): Plugin;
18
```
19

20
**Usage Example:**
21

22
```typescript
23
import { ViteNodePlugin } from "@nuxt/vite-builder/vite-node";
24
import type { Nuxt } from "@nuxt/schema";
25

26
// Used internally during client build setup
27
const plugin = ViteNodePlugin(nuxt);
28

29
// Enables:
30
// - Server-side hot module replacement
31
// - Real-time server code transformation
32
// - Seamless SSR development experience
33
```
34

35
### Development Server Writer
36

37
Configures and writes development server configuration for Nitro integration.
38

39
```typescript { .api }
40
/**
41
 * Write development server configuration
42
 * Creates development server setup for Nitro integration with proper middleware
43
 * @param nuxt - Nuxt instance with server configuration
44
 */
45
function writeDevServer(nuxt: Nuxt): Promise<void>;
46
```
47

48
**Development Server Features:**
49

50
- **Nitro Integration**: Seamless integration with Nuxt's server engine
51
- **Middleware Support**: Full support for server middleware during development
52
- **API Routes**: Automatic handling of API routes in development
53
- **File Watching**: Automatic server restart on configuration changes
54

55
### Vite-Node Request Handling
56

57
Sophisticated request/response system for vite-node communication during development.
58

59
```typescript { .api }
60
/**
61
 * Vite-Node request mapping interface
62
 * Defines request/response types for vite-node communication
63
 */
64
interface ViteNodeRequestMap {
65
  /** Manifest request for client bundle information */
66
  manifest: {
67
    request: undefined;
68
    response: Manifest;
69
  };
70
  /** Invalidation request for cache clearing */
71
  invalidates: {
72
    request: undefined;
73
    response: string[];
74
  };
75
  /** Module resolution request */
76
  resolve: {
77
    request: { id: string; importer?: string };
78
    response: ResolveIdResponse | null;
79
  };
80
  /** Module transformation request */
81
  module: {
82
    request: { moduleId: string };
83
    response: FetchResult;
84
  };
85
}
86

87
/**
88
 * Request type helper for vite-node requests
89
 */
90
type RequestOf = {
91
  [K in keyof ViteNodeRequestMap]: {
92
    id: number;
93
    type: K;
94
    payload: ViteNodeRequestMap[K]['request'];
95
  };
96
}[keyof ViteNodeRequestMap];
97
```
98

99
### Server Socket Communication
100

101
Socket-based communication system for real-time development server updates.
102

103
```typescript { .api }
104
/**
105
 * Vite-Node server for handling SSR transformations
106
 * Manages server-side module transformations and caching
107
 */
108
class ViteNodeServer {
109
  /** Transform server-side modules */
110
  transformRequest(id: string): Promise<FetchResult>;
111
  /** Resolve module dependencies */
112
  resolveId(id: string, importer?: string): Promise<ResolveIdResponse | null>;
113
  /** Invalidate module cache */
114
  invalidateModule(id: string): void;
115
}
116
```
117

118
**Socket Features:**
119

120
- **Real-time Updates**: Instant communication between client and server
121
- **Module Invalidation**: Efficient cache invalidation for changed modules  
122
- **Error Propagation**: Real-time error reporting from server to client
123
- **Performance Monitoring**: Request/response timing and performance metrics
124

125
### Hot Module Replacement
126

127
Advanced HMR system for both client and server-side code during development.
128

129
```typescript { .api }
130
/**
131
 * HMR configuration for development server
132
 */
133
interface HMRConfig {
134
  /** HMR protocol (ws/wss) */
135
  protocol?: 'ws' | 'wss';
136
  /** HMR server port */
137
  port?: number;
138
  /** Custom HMR server instance */
139
  server?: Server;
140
  /** HMR client options */
141
  clientPort?: number;
142
}
143
```
144

145
**HMR Features:**
146

147
- **Vue SFC Updates**: Instant Single File Component updates with state preservation
148
- **Server Code Updates**: Hot replacement of server-side code without restart
149
- **CSS Updates**: Style updates without page reload
150
- **Asset Updates**: Dynamic replacement of static assets
151
- **Error Recovery**: Automatic error recovery and state restoration
152

153
### Development Middleware
154

155
Middleware system for integrating Vite development server with Nuxt's request handling.
156

157
```typescript { .api }
158
/**
159
 * Development middleware handler
160
 * Integrates Vite dev server with Nuxt's middleware system
161
 */
162
interface DevMiddleware {
163
  /** Handle incoming requests through Vite middleware */
164
  handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
165
  /** Skip Vite transformation for specific requests */
166
  skipTransform(req: IncomingMessage & { _skip_transform?: boolean }): void;
167
}
168
```
169

170
**Middleware Features:**
171

172
- **Request Routing**: Intelligent routing between Vite and Nuxt handlers
173
- **Asset Serving**: Automatic serving of development assets
174
- **API Integration**: Seamless API route handling during development
175
- **CORS Support**: Configurable cross-origin request handling
176

177
### File Watching
178

179
Advanced file watching system for automatic rebuilds and hot updates.
180

181
```typescript { .api }
182
/**
183
 * File watching configuration
184
 */
185
interface WatchOptions {
186
  /** Files and directories to watch */
187
  include?: string[];
188
  /** Files and directories to ignore */
189
  exclude?: string[];
190
  /** Chokidar options for file watching */
191
  chokidar?: ChokidarOptions;
192
}
193
```
194

195
**File Watching Features:**
196

197
- **Smart Watching**: Only watches relevant files for better performance
198
- **Ignore Patterns**: Configurable ignore patterns for node_modules, etc.
199
- **Debouncing**: Intelligent debouncing to prevent excessive rebuilds
200
- **Cross-platform**: Consistent behavior across Windows, macOS, and Linux
201

202
### Development Performance
203

204
Performance optimizations specifically for development experience.
205

206
**Performance Features:**
207

208
- **Lazy Loading**: Modules loaded on-demand during development
209
- **Incremental Builds**: Only rebuild changed modules
210
- **Memory Management**: Efficient memory usage for long development sessions
211
- **Caching Strategy**: Intelligent caching of transformations and dependencies
212

213
### Error Handling
214

215
Comprehensive error handling and developer experience improvements.
216

217
```typescript { .api }
218
/**
219
 * Development error information
220
 */
221
interface DevError {
222
  /** Error message */
223
  message: string;
224
  /** Error stack trace */
225
  stack?: string;
226
  /** File location of error */
227
  loc?: { file: string; line: number; column: number };
228
  /** Error type/category */
229
  type: 'transform' | 'resolve' | 'syntax' | 'runtime';
230
}
231
```
232

233
**Error Handling Features:**
234

235
- **Error Overlay**: Visual error overlay in browser during development
236
- **Source Maps**: Accurate error location mapping with source maps
237
- **Recovery Mechanisms**: Automatic recovery from non-fatal errors
238
- **Clear Messaging**: Human-readable error messages with context
239

240
### Development Utilities
241

242
Utility functions for development server management and debugging.
243

244
```typescript { .api }
245
/**
246
 * Warmup Vite server with entry files
247
 * Pre-transforms entry files for faster initial loading
248
 * @param server - Vite development server
249
 * @param entries - Array of entry file paths
250
 * @param isServer - Whether this is for server-side code
251
 */
252
function warmupViteServer(
253
  server: ViteDevServer, 
254
  entries: string[], 
255
  isServer: boolean
256
): Promise<void>;
257

258
/**
259
 * Create custom Vite logger
260
 * Creates logger with Nuxt-specific formatting and filtering
261
 * @param config - Vite configuration
262
 * @param options - Logger options
263
 * @returns Custom logger instance
264
 */
265
function createViteLogger(
266
  config: ViteConfig, 
267
  options?: { hideOutput?: boolean }
268
): Logger;
269
```
270

271
### Development Configuration
272

273
Development-specific configuration options and defaults.
274

275
```typescript
276
// Development server configuration
277
const devConfig = {
278
  server: {
279
    middlewareMode: true,
280
    warmup: {
281
      clientFiles: [ctx.entry],
282
      ssrFiles: [serverEntry]
283
    },
284
    watch: {
285
      ...nuxt.options.watchers.chokidar,
286
      ignored: [isIgnored, /[\\/]node_modules[\\/]/]
287
    },
288
    fs: {
289
      allow: [...new Set(allowDirs)]
290
    }
291
  }
292
};
293
```
294

295
### Integration Points
296

297
Key integration points with other Nuxt systems during development.
298

299
**Integration Features:**
300

301
- **Nuxt DevTools**: Integration with Nuxt DevTools for debugging
302
- **Vue DevTools**: Support for Vue DevTools browser extension
303
- **TypeScript**: Real-time TypeScript compilation and error reporting
304
- **ESLint**: Integration with ESLint for code quality checking
305
- **Testing**: Support for testing frameworks during development